1. 從Chain到Graph為什么LangGraph是Agent開發(fā)的分水嶺先聊個真實感受。熱搜詞里那句“讓AI真的下地干活”幾乎是所有做過Agent項目的人心里最癢的一句話。ChatGPT剛火那會兒大家拿LangChain寫鏈?zhǔn)秸{(diào)用一個輸入進(jìn)去經(jīng)過幾個Prompt模板出來一段結(jié)果。但真做起Agent來你會發(fā)現(xiàn)事情沒那么簡單Agent要能觀察環(huán)境、決定行動、調(diào)用工具、看到結(jié)果再繼續(xù)思考這是一個循環(huán)往復(fù)的過程。傳統(tǒng)Chain是線性的一次跑完就結(jié)束根本沒法表達(dá)“先查數(shù)據(jù)、再寫SQL、發(fā)現(xiàn)數(shù)據(jù)不對、重新查一遍”這樣的邏輯。LangGraph就是為了解決這個核心痛點出現(xiàn)的。它是一個基于圖結(jié)構(gòu)的Agent編排框架把AI流程建模成一張有向圖節(jié)點Node是你要執(zhí)行的動作邊Edge是狀態(tài)流轉(zhuǎn)的路徑圖的狀態(tài)State則攜帶所有上下文在節(jié)點之間傳遞。說白了它不是把Prompt串成一條直線而是讓你像畫流程圖一樣編排AI的工作過程節(jié)點之間可以跳轉(zhuǎn)、循環(huán)、回退完全由代碼和AI的判斷決定。我第一次用LangGraph時最強(qiáng)烈的感受是這不就是給AI加了一張流程圖嗎但正是這張流程圖解決了Agent開發(fā)里最惡心的兩個問題——狀態(tài)管理混亂和執(zhí)行路徑不可控。以前寫Agent循環(huán)邏輯要靠while循環(huán)硬寫每次迭代的結(jié)果要自己拼到一個大字典里哪個環(huán)節(jié)出錯了也很難回溯。用LangGraph整個狀態(tài)就是全局共享的一個數(shù)據(jù)對象每個節(jié)點讀取它、更新它圖框架負(fù)責(zé)傳遞和保存你要做的就是定義好節(jié)點和邊。這篇文章我打算按自己的學(xué)習(xí)路徑來寫先講清楚LangGraph的核心設(shè)計思想再逐個拆解State、Node、Edge這幾個基礎(chǔ)概念然后從零手寫一個帶工具調(diào)用的小Agent最后把服務(wù)用FastAPI包起來跑在線上去。內(nèi)容覆蓋LangGraph基礎(chǔ)和工具調(diào)用落地適合剛接觸LangGraph、想搞懂它到底怎么用的朋友。要是你已經(jīng)在鏈?zhǔn)秸{(diào)用里寫了一堆if...else...那這篇正好幫你從“鏈”跳到“圖”。1.1 傳統(tǒng)鏈?zhǔn)秸{(diào)用覆蓋不了的場景咱們先把場景鋪開。假設(shè)你要做一個售后客服Agent用戶說“我上周買的耳機(jī)充不進(jìn)電幫我查一下訂單”。這個需求拆開來看Agent至少要經(jīng)歷這么幾步判斷用戶的意圖——是退換貨、維修還是單純咨詢從訂單系統(tǒng)里查出訂單狀態(tài)和商品信息根據(jù)售后規(guī)則判斷下一步行動——是發(fā)退貨鏈接還是轉(zhuǎn)人工生成對用戶的最終回復(fù)這里面有個關(guān)鍵點第二步的結(jié)果會影響第三步的走向。如果查出來訂單已過退貨期Agent就要走“維修”分支如果還能退就走“退換貨”分支。再細(xì)一步調(diào)用訂單API可能超時、可能查不到數(shù)據(jù)那Agent還得自動換個策略比如用用戶ID再查一次。這種有分支、有循環(huán)、有依賴的場景用LangChain的Chain結(jié)構(gòu)是非常痛苦的。Chain的RunnableSequence本質(zhì)上是固定的管道輸入從一端流到另一端中間不能停下來、不能跳轉(zhuǎn)。你當(dāng)然可以把if...else...寫在自定義函數(shù)里但那等于把流程控制權(quán)從框架手里搶回來自己維護(hù)代碼一多就變成一團(tuán)亂麻。LangGraph的解法是把這種流程直觀地建模成圖。節(jié)點代表“調(diào)用LLM”“調(diào)用工具”“運(yùn)行Python函數(shù)”邊代表“下一步去哪兒”條件邊則讓AI決定走哪條路。圖天然支持分支和循環(huán)而且狀態(tài)是顯式傳遞的每一步都看得見摸得著。這才是Agent真正需要的運(yùn)行時。1.2 LangGraph的核心狀態(tài)機(jī)遇上AI流程LangGraph本身借鑒了狀態(tài)機(jī)State Machine的思想。你對狀態(tài)機(jī)不熟也沒關(guān)系想象一個電梯控制系統(tǒng)電梯在“運(yùn)行”狀態(tài)、在“靜止”狀態(tài)按樓層按鈕觸發(fā)狀態(tài)切換每一步都有明確的規(guī)則。LangGraph把AI流程也看成這樣的狀態(tài)機(jī)系統(tǒng)的當(dāng)前狀況全部保存在State里像一個實時更新的中央數(shù)據(jù)倉庫Node是被觸發(fā)執(zhí)行的操作執(zhí)行完后會更新State根據(jù)State當(dāng)前的值條件邊決定下一跳是哪個節(jié)點整個過程在圖Graph里循環(huán)直到走到END節(jié)點這種設(shè)計讓AI流程變得可控。傳統(tǒng)Agent開發(fā)最怕的就是模型“天馬行空”一個循環(huán)能跑幾十輪不收斂。LangGraph允許你顯式設(shè)置最大遞歸次數(shù)、定義停止條件、甚至分支出去做多個并行任務(wù)再合并結(jié)果。這些能力一層層壘下來LangGraph就不只是LangChain的“升級版”而是一個獨立的Agent編排層。我在寫第一個圖的時候心里只有一個感慨流程不再是藏在代碼里的隱式邏輯而是像畫架構(gòu)圖一樣擺在了桌面上。這個變化帶來的調(diào)試體驗是質(zhì)的飛躍——出問題不用打日志猜流程走到哪直接打印State截圖就能看出來。2. 五個核心概念一次講透說實話LangGraph的API設(shè)計得很有章法但也因此勸退了不少人。初看文檔時滿屏的StateGraph、add_node、add_edge、END配合幾個抽象的名詞很多人第一反應(yīng)就是“這和LangChain不是一個套路嗎怎么那么繞”。其實它的核心概念只有五個搞懂這五個剩下的全是組合使用。2.1 State貫穿全流程的共享數(shù)據(jù)倉庫State是整個圖運(yùn)行時唯一的數(shù)據(jù)載體。你可以把它理解成一個不斷被更新的大字典圖里的每個節(jié)點都能讀它、改它。LangGraph官方文檔里最常出現(xiàn)的State定義方式是用TypedDictfrom typing import TypedDict class AgentState(TypedDict): messages: list # 對話歷史 order_info: dict # 查到的訂單信息 intent: str # 用戶意圖分類結(jié)果 final_answer: str # 最終回復(fù)TypedDict的好處是給字典加上了類型約束IDE能自動補(bǔ)全運(yùn)行時會校驗報錯對于復(fù)雜Agent來說這個約束能少踩很多坑。當(dāng)你調(diào)用StateGraph(AgentState)初始化圖時這個類型就成了整張圖的“全局變量聲明”。實際操作中我發(fā)現(xiàn)一個設(shè)計State的關(guān)鍵點不要圖省事把所有東西塞進(jìn)一個字段要有意地區(qū)分“短期工作變量”和“長期上下文”。比如對話歷史可能很長但你可以只在最后一步匯總時用它訂單原始JSON很大但下游節(jié)點只需要提取過的幾個字段。把State設(shè)計得過胖不僅每次傳遞都浪費(fèi)token而且會讓排查問題變得費(fèi)勁——因為你根本不知道是哪個節(jié)點改了哪個字段。LangGraph還允許你通過Annotated配合operator.add來定義字段的更新方式。比如消息列表用追加而不是覆蓋from typing import Annotated from typing_extensions import TypedDict import operator class AgentState(TypedDict): messages: Annotated[list, operator.add] # 新消息追加到舊消息后面 order_info: dict這樣就不用寫state[messages] state[messages] new_messages這種手動拼接代碼了。定義State合并規(guī)則其實是LangGraph一個容易被忽略但極其重要的能力它直接決定了多節(jié)點協(xié)作時數(shù)據(jù)怎么流轉(zhuǎn)。2.2 Node真正“干活”的地方Node就是圖上的一個操作單元本質(zhì)上是一個普通Python函數(shù)。函數(shù)簽名很固定接收一個state參數(shù)整個State字典返回一個dict返回的字典會被合并回State。來看一個最基礎(chǔ)的節(jié)點函數(shù)def analyze_intent(state: AgentState) - dict: # 假設(shè)這里已經(jīng)調(diào)用了一個意圖識別模型 user_input state[messages][-1][content] intent after_sales # 簡化判斷 return {intent: intent}這個函數(shù)讀到了state里最后一條用戶消息做了處理后返回一個{intent: ...}LangGraph就會用返回值更新State里的intent字段。需要注意的是節(jié)點的返回值不需要覆蓋全部State只需要返回你改了的那部分。這個設(shè)計讓每個節(jié)點可以只關(guān)心自己負(fù)責(zé)的領(lǐng)域。說白了Node是圖里唯一能觸碰外部世界的地方。你要查數(shù)據(jù)庫、調(diào)API、運(yùn)行重型計算都寫在Node里。LLM調(diào)用本身也可以封裝成一個Node——把Prompt模板、模型調(diào)用、輸出解析放在函數(shù)里只暴露state進(jìn)、dict出的接口。這樣做有個額外好處測試單個Node的時候你根本不需要起一張圖直接給個假State就能單測。寫Node的時候我踩過一個坑不要在節(jié)點函數(shù)內(nèi)部再去直接修改傳入的state參數(shù)。LangGraph的State是不可變快照immutable updates你把state[order_info] xxx寫在函數(shù)里它確實能改這個局部引用但不會真正影響圖的State流轉(zhuǎn)。正確做法永遠(yuǎn)是返回一個字典讓框架去合并。一開始不習(xí)慣覺得多此一舉但調(diào)試幾次后才會體會到這個約束的價值——每一步狀態(tài)變化都有明確的“提交記錄”。2.3 Edge與條件邊控制流程走向的兩把鑰匙只有節(jié)點沒有邊圖就只是一堆散落的函數(shù)。Edge的作用就是告訴LangGraph這個節(jié)點跑完之后下一步去哪個節(jié)點。最簡單的添加方式是這樣from langgraph.graph import StateGraph, END graph StateGraph(AgentState) graph.add_node(analyze_intent, analyze_intent) graph.add_node(check_order, check_order) graph.add_node(generate_answer, generate_answer) graph.set_entry_point(analyze_intent) # 入口先分析意圖 graph.add_edge(analyze_intent, check_order) # 分析完后查訂單 graph.add_edge(check_order, generate_answer) # 查完訂單生成回復(fù) graph.add_edge(generate_answer, END) # 生成完結(jié)束這種固定路徑適合流水線場景但Agent的核心價值恰恰在于不走固定路徑。所以LangGraph提供了add_conditional_edges讓“下一步去哪”由節(jié)點函數(shù)的返回值動態(tài)決定def route_after_check(state: AgentState) - str: # 根據(jù)查單結(jié)果決定走退貨流程還是維修流程 if state[order_info][can_refund]: return refund else: return repair graph.add_conditional_edges( check_order, route_after_check, { refund: refund_node, repair: repair_node, } )這個條件和字典映射的組合寫起來特別像路由表函數(shù)負(fù)責(zé)返回一個字符串標(biāo)簽字典負(fù)責(zé)把標(biāo)簽映射到實際節(jié)點。LangGraph拿到返回值后就去字典里查對應(yīng)的節(jié)點名跳到那個節(jié)點繼續(xù)跑。有條件邊的加持一張圖就能寫出一棵完整的決策樹。2.4 圖的編譯與執(zhí)行把設(shè)計變成可運(yùn)行的Agent圖設(shè)計好之后還必須經(jīng)過編譯這一步才能執(zhí)行app graph.compile() result app.invoke({messages: [{role: user, content: 耳機(jī)壞了怎么辦}]})compile()會做一次內(nèi)部結(jié)構(gòu)解析把節(jié)點、邊、條件檢查一遍有問題會立刻報錯。比如你引用了一個不存在的節(jié)點名編譯階段就能被抓出來而不是等到運(yùn)行到那一步才出異常。從這個角度說compile()像是一個圖結(jié)構(gòu)的“靜態(tài)檢查器”。invoke()是同步執(zhí)行接口。數(shù)據(jù)進(jìn)去后會從入口節(jié)點出發(fā)沿著邊和條件一路跑到END最終返回完整的State包含所有節(jié)點更新的字段。如果圖里有循環(huán)——比如Agent反復(fù)調(diào)用工具直到結(jié)果滿意——invoke()會一直循環(huán)到滿足退出條件為止。如果你希望拿到中間態(tài)比如每跑完一個節(jié)點就拿到一次狀態(tài)快照可以用stream()接口for event in app.stream({messages: [...]}, stream_modeupdates): print(event) # 每個節(jié)點執(zhí)行后都會輸出一步調(diào)試新圖的時候我強(qiáng)烈建議先用stream()把每一步輸出都打出來確認(rèn)每個節(jié)點的返回值符合預(yù)期再切回invoke()做生產(chǎn)調(diào)用。這個習(xí)慣能讓你把一個復(fù)雜的Agent調(diào)試時間從半天縮短到一小時。2.5 循環(huán)不是BugAgent的“再想想”機(jī)制講了這么多基礎(chǔ)概念必須把Agent循環(huán)單獨拿出來說一說。傳統(tǒng)編程里循環(huán)要小心翼翼但在Agent場景里循環(huán)恰恰是智能的體現(xiàn)。一個Agent收到用戶請求后可能要用工具查一遍資料、發(fā)現(xiàn)資料不夠、再調(diào)整查詢詞再查一遍這個“查了又查”的過程本質(zhì)上就是圖上的一個環(huán)。LangGraph對循環(huán)的支持是天然自帶的只要有一條邊從后面的節(jié)點指向前面的節(jié)點圖就跑成了環(huán)。最常見的場景是“調(diào)用工具”節(jié)點結(jié)束后把工具返回的結(jié)果放回State的messages然后跳到“LLM決策”節(jié)點讓模型看了工具結(jié)果后再決定下一步動作。這就是ReAct模式的雛形——模型用一次推理決定要調(diào)哪個工具工具返回后模型再推理下一步直到模型認(rèn)為問題已經(jīng)解決。寫循環(huán)時最怕的是無限循環(huán)。LangGraph提供了兩個保護(hù)措施一是編譯圖時傳recursion_limit參數(shù)限制最大步數(shù)二是在條件邊里寫顯式的“已完成”分支跳到END。我的習(xí)慣是條件邊里永遠(yuǎn)寫一個終止分支即使這個分支當(dāng)時看起來永遠(yuǎn)不會走到。模型的行為沒法100%預(yù)測這條退路是給意外情況兜底的。3. 從零構(gòu)建第一個LangGraph應(yīng)用概念說再多不如親手跑一個。這一節(jié)我?guī)愦钜粋€完整的LangGraph應(yīng)用它做的事情很簡單收到用戶的問題后先判斷意圖再決定是直接回答還是調(diào)用一個工具。工具這里我用“查天氣”來演示純模擬但你完全可以把工具換成查訂單、查數(shù)據(jù)庫、調(diào)用業(yè)務(wù)API。3.1 環(huán)境準(zhǔn)備與工程結(jié)構(gòu)先裝依賴。我推薦單獨建一個虛擬環(huán)境避免污染其他項目的依賴python -m venv .venv source .venv/bin/activate # Windows用 .venv\Scripts\activate pip install langgraph langchain-openai python-dotenv注意這里我用了langchain-openai這是LangChain新版的OpenAI適配包。如果你用的是langchain舊版的langchain.llms.OpenAI那大概率會碰到導(dǎo)入路徑不兼容的問題建議統(tǒng)一用新版。最后把OpenAI的API Key配到環(huán)境變量里或者寫在.env文件里啟動時加載。工程結(jié)構(gòu)我習(xí)慣這樣組織便于后面擴(kuò)展agent/ ├── main.py # 圖組裝與執(zhí)行入口 ├── state.py # State定義 ├── nodes/ # 各節(jié)點的實現(xiàn) │ ├── __init__.py │ ├── analyze.py │ ├── tools.py │ └── answer.py ├── tools/ # 工具函數(shù) │ ├── __init__.py │ └── weather.py └── requirements.txt小項目不用分這么細(xì)但當(dāng)圖里節(jié)點數(shù)量超過四五個沒有按職責(zé)拆文件的話改起來會非常痛苦。LangGraph的節(jié)點本質(zhì)上是純函數(shù)模塊化本來就自然沒必要都堆在一個文件里。3.2 定義State、工具和節(jié)點State按上一節(jié)的思路定義為了演示追加消息的合并規(guī)則我用operator.add處理消息列表# state.py import operator from typing import Annotated, TypedDict class AgentState(TypedDict): messages: Annotated[list, operator.add] need_tool: bool # LLM判斷是否需要調(diào)用工具 tool_result: str工具這里我用一個帶延遲的模擬函數(shù)模擬真實API調(diào)用# tools/weather.py import random def get_weather(city: str) - str: 模擬查詢天氣實際項目里替換成真實API調(diào)用 temp random.randint(15, 30) return f{city} 當(dāng)前氣溫 {temp} 攝氏度天氣晴轉(zhuǎn)多云節(jié)點部分意圖判斷節(jié)點讓LLM決定“要不要工具”——為了讓行為可解釋我讓模型用結(jié)構(gòu)化的方式輸出# nodes/analyze.py from langchain_openai import ChatOpenAI from state import AgentState model ChatOpenAI(modelgpt-4o-mini, temperature0) def analyze_intent(state: AgentState) - dict: last_message state[messages][-1][content] # 讓模型輸出JSON解析后作為判斷結(jié)果 resp model.invoke( f用戶說{last_message}。請判斷是否需要查詢實時信息比如天氣、訂單、庫存。 f只需要回答是或否。 ) need_tool resp.content.strip().startswith(是) return {need_tool: need_tool, messages: []}等一下這里有個注意事項不要隨意往State里塞空消息列表占位。因為messages字段用了operator.add合并如果你返回一個空列表合并時它不會追加任何消息這沒問題但如果你圖省事返回{messages: [...]}就會把一條空消息存進(jìn)去進(jìn)而污染后面的對話上下文。LangGraph的更新是增量式的你只需要返回真正想更新的字段。如果need_tool為True就進(jìn)入工具調(diào)用節(jié)點# nodes/tools.py from state import AgentState from tools.weather import get_weather def call_tool(state: AgentState) - dict: user_request state[messages][-1][content] # 這里簡化處理從消息里提取城市名實際項目里讓模型先做參數(shù)抽取 city 北京 result get_weather(city) return {tool_result: result, messages: [ {role: tool, content: f查詢結(jié)果{result}} ]}最后是回答節(jié)點它把工具結(jié)果和用戶原始問題合并用LLM生成最終回復(fù)# nodes/answer.py from langchain_openai import ChatOpenAI from state import AgentState model ChatOpenAI(modelgpt-4o-mini, temperature0.3) def generate_answer(state: AgentState) - dict: last_message state[messages][-1] if state[need_tool] and state[tool_result]: prompt f工具查詢結(jié)果{state[tool_result]}\n請基于這個結(jié)果回答用戶。 else: prompt 直接回答用戶的問題。 resp model.invoke([ {role: user, content: last_message[content]}, {role: assistant, content: prompt} ]) return {messages: [{role: assistant, content: resp.content}]}3.3 組裝圖并執(zhí)行驗證現(xiàn)在把節(jié)點和邊拼到一起。這一版我設(shè)計了三條路徑不需要工具就直連回答需要工具就先去工具節(jié)點再生成回復(fù)工具節(jié)點執(zhí)行后也可以選擇再走一次判斷演示循環(huán)能力雖然這里用不上但結(jié)構(gòu)上留好了# main.py from langgraph.graph import StateGraph, END from state import AgentState from nodes.analyze import analyze_intent from nodes.tools import call_tool from nodes.answer import generate_answer def route_after_analyze(state: AgentState) - str: if state[need_tool]: return call_tool return generate_answer graph StateGraph(AgentState) graph.add_node(analyze_intent, analyze_intent) graph.add_node(call_tool, call_tool) graph.add_node(generate_answer, generate_answer) graph.set_entry_point(analyze_intent) graph.add_conditional_edges( analyze_intent, route_after_analyze, {call_tool: call_tool, generate_answer: generate_answer} ) graph.add_edge(call_tool, generate_answer) graph.add_edge(generate_answer, END) app graph.compile() result app.invoke({messages: [{role: user, content: 北京今天天氣怎么樣}]}) print(result[messages][-1][content])這個流程跑起來之后關(guān)鍵詞“LangGraph 工具調(diào)用”的整個閉環(huán)就通了用戶輸入被分析、LLM判斷需要工具、工具被調(diào)用獲得結(jié)果、結(jié)果被合成為最終回復(fù)。而且每一次狀態(tài)流轉(zhuǎn)都被LangGraph記錄在案出問題可以直接翻中間態(tài)。我實測調(diào)試時最愛用stream模式把每步狀態(tài)變化打在終端上基本一眼就能看出哪個節(jié)點出了問題。比如for chunk in app.stream( {messages: [{role: user, content: 北京今天天氣怎么樣}]}, stream_modeupdates ): print(chunk)輸出里能看到“分析節(jié)點”先執(zhí)行、返回了need_toolTrue然后“工具節(jié)點”執(zhí)行、把查詢結(jié)果寫入State最后“回答節(jié)點”基于工具結(jié)果生成回復(fù)。這種透明度是傳統(tǒng)鏈?zhǔn)秸{(diào)用完全給不了的。4. 讓Agent真正“下地干活”工具調(diào)用與FastAPI實戰(zhàn)基礎(chǔ)圖能跑通之后就該聊落地了。熱搜詞那半句話特別戳人——“讓AI真的下地干活”。企業(yè)里的Agent不會只停留在玩玩具的階段它要去查數(shù)據(jù)庫、寫工單、調(diào)第三方API、在網(wǎng)頁上操作。做到這些核心就是工具調(diào)用Function Calling / Tool Calling的設(shè)計。4.1 工具調(diào)用的本質(zhì)把函數(shù)說明書給模型工具調(diào)用在技術(shù)本質(zhì)上并不神秘你寫一批函數(shù)把它們用tool裝飾器包裝起來連同函數(shù)的名稱、參數(shù)描述、返回值說明一起發(fā)給LLM。模型在收到用戶請求后從這些“工具說明書”里選一個合適的函數(shù)和參數(shù)然后以結(jié)構(gòu)化的形式JSON對象返回“我想調(diào)用這個函數(shù)參數(shù)是這樣”。你的程序拿到這個JSON后實際執(zhí)行對應(yīng)函數(shù)再把結(jié)果作為新消息發(fā)回給模型讓模型基于函數(shù)輸出繼續(xù)回答。整個過程可以循環(huán)多次。用LangChain寫一個工具非常簡單from langchain_core.tools import tool tool def get_weather(city: str) - str: 根據(jù)城市名查詢當(dāng)前的天氣情況參數(shù)city是城市名如北京。 return f{city} 今天的天氣是晴氣溫26度注意get_weather函數(shù)體本身可以不重要真正給模型看的是三樣?xùn)|西函數(shù)名get_weather、函數(shù)簽名參數(shù)city、以及docstring里的自然語言描述。我在實際項目里發(fā)現(xiàn)docstring寫得好不好直接影響模型選工具的準(zhǔn)確率。你要寫“查詢城市天氣”不能寫“內(nèi)部天氣服務(wù)接口”這種模糊描述。參數(shù)說明也一樣最好帶上示例值和邊界條件比如city要說明是中文城市名避免模型傳成拼音。4.2 用FastAPI把Agent包成HTTP服務(wù)工具定了Agent圖也定了最后一步是讓它以服務(wù)的形式常駐運(yùn)行。這時候FastAPI就派上用場了。FastAPI的異步支持配合LangGraph的ainvoke可以很自然地實現(xiàn)并發(fā)請求處理。給你一份可以直接抄作業(yè)的服務(wù)代碼# server.py from fastapi import FastAPI from pydantic import BaseModel from main import app as graph_app # 把編譯好的圖導(dǎo)入進(jìn)來 app FastAPI(titleAI Agent Service) class UserRequest(BaseModel): message: str session_id: str default class AgentResponse(BaseModel): reply: str session_id: str app.post(/api/agent, response_modelAgentResponse) async def run_agent(req: UserRequest): # 實際項目里session_id可以從數(shù)據(jù)庫或緩存里恢復(fù)歷史狀態(tài) result await graph_app.ainvoke({ messages: [{role: user, content: req.message}] }) return AgentResponse( replyresult[messages][-1][content], session_idreq.session_id )啟動服務(wù)后你就能用curl測試整個鏈路curl -X POST http://localhost:8000/api/agent \ -H Content-Type: application/json \ -d {message: 北京現(xiàn)在多少度}這一套下來就是熱搜詞里說的“基于FastAPI LangChain LangGraph的AI Agent”的標(biāo)準(zhǔn)雛形。之前我在博客里看過不少項目把這三樣組合當(dāng)作“全家桶”來用實話實說這個搭配確實順——FastAPI負(fù)責(zé)Web層、LangChain負(fù)責(zé)LLM調(diào)用和工具抽象、LangGraph負(fù)責(zé)流程控制各司其職邊界清楚。4.3 三個讓Agent更“頂用”的工程習(xí)慣光把服務(wù)跑起來不算完真正“下地干活”還需要把工程細(xì)節(jié)打磨到位。分享幾個我在項目中反復(fù)打磨過的習(xí)慣每個都踩過坑。第一工具結(jié)果必須“結(jié)構(gòu)化回傳”模型。工具函數(shù)返回的不一定要是自然語言字符串也可以是一個結(jié)構(gòu)化字典。但發(fā)回給模型時要么轉(zhuǎn)成可讀文本要么保留JSON結(jié)構(gòu)并讓模型明確知道這是工具輸出。我在一個項目里遇到過模型持續(xù)誤讀工具結(jié)果的情況排查半天發(fā)現(xiàn)是工具返回了一個純數(shù)字模型把它當(dāng)成了最終答案而非參考數(shù)據(jù)。解決方案是每次都把工具結(jié)果包一層“工具執(zhí)行完成返回結(jié)果如下”的說明再放回消息列表。第二給工具加“失敗兜底”路徑。真實世界里API會超時、數(shù)據(jù)庫會連接失敗、第三方服務(wù)會返回臟數(shù)據(jù)。你在設(shè)計條件邊時一定要考慮到工具節(jié)點可能拋異常的情況。我習(xí)慣在工具節(jié)點里捕獲所有異常并把錯誤信息寫進(jìn)tool_result讓模型看到錯誤后自己決定是重試還是換方案。這比直接讓Agent崩潰優(yōu)雅得多。第三會話狀態(tài)持久化。上面例子中每次請求都從零開始實際用戶不會接受這種“失憶”對話框。LangGraph提供了checkpointer機(jī)制可以把每一步的State保存下來后續(xù)用同一個thread_id恢復(fù)上下文。FastAPI層只需要在請求里帶上session_id并傳給調(diào)用入口from langgraph.checkpoint.memory import MemorySaver checkpointer MemorySaver() app graph.compile(checkpointercheckpointer) result await graph_app.ainvoke( {messages: [{role: user, content: req.message}]}, config{configurable: {thread_id: req.session_id}} )這樣就把多輪對話、回溯歷史、狀態(tài)恢復(fù)全交給LangGraph框架處理省掉大量自己寫狀態(tài)管理的代碼。5. 常見問題與排查技巧實錄用LangGraph寫了幾個月遇到的坑不說上百也有幾十個。這一節(jié)我挑最有代表性的幾個做一份“實測速查表”幫助后來者少走彎路。5.1 狀態(tài)不更新的詭異現(xiàn)象現(xiàn)象節(jié)點函數(shù)里明明修改了State的值但下一個節(jié)點讀到的還是舊值。原因在節(jié)點函數(shù)內(nèi)部直接改傳入的state字典而不是通過返回值更新。LangGraph的狀態(tài)流轉(zhuǎn)是基于返回值的增量合并原地修改不會生效。這個問題新手最容易犯因為Python里字典本來就是可變對象改了好像也沒報錯。排查先在節(jié)點函數(shù)末尾加一個print看返回值再在下一個節(jié)點開頭打印整個State比對差異?；疽谎劬湍芏ㄎ?。5.2 Agent無限循環(huán)停不下來現(xiàn)象圖在有“工具調(diào)用 → 模型分析 → 再調(diào)用工具”的循環(huán)邊時一直執(zhí)行不停直到觸發(fā)recursion_limit報錯終止。先說結(jié)論原因條件邊里沒有寫“結(jié)束分支”或者模型每次判斷都堅持要再調(diào)一次工具形成了死循環(huán)。排查與解決編譯圖時設(shè)置recursion_limit比如app graph.compile() # 默認(rèn)25步可配置 recursion_limit10作為一種兜底保護(hù)條件邊必須包含“任務(wù)完成、直接END”的分支。我見過不少實現(xiàn)把route_after_tool只寫了“繼續(xù)調(diào)用工具”和“生成答案”兩條路但漏了“任務(wù)其實已經(jīng)完成直接結(jié)束”這種判定導(dǎo)致模型反復(fù)糾結(jié)在工具結(jié)果消息里明確提示模型“如果已有足夠信息請直接給出最終答案”這類Prompt工程微調(diào)真的管用5.3 工具消息格式不對導(dǎo)致LLM調(diào)用報錯現(xiàn)象調(diào)用模型時報錯提示消息序列中roletool的消息必須緊跟在對應(yīng)的assistant消息之后。原因LangGraph允許任意修State但LLM對消息序列的格式有嚴(yán)格要求。如果你在messages里追加了一條工具結(jié)果卻沒把它放在合適的對話位置——比如夾在兩條user消息之間——模型API就會直接拒絕。排查把傳給模型的messages列表完整打印出來檢查順序。通常正確的序列是user提問 →assistant說“我要調(diào)用工具” →tool返回結(jié)果 →assistant最終回答。如果在圖里跳過了“assistant要調(diào)用工具”這條消息就會出問題。5.4 并發(fā)請求串號的坑現(xiàn)象線上服務(wù)并發(fā)高了以后用戶A的請求拿到了用戶B的上下文。原因早期我在FastAPI里把State對象定義成了模塊級全局變量多個請求共享了同一個State實例。LangGraph本身是無狀態(tài)的它的State是每次調(diào)用的參數(shù)但如果你在外面用了全局字典保存“會話狀態(tài)”并發(fā)場景就會互相覆蓋。排查把State和Graph實例徹底分開Graph是只讀的、可復(fù)用的State是每次調(diào)用重新創(chuàng)建的。會話級狀態(tài)一律走checkpointer或者外部存儲Redis、數(shù)據(jù)庫不要放在模塊級變量里。5.5 我的避坑速查表問題類別典型表現(xiàn)最快解法狀態(tài)不更新下個節(jié)點讀到舊值檢查是否在節(jié)點內(nèi)直接改字典改為return新字段死循環(huán)反復(fù)調(diào)用工具不停加recursion_limit條件邊增加終止分支優(yōu)化終止Prompt消息順序錯亂LLM API拒絕請求打印messages順序確保tool消息跟在assistant消息后并發(fā)串?dāng)?shù)據(jù)多用戶上下文交叉禁用模塊級可變State改用checkpointer或外部存儲節(jié)點異常吞沒圖靜默結(jié)束沒結(jié)果在節(jié)點內(nèi)捕獲異常并寫入State字段讓模型看到錯誤信息工具參數(shù)錯誤模型傳錯參數(shù)值優(yōu)化工具函數(shù)docstring加參數(shù)格式說明與示例最后一點個人體會從LangChain鏈?zhǔn)秸{(diào)用轉(zhuǎn)到LangGraph最直觀的改變是思維方式的轉(zhuǎn)換不要再想“這個流程按什么順序跑”而是想“整個系統(tǒng)有哪些狀態(tài)、哪些動作、狀態(tài)之間如何流轉(zhuǎn)”。這種建模方式更接近真實世界的業(yè)務(wù)邏輯也因此更抗折騰。我個人的建議是剛開始不要追求復(fù)雜從一個只有三個節(jié)點、一條條件邊的圖開始把工具調(diào)用循環(huán)跑通再逐步加持久化、加并行節(jié)點、加人工審批介入。LangGraph的復(fù)雜度是按需累加的你要做的只是在每個階段守住狀態(tài)的清晰邊界。把這套基礎(chǔ)設(shè)施搭好AI Agent就不再是演示臺上的玩具而是真正能在業(yè)務(wù)流程里穩(wěn)定運(yùn)轉(zhuǎn)的“勞動力”。