2026 年的 AI 應用開發(fā)已經不是“調 API、寫 prompt”就能撐住的階段了。項目中只要涉及多步驟決策、外部工具調用、多輪狀態(tài)維護LangChain、MCP、LangGraph 這三個關鍵詞就一定會出現(xiàn)。它們的關系并不復雜LangChain 負責把大模型和工具編排起來MCP 負責把外部工具接入標準化LangGraph 負責把多步驟流程變成可控狀態(tài)圖最后落地的形態(tài)就是 Agent。這篇文章的核心不是講概念而是走一遍最小可運行鏈路環(huán)境配置、定義工具、寫 Agent、接 MCP、用 LangGraph 搭一個多步工作流再把它封裝成 API跑一個批量任務。整個過程會盡量貼工程實踐不繞彎不堆術語。你跟著做完一遍至少能知道 Agent 項目從“能跑”到“能交付”之間到底隔了哪些關鍵節(jié)點。先交代硬件與門檻如果走純 API 模式只需要 Python 3.10、一個模型 API Key 和網絡完全沒有顯卡壓力如果要本地模型推理硬件門檻取決于模型大小常見的 7B 量化模型建議 8G 以上顯存沒有獨顯也能用 CPU 跑但速度會明顯下降。這看起來是現(xiàn)代 AI 項目里非常標準的門檻但真正卡住人的往往不是顯卡而是依賴環(huán)境、狀態(tài)管理和工具調用接口沒有理順。1. 核心能力速覽先給一張規(guī)格表方便快速判斷這個技術棧適不適合你。能力項說明技術棧LangChain MCP LangGraph Agent項目類型AI Agent 應用開發(fā)框架組合主要能力LLM 調用、工具構建、MCP 工具接入、圖狀態(tài)工作流、批量任務、API 封裝運行方式Python 腳本 / CLI / FastAPI 服務硬件門檻純 API 模式無 GPU 要求本地模型模式取決于模型大小建議 8G 以上顯存接口 API支持需要自己封裝 FastAPI 或類似服務批量任務支持可腳本循環(huán)、異步隊列、LangGraph 批處理適合讀者Python 開發(fā)者、AI 應用開發(fā)者、想從 Demo 走向工程化的團隊部署復雜度中等難點在依賴兼容和工具調用鏈路調試這套組合最明顯的優(yōu)勢是“分層清晰”。LangChain 負責模型與工具之間的膠水MCP 負責統(tǒng)一工具接入格式LangGraph 負責管理復雜流程的分支和狀態(tài)。單獨拆開每一個都夠用但它們組合起來才是 2026 年 Agent 應用的主流骨架。2. 四個核心概念別再搞混 LangChain、MCP、LangGraph 和 Agent很多人第一次接觸這套技術棧時最常問的問題是“它們之間到底有什么區(qū)別”。這里用一個表格先做出區(qū)分然后逐一說清楚。組件定位主要作用典型應用LangChain編排框架封裝模型調用、Prompt 模板、工具調用、RAG 等基礎能力把 LLM 和外部工具連起來MCP工具接入?yún)f(xié)議用統(tǒng)一協(xié)議讓 Agent 調用文件、數(shù)據(jù)庫、HTTP 服務等外部能力標準化工具接入避免為每個工具寫適配代碼LangGraph圖狀態(tài)工作流引擎用節(jié)點和邊構建有狀態(tài)、可分支、可恢復的 Agent 流程多步驟流程、條件分支、多智能體協(xié)作Agent產品形態(tài)根據(jù)用戶目標自主決策循環(huán)調用模型和工具直到完成任務客服機器人、自動化助手、數(shù)據(jù)分析 Agent2.1 LangChain不是“一個庫”而是一整套編排生態(tài)LangChain 最核心的貢獻是讓“模型調用”這件事變得更工程化。你可以用統(tǒng)一的接口對接不同模型供應商可以用 Prompt 模板復用提示詞可以把一個普通函數(shù)包裝成 Agent 可調用的工具也可以快速做 RAG 檢索。但在 2026 年這個時間點LangChain 已經不適合當作“全部答案”。它更準確的定位是“基礎工具箱”模型接口、輸出解析、工具包裝、記憶管理這些能力LangChain 都能給。真正復雜的狀態(tài)流轉和分支邏輯建議交給 LangGraph 處理。2.2 MCP把“工具接入”變成標準協(xié)議MCP 全稱 Model Context Protocol解決的是“每一家服務都要寫一套自定義工具接入”的問題。它把文件操作、數(shù)據(jù)庫查詢、HTTP 請求、瀏覽器操作、設計工具能力等封裝成標準接口供 Agent 按統(tǒng)一格式調用。從熱門生態(tài)來看MCP 已經延伸到很多方向游戲引擎工具鏈、UI 設計工具、數(shù)據(jù)平臺、自動化和辦公軟件都在接入。它的存在讓 Agent 的工具生態(tài)從“每個工具一套 SDK”變成了“一套協(xié)議訪問所有工具”。2.3 LangGraph把流程從混沌循環(huán)變成可控狀態(tài)圖普通 Agent 是一個 while 循環(huán)讓模型決定下一步調用什么工具然后重復直到任務完成。這種模式在簡單場景下很自然但一旦需要固定流程、條件分支、人工審核、多角色協(xié)作單純循環(huán)就會變得很難維護。LangGraph 用圖的方式顯式定義節(jié)點和邊。每個節(jié)點是一個計算步驟每條邊決定下一步走到哪里所有中間結果都存在狀態(tài)對象里。這樣 Agent 的每一步都是可觀測、可回放、可中斷恢復的。2.4 順帶說清Computer Use 與 MCP 不是一回事搜索里經常把 Computer Use 和 MCP 放在一起比較這里值得說明。Computer Use 是指讓模型直接操作計算機界面比如移動鼠標、點擊按鈕、輸入文字本質是“模擬人去操作系統(tǒng)”MCP 則是通過協(xié)議直接調用工具的編程接口比如查詢數(shù)據(jù)庫、寫文件、調 HTTP API本質是“讓程序之間標準化通信”。在實際項目中兩者可以互補需要操作沒有 API 的舊系統(tǒng)時Computer Use 更合適目標系統(tǒng)提供 API 時MCP 更快、更穩(wěn)定。不要因為名字里都有“工具連接”就把它們混成同一個東西。2.5 適用場景與使用邊界這套組合真正適合的場景是“目標明確但路徑不固定”的任務。例如讓 Agent 根據(jù)用戶查詢去查數(shù)據(jù)庫、再寫一份 Markdown 報告讓 Agent 搜集多個數(shù)據(jù)源后做對比分析讓 Agent 按照固定的質檢流程逐項檢查輸入內容并輸出結構化結果。這些場景里Agent 需要決策、需要調用多個工具、需要維護中間狀態(tài)正是 LangChain MCP LangGraph 的強項。不適合的場景也很明顯如果只是單輪問答、一次性文案生成、簡單分類任務直接用大模型調用接口更輕快引入全套 Agent 編排反而增加復雜度和延遲。安全與合規(guī)邊界一定要前置考慮。當 Agent 被允許調用外部工具時它就有了“行動能力”。所有工具調用必須限定在合法授權范圍內訪問數(shù)據(jù)庫要確認賬號權限抓取網頁要遵守目標站點條款處理用戶隱私數(shù)據(jù)要遵守相關法規(guī)。涉及人臉、聲音、版權素材的場景更要確認授權鏈完整。任何工具接入上線前都應先在隔離環(huán)境做權限測試。3. 2026 年 LangChain MCP LangGraph 環(huán)境準備在寫第一行代碼之前先把環(huán)境準備好。下面是一個經過整理的通用檢查清單適用于大多數(shù) Windows / macOS / Linux 開發(fā)機。3.1 基礎環(huán)境清單檢查項建議要求操作系統(tǒng)Windows 10/11、macOS、Ubuntu 20.04Python 版本Python 3.10 或更高包管理工具pip 或 uv模型訪問方式OpenAI 兼容 API Key或本地 Ollama / vLLM 服務網絡能訪問模型 API國內環(huán)境可用 OLLAMA 或國產模型平臺需按實際服務地址配置磁盤空間純 API 模式 2G 足夠本地模型模式預留模型文件空間7B 量化模型約 4-8G端口預留 8080、8000 等端口給 API 服務3.2 創(chuàng)建虛擬環(huán)境并安裝核心依賴建議所有項目都在虛擬環(huán)境里運行避免系統(tǒng) Python 環(huán)境被污染。# 創(chuàng)建虛擬環(huán)境python 版本需要 3.10 python -m venv venv # 激活虛擬環(huán)境Windows 用 venv\Scripts\activatemacOS/Linux 用 source venv/bin/activate source venv/bin/activate # 升級 pip pip install --upgrade pip # 安裝核心依賴 pip install langchain langgraph mcp openai fastapi uvicorn python-dotenv如果你在國內網絡環(huán)境pip 安裝失敗時可以使用清華鏡像源pip install -i https://pypi.tuna.tsinghua.edu.cn/simple langchain langgraph mcp openai fastapi uvicorn python-dotenv3.3 配置模型訪問新建一個.env文件保存模型密鑰和基礎地址。OPENAI_API_KEY你的_key_或者_sk-xxx OPENAI_BASE_URLhttps://api.openai.com/v1 MODEL_NAMEgpt-4o-mini如果使用本地模型可以指向 Ollama 或其他 OpenAI 兼容服務OPENAI_API_KEYollama OPENAI_BASE_URLhttp://127.0.0.1:11434/v1 MODEL_NAMEqwen2.5:7b這里的關鍵是保持“OpenAI 兼容接口”這一層抽象。只要模型服務提供 OpenAI 兼容 APILangChain 就可以用同一套代碼切換在線和本地模型。4. 最小 Agent 啟動先跑通一條主鏈路第一次做 Agent 項目不要一上來就多智能體、圖工作流、幾十個工具。先把最小鏈路跑通一個模型、一個工具、一個 Agent。4.1 定義一個計算工具并創(chuàng)建 Agent下面代碼中我定義了add和get_current_time兩個工具然后創(chuàng)建了一個 ReAct 模式的 Agent。ReAct 的意思是模型會先推理Reason再決定調用什么工具Act然后根據(jù)工具結果繼續(xù)推理。import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import create_react_agent, AgentExecutor from langchain.tools import tool from langchain_core.prompts import PromptTemplate load_dotenv() # 初始化模型 llm ChatOpenAI( modelos.getenv(MODEL_NAME, gpt-4o-mini), temperature0, ) # 定義工具加法計算 tool def add(a: int, b: int) - int: 計算兩個整數(shù)相加的結果。 return a b # 定義工具獲取當前時間 tool def get_current_time() - str: 返回當前系統(tǒng)時間適合回答時間相關問題。 import datetime return datetime.datetime.now().strftime(%Y-%m-%d %H:%M:%S) tools [add, get_current_time] # ReAct Agent 提示詞模板這里使用最簡模板 prompt PromptTemplate.from_template(Answer the following questions as best you can. You have access to tools: {tools}. Use the following format:\nQuestion: the input question\nThought: you should always think about what to do\nAction: the action to take, should be one of [{tool_names}]\nAction Input: the input to the action\nObservation: the result of the action\n... (this Thought/Action/Action Input/Observation can repeat N times)\nThought: I now know the final answer\nFinal Answer: the final answer to the original input question\n\nQuestion: {input}\nThought: {agent_scratchpad}) agent create_react_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue)4.2 運行 Agent 并觀察鏈路# 測試 1純工具調用 result1 agent_executor.invoke({input: 請計算 12345 67890 等于多少}) print(結果1, result1[output]) # 測試 2混合問題 result2 agent_executor.invoke({input: 當前時間是什么并且計算 3 和 5 的和}) print(結果2, result2[output])預期輸出不是最重要的重要的是verboseTrue時打印出的中間過程。你會看到模型先輸出 Thought再輸出 Action再拿到 Observation最后給出 Final Answer。這代表 Agent 的核心決策循環(huán)已經跑通了。4.3 判斷成功與排查方向如果結果里出現(xiàn)工具返回值并且 Final Answer 引用該返回值說明鏈路成功。如果 Agent 直接給出答案但沒有調用工具可能是模型選擇跳過工具也可能是 prompt 中沒有強調“必須使用工具”。如果報Could not parse LLM output通常是模型輸出格式不符合 ReAct 模板可以開啟handle_parsing_errorsTrue并檢查 prompt。這一步跑通后再往里面加 MCP 和 LangGraph 就有了穩(wěn)定的地基。5. MCP 實戰(zhàn)讓 Agent 通過標準協(xié)議接入外部工具MCP 的核心價值在“接入標準”。假設你想讓 Agent 讀取一個文件、查一次數(shù)據(jù)庫、調一個 HTTP 接口傳統(tǒng)做法是用 LangChain 的tool一個個封裝。工具少還好工具一旦多了每個工具的入?yún)?、鑒權、錯誤處理都不一樣代碼很快就失控。MCP 的做法是定一個統(tǒng)一協(xié)議服務端暴露工具客戶端負責發(fā)現(xiàn)和調用。Agent 不需要關心工具背后的實現(xiàn)語言和部署位置只要走 MCP 協(xié)議即可。5.1 用 Python 實現(xiàn)一個最簡 MCP Server可以用mcp官方 Python SDK 寫一個最簡 Server。下面代碼里我創(chuàng)建了一個“加法工具”和“文件讀取工具”用來模擬真實工具服務。# server.py from mcp.server.fastmcp import FastMCP mcp FastMCP(demo-tools) mcp.tool() def add(a: int, b: int) - int: 計算兩個整數(shù)相加的結果。 return a b mcp.tool() def read_txt_file(path: str) - str: 讀取指定 txt 文件的文本內容。 with open(path, r, encodingutf-8) as f: return f.read() if __name__ __main__: mcp.run(transportstdio)運行這個服務python server.py注意當前示例使用stdio作為傳輸層這意味著 MCP Server 由父進程拉起并通過標準輸入輸出通信。如果是遠程服務可以改成streamable-http或sse模式但最終配置方式要根據(jù)你使用的 MCP Client SDK 來確定。5.2 LangChain 接入 MCP 工具不同版本的 LangChain MCP 適配器 API 略有差異。下面給出一個思路性的通用流程實際代碼以官方文檔為準啟動 MCP Server 進程。用langchain-mcp-adapters或其他適配器將 MCP 工具轉換為 LangChain 工具列表。將工具列表傳給 Agent 或 LangGraph 節(jié)點。# 偽代碼示意實際 API 需要按你使用的適配器版本調整 # from langchain_mcp_adapters.client import load_mcp_tools # from mcp import ClientSession, StdioServerParameters # 創(chuàng)建會話并加載工具 mcp_tools await load_mcp_tools( server_paramsStdioServerParameters( commandpython, args[server.py], ) ) # 將 MCP 工具與 LangChain 工具合并 all_tools mcp_tools這個階段最容易踩的坑是“工具名沖突”。MCP Server 里的工具名和本地tool函數(shù)名不能重復否則 Agent 調用時可能路由錯誤。5.3 MCP 使用的合規(guī)邊界MCP 讓 Agent 擁有了“執(zhí)行能力”這既是優(yōu)勢也是風險。接入數(shù)據(jù)庫前必須用只讀賬號測試接入文件系統(tǒng)時應限定在沙箱目錄內接入 HTTP 服務時要確認目標服務的鑒權和調用頻率限制。生產環(huán)境不要直接給 Agent 開放所有系統(tǒng)權限盡量按最小權限原則配置。6. LangGraph 實戰(zhàn)把 Agent 變成可控狀態(tài)工作流有了最小 Agent很多人以為就夠了。但真實業(yè)務里“連續(xù)做三步其中第二步根據(jù)第一步結果走不同分支”是剛需。LangGraph 的價值在于把流程畫成圖每個步驟都能被觀察和控制。6.1 一個最簡單的 LangGraph 狀態(tài)圖先看一個最小示例一個狀態(tài)對象經過兩個節(jié)點最終輸出。from langgraph.graph import StateGraph, START, END from typing import TypedDict class State(TypedDict): messages: list def node_setup(state: State): return {messages: state[messages] [已初始化上下文]} def node_summary(state: State): return {messages: state[messages] [已生成摘要]} # 構建圖 graph StateGraph(State) graph.add_node(setup, node_setup) graph.add_node(summary, node_summary) graph.add_edge(START, setup) graph.add_edge(setup, summary) graph.add_edge(summary, END) app graph.compile() # 運行 result app.invoke({messages: []}) print(result[messages])預期輸出是[已初始化上下文, 已生成摘要]這個示例雖然簡單但已經體現(xiàn)了 LangGraph 和普通 Agent 的關鍵差異節(jié)點順序是顯式的狀態(tài)是跨節(jié)點傳遞的流程是可追蹤的。6.2 用 LangGraph 做“檢索 工具調用 總結”工作流實際項目中更常見的需求是用戶輸入問題Agent 先決定是否檢索資料再調用工具最后總結。這個流程如果寫成普通 ReAct 循環(huán)每一步模型都有“自由發(fā)揮”的空間用 LangGraph 則可以把步驟固定下來。from langgraph.graph import StateGraph, START, END from typing import TypedDict, Optional class WorkflowState(TypedDict): question: str search_keyword: Optional[str] search_result: Optional[str] final_answer: str def decide_search(state: WorkflowState): # 這里可以調用模型判斷是否需要檢索簡化處理只要包含“資料”就設置關鍵詞 if 資料 in state[question]: return {search_keyword: state[question].replace(資料, ).strip()} return {search_keyword: None} def search_web(state: WorkflowState): if state[search_keyword] is None: return {search_result: 無需檢索} # 實際項目里可以替換為搜索引擎 API 或內部知識庫 return {search_result: f模擬檢索結果{state[search_keyword]}} def generate_answer(state: WorkflowState): state[final_answer] f基于檢索結果生成回答{state[search_result]} return state graph StateGraph(WorkflowState) graph.add_node(decide, decide_search) graph.add_node(search, search_web) graph.add_node(answer, generate_answer) graph.add_edge(START, decide) graph.add_conditional_edges( decide, lambda state: search if state[search_keyword] else answer, ) graph.add_edge(search, answer) graph.add_edge(answer, END) app graph.compile() result app.invoke({question: 請幫我查找 Python 資料}) print(result[final_answer])這里的核心在add_conditional_edges根據(jù)decide節(jié)點的結果決定走向。沒有 LangGraph 時這種分支邏輯要在代碼里手寫if/else加循環(huán)管理狀態(tài)多了之后很難維護。如果你需要多輪對話能力LangGraph 還支持Checkpointer保存狀態(tài)。這樣 Agent 請求中斷后可以恢復上下文而不是每次重新構建歷史。6.3 LangGraph 增加外部能力的思路關于“LangGraph 怎么增加 skill”本質上是兩類操作增加工具節(jié)點或增加普通計算節(jié)點。工具節(jié)點可以加載前面定義的 MCP 工具普通計算節(jié)點則做數(shù)據(jù)清洗、格式轉換、人工審核等業(yè)務邏輯。模型不是所有步驟都必須參與只有需要“理解力”的節(jié)點才接入 LLM這樣既能節(jié)省 Token 又能提高流程穩(wěn)定性。7. API 化與批量任務從腳本走向服務Agent 腳本跑通了還不夠工程落地時通常需要暴露 HTTP 接口并支持批量執(zhí)行。7.1 用 FastAPI 封裝 Agent 接口下面用 FastAPI 寫一個最簡封裝把 Agent 或 LangGraph 工作流暴露為 HTTP 服務。# api.py import os from dotenv import load_dotenv from fastapi import FastAPI from pydantic import BaseModel from langchain_openai import ChatOpenAI from langchain.agents import create_react_agent, AgentExecutor from langchain.tools import tool load_dotenv() app FastAPI(titleAgent API) # 初始化模型和 Agent llm ChatOpenAI(modelos.getenv(MODEL_NAME, gpt-4o-mini), temperature0) tool def add(a: int, b: int) - int: 計算兩個整數(shù)相加的結果。 return a b # 簡化示例這里省略 ReAct prompt 詳細配置實際開發(fā)建議模塊化 # from langchain.agents import initialize_agent # agent_executor initialize_agent(tools[add], llmllm, agentzero-shot-react-description) class AgentRequest(BaseModel): prompt: str app.post(/agent/run) def run_agent(req: AgentRequest): # 實際調用 agent_executor這里用簡化邏輯說明結構 result {output: f模擬 Agent 輸出{req.prompt}} return {status: ok, result: result[output]} # 健康檢查 app.get(/health) def health(): return {status: alive}啟動服務uvicorn api:app --host 127.0.0.1 --port 8000注意上面的示例中 Agent 部分做了簡化標注。實際項目應該把 Agent 初始化邏輯提取成獨立模塊API 層只負責請求校驗和結果返回避免每個請求都重復創(chuàng)建模型實例。7.2 curl 測試接口服務啟動后用 curl 驗證接口是否通curl -X POST http://127.0.0.1:8000/agent/run \ -H Content-Type: application/json \ -d {prompt: 請計算 2 和 3 的和}7.3 批量任務循環(huán)、并發(fā)與失敗重試批量任務的實現(xiàn)不需要一開始就上 Celery。先用簡單的順序循環(huán)或線程池確認邏輯穩(wěn)定后再升級隊列。import json import time import requests # 讀取任務配置 with open(batch_config.json, r, encodingutf-8) as f: config json.load(f) prompts config[prompts] output_dir config[output_dir] for idx, prompt in enumerate(prompts): try: resp requests.post(config[api_url], json{prompt: prompt}, timeout120) resp.raise_for_status() data resp.json() with open(f{output_dir}/result_{idx}.json, w, encodingutf-8) as f: json.dump(data, f, ensure_asciiFalse, indent2) print(f[OK] {idx}: {prompt[:20]}) except Exception as e: print(f[FAIL] {idx}: {e}) # 簡單重試一次 time.sleep(2)配置文件示例{ api_url: http://127.0.0.1:8000/agent/run, prompts: [ 計算 1 加 1, 計算 10 加 20, 計算 100 加 200 ], output_dir: ./outputs }批量任務最容易出現(xiàn)的問題是“單條失敗拖垮整個批”。建議每個任務獨立捕獲異常、獨立寫結果文件并記錄失敗原因。任務量大時再加上最大重試次數(shù)、超時控制和并發(fā)數(shù)上限。7.4 接口安全提醒FastAPI 服務啟動后默認沒有鑒權。如果只是本機調試綁定127.0.0.1就夠了如果要部署到服務器至少加 API Key 校驗并把服務放在內網網關之后。Agent 擁有工具調用能力接口暴露在公網等于把工具權限暴露在公網這是一條必須守住的底線。8. 資源占用與性能觀察LangChain MCP LangGraph 這套技術棧的資源消耗和傳統(tǒng) Web 服務不同瓶頸往往不是 CPU 或顯存而是 Token 消耗和工具調用耗時。8.1 不同運行模式的資源觀察重點運行模式主要瓶頸觀察方式純 API 模式網絡延遲、Token 消耗在代碼里記錄每次模型調用的輸入/輸出 Token本地模型GPU 推理顯存占用、顯存帶寬nvidia-smi 實時觀察本地模型CPU 推理CPU 占用、推理速度任務管理器或 top 命令混合模式API 本地工具工具響應時間、并發(fā)連接數(shù)日志記錄每個節(jié)點的耗時如果走本地模型路線推薦先量化再部署。常見 7B 模型 4bit 量化后占用約 4-6G 顯存有條件可以先用小模型驗證整個鏈路再切到更大模型。顯存占用需要以實際模型版本和推理參數(shù)為準不同量化方式差異很大。8.2 上下文長度是隱藏成本Agent 每次調用模型時都要把歷史消息、系統(tǒng)提示詞、工具定義、工具返回結果拼進上下文。上下文越長Token 消耗越大響應越慢。建議對工具返回結果做截斷只返回必要字段多輪對話時定期裁剪歷史消息或者用摘要替代完整歷史。8.3 LangGraph 狀態(tài)大小控制LangGraph 把所有節(jié)點中間結果都放到狀態(tài)對象里狀態(tài)字段設計得越寬內存壓力和后續(xù)檢索成本越高。建議只保存下一步需要的字段不要把大段原始數(shù)據(jù)堆在狀態(tài)中?？梢远ㄆ谇謇韒essages歷史或寫入外部存儲。9. 常見問題與排查方法問題現(xiàn)象可能原因排查方式解決方案pip 安裝依賴失敗網絡問題、Python 版本過低、依賴版本沖突查看完整報錯確認 Python 版本使用鏡像源升級 Python或逐個安裝依賴Agent 不調用工具Prompt 未強調工具使用、工具描述不清晰、工具列表為空開啟 verbose 查看推理過程加強 Prompt 約束優(yōu)化工具描述Agent 報Could not parse LLM output模型輸出格式不符合 ReAct 模板查看原始模型輸出設置handle_parsing_errorsTrue或更換更強模型MCP 連接失敗transport 類型不匹配、Server 啟動報錯、鑒權失敗先單獨運行 MCP Server確認工具可調用檢查 StdioServerParameters 參數(shù)和 Server 日志LangGraph 節(jié)點未執(zhí)行邊的連接錯誤、條件邊返回了不存在的節(jié)點名打印每個節(jié)點返回的 key檢查add_conditional_edges返回值與節(jié)點名一致批量任務卡住單條請求無超時、工具調用死循環(huán)、服務端并發(fā)限制給請求設置 timeout查看服務端日志每條任務加超時和重試限制并發(fā)數(shù)上下文溢出超過模型 context 限制統(tǒng)計請求中 token 數(shù)裁剪歷史、截斷工具返回、用摘要壓縮上下文agent execution terminated due to error工具步驟拋異常未捕獲打開 verbose 或查看異常堆棧在工具函數(shù)內捕獲異常返回友好錯誤信息API 請求超時模型推理太慢、工具響應慢、FastAPI 同步阻塞觀察每個節(jié)點耗時改用異步接口設置更長 timeout或增加超時重試排查口訣是先看日志再拆鏈路最后查依賴。Agent 項目里大量問題不是模型不夠聰明而是工具返回格式沒處理好、狀態(tài)字段對不上、依賴版本不一致。10. 最佳實踐與使用建議第一先把最小鏈路跑通再擴展。第一次實驗建議只用一個模型、兩個工具、一個 Agent確認模型能正確調用工具后再引入 MCP 和 LangGraph。第二工具函數(shù)要“單一職責”。一個工具只做一件事描述里寫清楚“什么時候用、參數(shù)代表什么、返回值是什么”。模型是靠描述決定是否調用工具的描述寫得不清晰Agent 就會選擇跳過。第三把配置和密鑰外置。模型名、API Key、數(shù)據(jù)庫地址都不要寫死在代碼里用.env或配置中心管理。密鑰文件加入.gitignore。第四給批量任務加日志、超時和失敗重試。上線前先跑一個 3-5 條的小批量樣本確認輸出格式穩(wěn)定再跑全量。第五關注狀態(tài)管理和上下文成本。LangGraph 的狀態(tài)字段盡量精簡歷史消息按策略裁剪工具返回體做截斷。Token 消耗要提前預估不要等月底賬單出來再吃驚。第六從開發(fā)第一天就考慮合規(guī)。Agent 的所有工具調用都應該有權限邊界和審計日志。誰在什么時間調用了哪個工具執(zhí)行了哪些操作這些記錄既是排查問題的依據(jù)也是合規(guī)審計的底稿。11. 總結與下一步這套技術棧里最值得優(yōu)先嘗試的是“最小 Agent MCP Server LangGraph 工作流”三件套。你先用 LangChain 跑通模型調工具再用 MCP 把外部能力接入標準化最后用 LangGraph 把流程固定成可控狀態(tài)圖整個過程約兩小時就能完成首輪驗證。最先要驗證的是兩件事工具是否真的被模型調用狀態(tài)流轉是否符合預期。如果這兩個環(huán)節(jié)穩(wěn)定后面的 API 封裝和批量任務只是工程量問題不算技術風險。最容易踩的坑分別是依賴版本不齊、工具函數(shù) schema 寫錯、線程阻塞導致接口超時。這三類問題都不會直接報出“你這里寫錯了”而是以啟動失敗、解析失敗或超時的形式出現(xiàn)排查時要有耐心。后續(xù)可以繼續(xù)擴展的方向包括接入 RAG 增強知識庫能力、做多智能體協(xié)作流程、加上 LangSmith 或 Langfuse 做可觀測性、把批量任務升級為獨立消息隊列。也可以嘗試把當前鏈路接到本地模型上對比 Token 成本和響應速度找到適合自己業(yè)務的性價比方案。建議收藏備用。工具鏈還在快速演進但只要掌握了“模型 工具 狀態(tài)圖”這個核心骨架后續(xù)版本怎么變你都能很快跟上。