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