1. 這個問題比選框架更重要為什么“先問一個問題”是智能體開發(fā)的分水嶺我去年下半年開始密集落地智能體項目從內(nèi)部知識助手、銷售話術(shù)生成器到客戶投訴自動歸因系統(tǒng)前后跑了7個真實業(yè)務(wù)線。過程中把 Claude Agent SDK、LangGraph、LangChain、LlamaIndex 甚至自研狀態(tài)機都輪著搭過三遍以上。不是為了炫技而是因為每個項目上線后兩周內(nèi)必遇到同一個卡點流程跑著跑著就“斷”了——不是報錯不是崩潰而是邏輯莫名其妙繞彎、決策反復(fù)橫跳、用戶追問一句就徹底失聯(lián)。直到第三次重構(gòu)一個保險理賠輔助Agent時我把所有代碼刪掉只留一張白紙逼自己寫下第一行字“這個智能體必須在3秒內(nèi)給出可執(zhí)行動作還是必須在5輪對話后輸出結(jié)構(gòu)化結(jié)論”就是這個問題直接決定了后續(xù)所有技術(shù)選型。Claude Agent SDK 的強項是“單步強推理高置信度動作觸發(fā)”它默認假設(shè)你面對的是一個需要快速響應(yīng)、低容錯、高確定性的任務(wù)場景比如客服工單自動分派、實時風(fēng)控攔截、API調(diào)用鏈路兜底而 LangGraph 的設(shè)計哲學(xué)是“狀態(tài)可追溯邊執(zhí)行邊修正”它天然適配那種需要多輪協(xié)商、外部工具調(diào)用不可控、中間狀態(tài)必須人工介入的長周期任務(wù)比如跨部門協(xié)同審批、復(fù)雜合同條款比對、帶人工復(fù)核的財務(wù)報銷流程。很多人一上來就對比“LangChain 和 LangGraph 哪個更火”“Claude Agent SDK 能不能替代 LangChain”這就像問“錘子和電鉆哪個更好用”卻不說明你要裝的是 Ikea 椅子還是承重墻龍骨。真正決定成敗的從來不是框架語法有多優(yōu)雅而是你手里的業(yè)務(wù)問題到底屬于“確定性動作執(zhí)行”還是“不確定性狀態(tài)演進”。前者要的是確定性出口后者要的是可觀測入口。我見過太多團隊花兩個月用 LangGraph 搭了一個銷售線索打標Agent結(jié)果發(fā)現(xiàn)銷售每天只看一眼標簽就扔進CRM根本不需要狀態(tài)回溯——那套復(fù)雜的 checkpoint 機制、state snapshot、interrupt 邏輯全成了性能負擔(dān)。反過來也有團隊用 Claude Agent SDK 做供應(yīng)鏈異常預(yù)警結(jié)果因為無法記錄“第3次觸發(fā)預(yù)警后采購員手動否決了建議”導(dǎo)致系統(tǒng)永遠學(xué)不會規(guī)避誤報最后硬生生加了一層數(shù)據(jù)庫存 state反而把 SDK 的輕量優(yōu)勢全廢了。所以標題里說的“選型先問一個問題”不是玄學(xué)是血淚經(jīng)驗?zāi)毜牟僮骺谠E。它不涉及任何代碼卻能幫你省下至少60%的返工時間。這個問題的答案會像一把尺子立刻把你拉回業(yè)務(wù)本質(zhì)你的智能體到底是“執(zhí)行器”還是“協(xié)作者”執(zhí)行器要快、準、穩(wěn)協(xié)作者要清、可逆、可干預(yù)。接下來所有技術(shù)細節(jié)都只是圍繞這個核心判斷做工程實現(xiàn)。2. 執(zhí)行器 vs 協(xié)作者兩類智能體的本質(zhì)差異與選型邏輯2.1 執(zhí)行器型智能體以 Claude Agent SDK 為典型代表的“確定性出口”范式執(zhí)行器型智能體的核心訴求是在明確約束下完成一次精準的動作交付。它的成功標準非常樸素輸入X輸出YY必須是可被下游系統(tǒng)直接消費的確定值如API參數(shù)、SQL語句、JSON Schema校驗通過的數(shù)據(jù)且整個過程耗時可控通常2秒、失敗率極低0.5%。這類場景常見于企業(yè)內(nèi)部自動化流程比如客服系統(tǒng)收到“我的訂單號123456物流停滯”Agent需在1.8秒內(nèi)調(diào)用物流查詢API解析返回JSON提取“l(fā)ast_update_time”和“status_code”生成結(jié)構(gòu)化告警事件發(fā)往工單系統(tǒng)ERP系統(tǒng)檢測到“采購申請單金額超50萬”Agent需立即調(diào)用風(fēng)控模型API傳入供應(yīng)商歷史履約率、當前賬期余額等字段返回“approved/rejected/escalate_to_finance”三選一結(jié)果并附帶置信度分數(shù)監(jiān)控平臺報警“服務(wù)器CPU持續(xù)95%達5分鐘”Agent需自動執(zhí)行“查進程→殺異常PID→重啟服務(wù)→發(fā)釘釘通知”四步原子操作每步失敗即終止并上報錯誤碼。Claude Agent SDK 正是為這類場景深度優(yōu)化的。它底層強制要求你定義Tool Schema嚴格遵循OpenAPI 3.0規(guī)范每個工具必須聲明輸入?yún)?shù)類型、必填項、枚舉值范圍、輸出格式約束。SDK 在運行時會做三重校驗① LLM生成的tool_call參數(shù)是否符合schema類型、長度、枚舉② 實際調(diào)用返回是否匹配output_schema避免LLM幻覺偽造JSON③ 整個action chain是否在timeout閾值內(nèi)完成默認1.5秒可設(shè)為200ms級。這種“契約式執(zhí)行”帶來的好處是你根本不用寫retry邏輯、不用管state持久化、不用設(shè)計中斷恢復(fù)——因為系統(tǒng)默認不允許“半途而廢”。提示Claude Agent SDK 的tool_call不是簡單函數(shù)調(diào)用而是帶語義校驗的協(xié)議交互。比如你定義一個search_knowledge_base(query: str, category: Literal[policy, product, compliance])工具LLM若生成category: policies拼寫錯誤或category: 123類型錯誤SDK會在調(diào)用前直接拋出ValidationException而不是把錯誤參數(shù)傳給后端——這省去了90%的邊界case處理代碼。2.2 協(xié)作者型智能體以 LangGraph 為典型代表的“可觀測入口”范式協(xié)作者型智能體的核心訴求是在開放約束下維持一段可理解、可干預(yù)、可回溯的協(xié)作過程。它的成功標準不是單次輸出正確而是整個協(xié)作流的透明度和可控性管理者能否看清“為什么Agent選擇了方案A而非B”業(yè)務(wù)人員能否在第4步插入人工審核當?shù)谌紸PI超時系統(tǒng)能否自動降級到備選路徑并記錄決策日志這類場景常見于需要人機混合決策的業(yè)務(wù)比如法務(wù)部審核一份NDA協(xié)議Agent需先提取甲方乙方主體信息再比對歷史模板庫找出差異點接著調(diào)用合規(guī)檢查工具掃描風(fēng)險條款最后生成修訂建議——但法務(wù)專員可能在“比對模板”后要求“先看甲方歷史違約記錄”或在“生成建議”前手動修改某條條款醫(yī)療問診預(yù)篩患者描述癥狀后Agent需逐步追問“疼痛持續(xù)時間”“是否伴隨發(fā)熱”“既往病史”每輪追問都依賴上一輪回答且醫(yī)生可在任意節(jié)點介入覆蓋LLM生成的問題或直接跳轉(zhuǎn)到特定檢查項跨境電商選品Agent需并行調(diào)研目標市場政策、競品定價、物流時效、本地化成本每個維度數(shù)據(jù)源不穩(wěn)定海關(guān)API常超時、爬蟲被封需動態(tài)調(diào)整采集順序并允許運營人員在“政策分析完成”后手動輸入最新法規(guī)解讀。LangGraph 的設(shè)計完全圍繞“狀態(tài)可觀測”展開。它強制你定義State SchemaPydantic BaseModel所有節(jié)點Node的輸入輸出都必須是該Schema的子集。每個節(jié)點執(zhí)行后state會被序列化存入checkpoint支持SQLite/PostgreSQL/Redis你可以隨時調(diào)用graph.get_state(config)查看當前完整狀態(tài)樹包括所有中間變量、工具調(diào)用歷史、LLM原始prompt。更關(guān)鍵的是LangGraph原生支持Human-in-the-loop只需在任意節(jié)點后加.interrupt()系統(tǒng)就會暫停并暴露當前state前端調(diào)用graph.invoke({user_input: 按B方案執(zhí)行}, config)即可繼續(xù)——整個過程無需重啟、不丟失上下文、不破壞state一致性。注意LangGraph 的“圖”不是流程圖而是狀態(tài)遷移圖。每個節(jié)點本質(zhì)是state - state的純函數(shù)沒有隱式狀態(tài)傳遞。這意味著你無法在節(jié)點A里“偷偷改”節(jié)點B要用的變量——所有變更必須顯式寫入state。這種設(shè)計看似繁瑣實則杜絕了90%的幽靈bug比如某個節(jié)點意外覆蓋了全局session_id導(dǎo)致后續(xù)所有日志串號。2.3 關(guān)鍵分界點三個實操判據(jù)幫你一秒定位類型光看理論容易迷糊我在實際項目中總結(jié)出三個硬性判據(jù)只要滿足任一條件就屬于協(xié)作者型必須選LangGraph類框架全部不滿足則優(yōu)先考慮Claude Agent SDK是否存在“非原子性決策點”如果你的業(yè)務(wù)流程中存在某個環(huán)節(jié)必須由人判斷“是否繼續(xù)”且該判斷依賴LLM未生成的中間結(jié)果例如“請法務(wù)確認條款3是否需保留”這就是非原子性決策點。Claude Agent SDK 無法優(yōu)雅處理——它要么執(zhí)行完所有步驟要么失敗退出而LangGraph可通過.interrupt()在任意節(jié)點后暫停等待人工輸入后再resume。工具調(diào)用失敗是否允許降級或跳過如果某個工具如“查海關(guān)編碼”超時業(yè)務(wù)上允許跳過此步直接進入下一步如“按默認稅率計算”則屬于協(xié)作者型。Claude Agent SDK 默認fail-fast需額外寫fallback邏輯LangGraph則天然支持在node內(nèi)捕獲異常寫if tool_failed: state.update({tax_rate: 0.13})即可無縫降級。是否需要追溯“為什么這樣決策”如果審計要求你提供“Agent為何將此工單分派給上海組而非北京組”的完整證據(jù)鏈包括當時獲取的客戶地域信息、上海組當前負載、歷史分派準確率就必須選LangGraph。它的checkpoint機制自動記錄每次state變更、LLM prompt、tool call參數(shù)及返回導(dǎo)出JSON即可生成審計報告Claude Agent SDK 僅保留最終action log中間推理鏈不可追溯。這三個判據(jù)我在給客戶做技術(shù)盡調(diào)時用一張A4紙就能講清楚。它不涉及任何代碼卻能避免團隊在錯誤的技術(shù)路線上狂奔三個月。3. 實操拆解同一需求兩種框架的實現(xiàn)差異與代價我們以一個真實案例切入銀行信用卡逾期催收話術(shù)生成Agent。業(yè)務(wù)需求是輸入客戶逾期天數(shù)、歷史還款次數(shù)、當前賬戶余額輸出一段符合監(jiān)管要求、語氣得體、帶個性化激勵的話術(shù)如“王女士您已逾期12天近3個月有2次按時還款記錄本次可享利息減免50%點擊鏈接立即處理”。3.1 Claude Agent SDK 實現(xiàn)聚焦“出口確定性”第一步定義Tool Schema嚴格約束輸出from typing import Literal from pydantic import BaseModel, Field class GenerateScriptInput(BaseModel): overdue_days: int Field(..., ge1, le90, description逾期天數(shù)1-90) repayment_count: int Field(..., ge0, le100, description近6個月還款次數(shù)) balance: float Field(..., ge0.01, le1000000.0, description當前欠款余額) class GenerateScriptOutput(BaseModel): script: str Field(..., min_length20, max_length300, description生成的話術(shù)必須包含客戶稱謂、逾期天數(shù)、激勵措施、行動指引) compliance_score: float Field(..., ge0.0, le1.0, description合規(guī)性評分0.95以上才允許發(fā)送) risk_level: Literal[low, medium, high] Field(..., description風(fēng)險等級依據(jù)balance和overdue_days計算) # 注冊工具SDK自動校驗輸入輸出 tool(schemaGenerateScriptInput, output_schemaGenerateScriptOutput) def generate_script(input: GenerateScriptInput) - GenerateScriptOutput: # 實際調(diào)用微調(diào)后的Claude模型prompt含嚴格格式指令 # 輸出必須是valid JSON否則SDK拋異常 return GenerateScriptOutput( scriptf王女士您已逾期{input.overdue_days}天..., compliance_score0.98, risk_levelmedium )第二步配置Agent極簡無狀態(tài)管理from claude_agent import Agent agent Agent( modelclaude-3-haiku-20240307, tools[generate_script], timeout_ms1200, # 嚴格1.2秒超時 max_retries0, # 不重試失敗即告警 ) # 調(diào)用輸入原始數(shù)據(jù)輸出確定結(jié)果 result agent.invoke({ overdue_days: 12, repayment_count: 2, balance: 8500.0 }) # result 是 GenerateScriptOutput 實例可直接序列化發(fā)短信代價與收益? 優(yōu)勢代碼量僅50行部署后P99延遲1.1秒合規(guī)評分0.95時自動拒絕輸出杜絕違規(guī)話術(shù)? 代價若監(jiān)管突然新增“必須提及客戶最近一筆還款日期”需重新訓(xùn)練模型更新schema全量回歸測試無法在生成話術(shù)后讓催收主管手動微調(diào)“激勵力度”再發(fā)送。3.2 LangGraph 實現(xiàn)聚焦“入口可觀測性”第一步定義State容納所有中間態(tài)from typing import Optional, List, Dict, Any from pydantic import BaseModel class CallState(BaseModel): customer_name: str overdue_days: int repayment_count: int balance: float # 中間變量全部顯式聲明 last_repayment_date: Optional[str] None regulatory_rules: List[Dict[str, Any]] [] draft_script: Optional[str] None compliance_check_result: Optional[Dict[str, Any]] None human_approval: Optional[bool] None # 人工干預(yù)標記第二步構(gòu)建圖節(jié)點職責(zé)清晰狀態(tài)可追蹤from langgraph.graph import StateGraph, END from langgraph.checkpoint.sqlite import SqliteSaver def fetch_last_repayment(state: CallState): # 調(diào)用CRM API獲取最近還款日期 date call_crm_api(state.customer_name) return {last_repayment_date: date} def load_regulations(state: CallState): # 加載最新監(jiān)管規(guī)則可熱更新 rules get_latest_regulations() return {regulatory_rules: rules} def generate_draft(state: CallState): # LLM生成初稿prompt含規(guī)則引用 script llm.invoke(f根據(jù)規(guī)則{state.regulatory_rules}生成話術(shù)...) return {draft_script: script} def check_compliance(state: CallState): # 調(diào)用合規(guī)引擎校驗 result compliance_engine.validate(state.draft_script) return {compliance_check_result: result} def human_review(state: CallState): # 等待人工輸入前端調(diào)用invoke時傳入 if not state.human_approval: return {human_approval: None} # 觸發(fā)interrupt return {human_approval: state.human_approval} # 構(gòu)建圖 builder StateGraph(CallState) builder.add_node(fetch_repayment, fetch_last_repayment) builder.add_node(load_rules, load_regulations) builder.add_node(generate, generate_draft) builder.add_node(check, check_compliance) builder.add_node(review, human_review) builder.set_entry_point(fetch_repayment) builder.add_edge(fetch_repayment, load_rules) builder.add_edge(load_rules, generate) builder.add_edge(generate, check) builder.add_conditional_edges( check, lambda state: approved if state.compliance_check_result[score] 0.95 else review, {approved: END, review: review} ) builder.add_edge(review, END) graph builder.compile(checkpointerSqliteSaver.from_conn_string(:memory:))第三步調(diào)用支持全流程干預(yù)# 初始調(diào)用 config {configurable: {thread_id: call_12345}} result graph.invoke({ customer_name: 王女士, overdue_days: 12, repayment_count: 2, balance: 8500.0 }, config) # 若合規(guī)分0.95系統(tǒng)自動暫停在review節(jié)點 # 前端可調(diào)用 graph.invoke({ human_approval: True, # 主管點擊“通過” draft_script: 王女士您已逾期12天...微調(diào)后版本 }, config) # 查看完整決策鏈 state graph.get_state(config) print(state.values) # 輸出所有中間變量、時間戳、節(jié)點執(zhí)行日志代價與收益? 優(yōu)勢監(jiān)管規(guī)則更新只需改load_regulations節(jié)點無需重訓(xùn)模型主管可在任意節(jié)點介入審計時graph.get_state()一鍵導(dǎo)出全鏈路證據(jù)? 代價代碼量300行首次部署需配置SQLiteP99延遲2.8秒因多步IO運維復(fù)雜度顯著提升。3.3 關(guān)鍵對比表選型決策的量化依據(jù)維度Claude Agent SDKLangGraph我的實際選擇建議首屏響應(yīng)時間P99 ≤ 1.3秒P99 ≤ 2.8秒單線程/ ≤ 1.9秒Redis checkpointer若業(yè)務(wù)SLA要求1.5秒優(yōu)先SDK若可接受≤3秒LangGraph更靈活狀態(tài)持久化成本無內(nèi)置機制需自行集成DB內(nèi)置checkpointSQLite免費PostgreSQL生產(chǎn)推薦小團隊用SQLite夠用中大型系統(tǒng)必須評估PostgreSQL連接池壓力人工干預(yù)支持需hack在tool內(nèi)加if manual_mode: return wait_for_human()原生.interrupt()invoke(..., config)凡涉及“人審”“人補”“人覆”LangGraph省90%膠水代碼規(guī)則熱更新能力工具schema變更需重啟服務(wù)load_rules節(jié)點可獨立更新不影響其他節(jié)點監(jiān)管頻繁變動的金融/醫(yī)療場景LangGraph是剛需調(diào)試成本日志只有input/outputLLM內(nèi)部推理不可見get_state()返回完整state樹含每個節(jié)點的prompt和tool call詳情新人上手調(diào)試LangGraph學(xué)習(xí)曲線陡但長期省力SDK初期快但后期難排查擴展多智能體需手動編排多個Agent實例狀態(tài)同步復(fù)雜原生支持send()跨圖通信State可繼承復(fù)用做“催收Agent風(fēng)控Agent法務(wù)Agent”協(xié)同LangGraph架構(gòu)更清晰這張表是我和架構(gòu)師喝著咖啡拍板的依據(jù)。它不談虛的概念只列工程師真正在意的數(shù)字和痛點。4. 避坑指南那些沒人告訴你的“選型后遺癥”4.1 Claude Agent SDK 的隱藏陷阱當“確定性”變成“僵化性”我最早用SDK做的一個HR面試邀約Agent跑得飛快P99 0.8秒。但上線兩周后招聘BP提了個需求“如果候選人上周剛拒過我們offer話術(shù)末尾要加‘理解您上次的選擇本次崗位有新升級’”。這看起來只是prompt微調(diào)但實際踩了三個深坑Schema耦合陷阱原tool output schema里script字段是str現(xiàn)在要加條件分支LLM可能生成“理解您上次的選擇...”或“感謝您關(guān)注...”但SDK的schema校驗只認固定格式。我被迫把script改成dict增加base_script和conditional_suffix兩個字段結(jié)果所有下游系統(tǒng)短信網(wǎng)關(guān)、郵件模板引擎都要改解析邏輯——一個文案需求引發(fā)5個系統(tǒng)聯(lián)調(diào)。Fallback失效陷阱SDK的max_retries0本是優(yōu)點但當LLM因溫度值設(shè)置過高為增加文案多樣性偶爾生成不符合schema的JSON時整個請求直接500。監(jiān)控里看到大量ValidationError卻無法區(qū)分是LLM bug還是輸入臟數(shù)據(jù)。最后只能加一層前置清洗對所有輸入字段做正則校驗把overdue_daystwelve這種字符串提前攔住——這違背了SDK“專注執(zhí)行”的初衷?；叶劝l(fā)布陷阱想用A/B test驗證新話術(shù)效果SDK不支持按thread_id路由到不同model版本。我不得不在外層加Nginx分流把/v1/generate?expnew_script的請求導(dǎo)向新服務(wù)但這樣就失去了SDK的統(tǒng)一超時控制兩套服務(wù)的P99指標完全不可比。實操心得Claude Agent SDK 適合“功能穩(wěn)定、規(guī)則固化、下游系統(tǒng)不愿改”的場景。一旦業(yè)務(wù)進入快速迭代期它的強約束會迅速變成枷鎖。我的經(jīng)驗是上線前務(wù)必問自己“未來6個月這個智能體的輸入輸出schema有無可能變更”如果有立刻選LangGraph。4.2 LangGraph 的認知負荷當“可觀測”變成“過度設(shè)計”我們曾用LangGraph搭一個簡單的“會議紀要生成Agent”結(jié)果陷入“狀態(tài)焦慮”初始state只定義了transcript和summary第二版加了action_items待辦事項第三版加了decision_points決策點第四版加了sentiment_score情緒分最后state膨脹到12個字段每個節(jié)點都要return {field_x: value}新人看代碼像讀天書。更糟的是為追求“完美可觀測”我們在每個節(jié)點后加了logger.info(fNode X executed, state: {state})結(jié)果日志量暴增10倍ELK集群差點被打爆。運維同事找上門“你們的Agent每秒產(chǎn)生2000行日志比整個訂單系統(tǒng)的日志還多”LangGraph真正的敵人不是技術(shù)是工程師的完美主義。它的state schema不是越細越好而是要遵循“最小必要原則”只存影響下一步?jīng)Q策或必須審計的字段。比如sentiment_score對會議紀要生成毫無價值刪掉decision_points若只是供人看不參與后續(xù)邏輯就該移到前端渲染層而非塞進state。實操心得LangGraph的state不是數(shù)據(jù)庫而是決策上下文快照。我現(xiàn)在的做法是每個節(jié)點只更新1-2個字段用state.update()而非全量覆蓋所有只讀信息如原始錄音文本存OSSstate里只放URLaudit字段統(tǒng)一加_audit_前綴方便日志過濾。這套約定讓團隊新人三天就能上手維護。4.3 混合架構(gòu)的實戰(zhàn)平衡術(shù)不選邊而是分層最成熟的方案往往不是二選一而是分層組合。我在一個保險核保Agent中實踐了“SDKLangGraph”混合架構(gòu)效果極佳外層用LangGraph做流程編排負責(zé)接收用戶上傳的體檢報告PDF、調(diào)用OCR識別、觸發(fā)風(fēng)控規(guī)則引擎、決定是否需要人工復(fù)核——這一層需要狀態(tài)追蹤、人工中斷、規(guī)則熱更新內(nèi)層用Claude Agent SDK做原子工具OCR識別、規(guī)則引擎調(diào)用、話術(shù)生成全部封裝成SDK工具。LangGraph節(jié)點只負責(zé)傳參調(diào)用不關(guān)心內(nèi)部實現(xiàn)狀態(tài)橋接LangGraph的state中ocr_result字段存SDK返回的結(jié)構(gòu)化JSONrule_engine_output字段存SDK返回的風(fēng)險等級所有SDK工具的timeout、retry策略由SDK自身管理LangGraph只處理“調(diào)用成功/失敗”兩種狀態(tài)。這樣既享受了LangGraph的流程靈活性又保留了SDK的執(zhí)行確定性。關(guān)鍵在于清晰劃分邊界LangGraph管“做什么”和“何時做”SDK管“怎么做”和“做得多準”。實操心得混合架構(gòu)不是炫技而是成本權(quán)衡。我的分層原則是凡涉及外部系統(tǒng)交互、人工干預(yù)、長周期狀態(tài)交給LangGraph凡涉及高并發(fā)、低延遲、強一致性輸出交給Claude Agent SDK。兩者通過明確定義的DTOData Transfer Object通信絕不共享內(nèi)存或狀態(tài)。5. 選型之后如何讓智能體真正跑起來5.1 監(jiān)控不是錦上添花而是生存必需無論選哪個框架上線后第一件事不是優(yōu)化prompt而是埋監(jiān)控。我給自己定的鐵律沒有監(jiān)控的智能體等于沒上線。具體監(jiān)控項必須覆蓋三層基礎(chǔ)設(shè)施層CPU/內(nèi)存使用率LangGraph的checkpointer易吃內(nèi)存、Redis連接數(shù)LangGraph用Redis時、API調(diào)用延遲Claude SDK的timeout命中率框架層LangGraph的checkpoint_sizestate序列化后大小超1MB要告警、node_execution_time各節(jié)點P95耗時Claude SDK的validation_error_rateschema校驗失敗率0.1%需立即排查業(yè)務(wù)層話術(shù)生成Agent的compliance_score 0.95占比、催收Agent的human_interrupt_rate人工介入率15%說明流程設(shè)計有問題、會議紀要Agent的summary_length_deviation摘要字數(shù)偏離均值±20%即告警。我們曾因忽略checkpoint_size監(jiān)控導(dǎo)致LangGraph在處理大PDF時state膨脹到8MBSQLite寫入超時整個圖卡死。后來加了state_size_validator節(jié)點超過2MB自動壓縮文本并告警問題根除。5.2 Prompt不是魔法而是接口契約很多團隊把prompt當黑盒調(diào)優(yōu)這是最大誤區(qū)。Prompt本質(zhì)是LLM與業(yè)務(wù)邏輯之間的API契約。Claude Agent SDK要求你把prompt約束寫進tool schemaLangGraph要求你在節(jié)點函數(shù)里顯式聲明prompt模板——這恰恰是好事。我的做法是為每個tool/node建立prompt_contract.md文檔包含輸入變量說明如{customer_name}必須是中文姓名不含空格輸出格式強制要求如“必須以‘尊敬的{customer_name}’開頭結(jié)尾帶‘點擊鏈接’”錯誤示例如生成“親愛的王先生”算違規(guī)因客戶性別未知合規(guī)紅線如禁止出現(xiàn)“保證”“絕對”等詞。這份文檔和代碼一起提交GitPR評審時必須檢查prompt契約是否與業(yè)務(wù)需求一致。它讓prompt從玄學(xué)變成可測試的接口。5.3 迭代不是推倒重來而是漸進增強最后分享一個血淚教訓(xùn)別迷信“下一代框架”。我們曾計劃把運行良好的Claude Agent SDK項目遷到LangGraph理由是“LangGraph更先進”。結(jié)果花了6周重寫上線后P99延遲從1.1秒升到2.4秒業(yè)務(wù)方投訴“比原來慢一倍”。最后發(fā)現(xiàn)原SDK的輕量級設(shè)計恰恰匹配了業(yè)務(wù)——催收話術(shù)生成本就不需要狀態(tài)回溯強行加LangGraph只是增加復(fù)雜度。真正的迭代應(yīng)該是基于監(jiān)控數(shù)據(jù)的漸進增強當validation_error_rate持續(xù)升高說明輸入數(shù)據(jù)質(zhì)量下降該加數(shù)據(jù)清洗層當human_interrupt_rate突增說明LLM輸出與業(yè)務(wù)預(yù)期偏差變大該重訓(xùn)模型而非換框架當checkpoint_size緩慢增長說明state設(shè)計冗余該做字段精簡而非升級checkpointer。智能體開發(fā)最終拼的不是框架多酷而是你對業(yè)務(wù)問題的理解深度以及把這種理解精準翻譯成技術(shù)約束的能力。那個“先問的問題”就是翻譯的起點。