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