行流程拆解：從ReAct到工具調(diào)用)
先問大家一個問題當(dāng)你在開發(fā)一個完整的 AI Agent 時最頭疼的是什么可能很多人會說“模型能力不夠”“工具不好接入”但真正把一個 Agent 從 Demo 推到可落地狀態(tài)時你會發(fā)現(xiàn)最復(fù)雜的其實是Agent 的執(zhí)行流程模型是怎么決定調(diào)用哪個工具的工具返回結(jié)果之后又要做什么循環(huán)什么時候終止如果中間報錯了整個流程又該怎么恢復(fù)這些問題如果只靠“調(diào) LLM 拼 Prompt”來解決會非常容易失控。LangChain 在 0.6 到 0.9 這個版本區(qū)間對 Agent 模塊做了大量重構(gòu)把很多隱式的執(zhí)行邏輯收斂到了框架內(nèi)部讓開發(fā)者可以把更多精力放在業(yè)務(wù)本身。但框架收斂邏輯并不代表我們不需要理解執(zhí)行流程。恰恰相反只有把執(zhí)行鏈路拆解清楚才能在真正遇到“Agent 不按預(yù)期工作”的時候快速定位問題。本文就把 LangChain 6-9 版本中的 Agent 執(zhí)行流程完整拆開從核心概念、環(huán)境準(zhǔn)備、組件原理到完整實戰(zhàn)和常見排查思路一次性講透。無論你是剛開始接觸 langchain 入門還是在項目中已經(jīng)用到 ai agent 開發(fā)這篇內(nèi)容都能給你一個清晰的框架。1. 背景與核心概念1.1 什么是 Agent在了解 LangChain 的 Agent 執(zhí)行流程之前我們需要先明確一件事Agent 到底是什么它和我們平時調(diào)大模型接口有什么區(qū)別。如果只是調(diào)用大模型流程非常簡單你給模型一個 Prompt模型返回一個回答。這個回答可能是文本、JSON、代碼片段但本質(zhì)上模型只是在“生成內(nèi)容”。而 Agent 是一個擁有“決策能力”的智能體。它不只是回答問題而是可以為了完成目標(biāo)自主選擇調(diào)用什么工具、按什么順序執(zhí)行、如何利用工具返回的信息繼續(xù)下一步。舉個例子用戶問“上海今天適合穿什么衣服”。普通模型只能根據(jù)它的訓(xùn)練知識給出模糊建議。但一個有工具的 Agent可以調(diào)用天氣插件查詢上海實時天氣拿到溫度、濕度、風(fēng)力數(shù)據(jù)再決定告訴用戶穿什么衣服。這個過程中Agent 是“主動”的它在不斷決定“下一步做什么”。1.2 LangChain Agent 解決什么問題LangChain 提供了一套標(biāo)準(zhǔn)化的 Agent 構(gòu)建框架。在 LangChain 6-9 這個版本區(qū)間框架解決的問題可以歸納為三塊Agent 決策鏈路讓模型根據(jù)用戶輸入和歷史信息推理出下一步應(yīng)該調(diào)用哪個工具。工具調(diào)用與結(jié)果回傳封裝了 Function Calling 和 Tool Calling 的標(biāo)準(zhǔn)流程讓 Agent 可以穩(wěn)定地觸發(fā)工具并拿到結(jié)構(gòu)化結(jié)果。循環(huán)控制Agent 不是跑一次就結(jié)束而是反復(fù)執(zhí)行“推理 - 行動 - 觀察”的循環(huán)直到得到最終答案或達(dá)到最大迭代次數(shù)。這些能力疊加起來就是 Agent 執(zhí)行流程的核心骨架。1.3 Agent 與 LangGraph 的關(guān)系如果你在搜索 langchain agent 相關(guān)內(nèi)容一定會頻繁看到一個叫 LangGraph 的詞。它們并不是替代關(guān)系而是側(cè)重點不同。LangChain 的 Agent 模塊也就是 AgentExecutor提供的是標(biāo)準(zhǔn)化的執(zhí)行流程封裝適合快速搭建 AgentLangGraph 則是一個更底層的編排框架可以讓你用圖的方式手動控制每個節(jié)點的狀態(tài)轉(zhuǎn)換。簡單理解AgentExecutor 自動化的循環(huán)引擎 LangGraph 可自定義的編排引擎在 LangChain 6-9 版本中AgentExecutor 底層也已經(jīng)可以基于 LangGraph 實現(xiàn)但在使用層面AgentExecutor 隱藏了圖的復(fù)雜度對多數(shù)業(yè)務(wù)場景來說已經(jīng)足夠了。如果你要對執(zhí)行流程做非常細(xì)粒度的控制再考慮直接上手 LangGraph。2. 環(huán)境準(zhǔn)備與版本說明2.1 基礎(chǔ)環(huán)境在開始代碼實戰(zhàn)前先把環(huán)境準(zhǔn)備好。本文示例基于 Python 3.10LangChain 版本以 0.6.x 至 0.9.x 區(qū)間為主。由于該區(qū)間內(nèi)部分 API 仍在迭代實際使用時請以你自己的環(huán)境中安裝的版本為準(zhǔn)。# 建議使用虛擬環(huán)境 python -m venv langchain-agent-demo source langchain-agent-demo/bin/activate # 安裝 LangChain 本體 pip install langchain # 安裝 LangChain 官方社區(qū)包 pip install langchain-community # 安裝 OpenAI 集成包本文示例使用 OpenAI 兼容接口 pip install langchain-openai # 安裝用于加載環(huán)境變量的庫 pip install python-dotenv如果你使用的是國內(nèi)可訪問的大模型服務(wù)比如 DeepSeek、通義千問、Kimi、智譜等只要它兼容 OpenAI 的接口格式也可以通過langchain-openai或自定義ChatOpenAI的base_url來接入。本文示例會預(yù)留這部分配置說明。2.2 環(huán)境變量配置在項目根目錄創(chuàng)建.env文件內(nèi)容如下# 你的模型 API Key OPENAI_API_KEYyour-api-key-here # 如果你使用的是兼容 OpenAI 接口的服務(wù)可以指定 base_url OPENAI_API_BASEhttps://api.example.com/v1 # 實際項目中推薦使用的模型名稱 MODEL_NAMEgpt-4o-mini注意OPENAI_API_BASE是可選的。如果使用 OpenAI 官方服務(wù)不需要配置這一項。加載方式import os from dotenv import load_dotenv load_dotenv() api_key os.getenv(OPENAI_API_KEY) base_url os.getenv(OPENAI_API_BASE) model_name os.getenv(MODEL_NAME, gpt-4o-mini)2.3 項目結(jié)構(gòu)本文示例項目結(jié)構(gòu)如下langchain-agent-demo/ ├── .env ├── main.py └── tools/ ├── __init__.py └── weather_tools.py我們通過一個“天氣查詢 計算器”的 Agent 案例完整演示 Agent 執(zhí)行流程。這個案例雖然業(yè)務(wù)簡單但能覆蓋 Agent 執(zhí)行鏈路中的大多數(shù)關(guān)鍵環(huán)節(jié)。3. Agent 執(zhí)行流程整體拆解3.1 一次 Agent 調(diào)用的完整鏈路在沒有理解執(zhí)行流程之前看 Agent 的代碼會覺得很“玄學(xué)”明明只是調(diào)了一個agent_executor.invoke({input: ...})為什么模型自己就知道該用哪個工具實際上一次完整的 Agent 調(diào)用在框架內(nèi)部經(jīng)歷了這樣的過程用戶輸入 ↓ Prompt 組裝System Prompt 用戶輸入 歷史記憶 工具描述 ↓ 調(diào)用 LLM 進(jìn)行推理 ↓ LLM 返回 Action決策 ↓ 判斷是否有工具調(diào)用 ├── 沒有工具調(diào)用 - 直接生成最終回答 - 結(jié)束 └── 有工具調(diào)用 ↓ 執(zhí)行對應(yīng) Tool ↓ 獲得 Observation觀察結(jié)果 ↓ 將 Observation 拼接到 Prompt再次調(diào)用 LLM ↓ 重復(fù)以上過程直到模型生成最終回答或達(dá)到最大迭代次數(shù)這個循環(huán)就是 Agent 執(zhí)行流程的核心學(xué)術(shù)上通常稱為ReAct 范式Reasoning推理 Acting行動。3.2 核心組件分工在 LangChain 6-9 版本的 Agent 架構(gòu)中參與執(zhí)行流程的組件有五個它們各司其職Agent 決策器Agent負(fù)責(zé)生成“下一步行動”的決策。它本質(zhì)上是一個綁定了一堆工具描述的大模型。工具ToolsAgent 可以調(diào)用的外部能力集合比如查天氣、執(zhí)行代碼、搜索網(wǎng)頁、操作數(shù)據(jù)庫。執(zhí)行器AgentExecutor負(fù)責(zé)編排整個循環(huán)。它把 Agent 的決策翻譯成實際動作把工具返回的結(jié)果再喂給 Agent循環(huán)往復(fù)。記憶Memory保存 Agent 執(zhí)行過程中的關(guān)鍵上下文避免模型“失憶”。輸出解析器OutputParser把模型輸出的原始文本解析成結(jié)構(gòu)化的AgentAction或AgentFinish。這一步非常關(guān)鍵因為大模型輸出可能是文本、JSON甚至夾雜著多余的描述。我們用一個表格來總結(jié)組件作用執(zhí)行流程中的位置Agent決策下一步行動每個循環(huán)的第一步Tools提供外部執(zhí)行能力Agent 決定調(diào)用時觸發(fā)AgentExecutor控制循環(huán)流程整個流程的調(diào)度者M(jìn)emory保存中間狀態(tài)和上下文每次調(diào)用前讀取調(diào)用后更新OutputParser解析模型輸出Agent 輸出之后工具調(diào)用之前3.3 工具調(diào)用協(xié)議LangChain 6-9 版本中Agent 的工具調(diào)用主要基于大模型的 Function Calling / Tool Calling 能力。這意味著模型在推理過程中會輸出一個結(jié)構(gòu)化的“函數(shù)調(diào)用請求”而不是普通的自然語言。這個請求通常包含name工具名稱arguments參數(shù)字典Agent 執(zhí)行器拿到這個請求后會去工具注冊表中找到對應(yīng)名稱的工具然后以arguments為參數(shù)執(zhí)行工具函數(shù)。這個設(shè)計最大的價值在于工具調(diào)用的決策和工具的執(zhí)行被徹底分離了。模型只負(fù)責(zé)“決定”不負(fù)責(zé)“實現(xiàn)”。這樣即使底層工具換了實現(xiàn)方式只要保持名稱和參數(shù)結(jié)構(gòu)一致Agent 的決策邏輯完全不需要改。4. 從零實現(xiàn)一個 Agent完整實戰(zhàn)4.1 創(chuàng)建項目結(jié)構(gòu)首先創(chuàng)建項目目錄mkdir langchain-agent-demo cd langchain-agent-demo然后按前面提到的結(jié)構(gòu)創(chuàng)建好tools包。4.2 定義工具工具是 Agent 執(zhí)行流程中真正“干活”的部分。我們先實現(xiàn)兩個工具天氣查詢和加法計算。文件路徑tools/weather_tools.pyimport random from datetime import datetime from langchain_core.tools import tool tool def get_weather(city: str) - str: 查詢指定城市的實時天氣信息。 參數(shù) city: 城市名稱例如 北京、上海 返回 包含溫度、天氣狀況、風(fēng)力等級等信息的字符串 # 這里使用模擬數(shù)據(jù)實際項目中可以替換為真實天氣 API 調(diào)用 temperature random.randint(-5, 35) conditions [晴, 多云, 陰, 小雨, 中雨, 大雨, 雪] weather random.choice(conditions) return ( f{city}當(dāng)前天氣{weather}溫度 {temperature}℃ f風(fēng)力 3-4 級。時間為 {datetime.now().strftime(%Y-%m-%d %H:%M)}。 ) tool def add_numbers(a: int, b: int) - int: 計算兩個整數(shù)的和。 參數(shù) a: 第一個整數(shù) b: 第二個整數(shù) 返回 兩個整數(shù)的和 return a b幾點說明tool裝飾器是 LangChain 推薦的工具定義方式。它可以把一個普通的 Python 函數(shù)包裝成 LangChain 認(rèn)識的 Tool 對象。函數(shù)名和 docstring 非常重要。在 Agent 執(zhí)行流程中函數(shù)名會被當(dāng)作工具的名稱docstring 中關(guān)于參數(shù)和返回值的描述會被發(fā)給模型作為模型決策是否調(diào)用該工具的依據(jù)。參數(shù)類型標(biāo)注也很關(guān)鍵。LangChain 會根據(jù)類型標(biāo)注生成工具的參數(shù) Schema模型在生成 Function Calling 請求時會嚴(yán)格按照這個 Schema 來生成 JSON 參數(shù)。4.3 創(chuàng)建 Agent 執(zhí)行器在項目根目錄創(chuàng)建main.py先看整體代碼再逐行解釋。文件路徑main.pyimport os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_react_agent from langchain.prompts import PromptTemplate from langchain_core.tools import Tool from tools.weather_tools import get_weather, add_numbers # 加載環(huán)境變量 load_dotenv() # 初始化 LLM llm ChatOpenAI( modelos.getenv(MODEL_NAME, gpt-4o-mini), api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_API_BASE), temperature0, ) # 將 tool 裝飾的函數(shù)包裝成 Agent 可用的工具列表 tools [ Tool( nameget_weather, funcget_weather.func, # 注意這里需要傳入原始函數(shù) description查詢指定城市的實時天氣信息參數(shù)為城市名稱例如北京, ), Tool( nameadd_numbers, funcadd_numbers.func, description計算兩個整數(shù)的和參數(shù)為兩個整數(shù) a 和 b, ), ] # 構(gòu)建 ReAct Agent 的 Prompt prompt PromptTemplate.from_template( 你是是一個智能助手可以調(diào)用工具來完成任務(wù)。 你可以使用以下工具 {tools} 工具名稱列表 {tool_names} 回答時請使用以下格式 問題需要回答的輸入問題 思考你應(yīng)當(dāng)思考如何回答這個問題 行動你應(yīng)當(dāng)采取的動作名稱必須是 [{tool_names}] 之一 行動輸入行動需要的輸入?yún)?shù)必須是一個 JSON 對象 觀察工具返回的結(jié)果 ... (這個思考/行動/行動輸入/觀察可以重復(fù) N 次) 思考我已經(jīng)拿到足夠的信息 最終答案對原始問題的最終回復(fù) 開始 問題{input} 思考{agent_scratchpad} ) # 創(chuàng)建 Agent agent create_react_agent( llmllm, toolstools, promptprompt, ) # 創(chuàng)建執(zhí)行器 agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations5, handle_parsing_errorsTrue, ) # 執(zhí)行測試 if __name__ __main__: result agent_executor.invoke( {input: 上海今天天氣怎么樣順便幫我算一下 123 456 等于多少} ) print(最終回答, result[output])4.4 代碼關(guān)鍵點解析這段代碼是 Agent 執(zhí)行流程的入口其中有幾個點需要重點理解。第一create_react_agent的作用。它負(fù)責(zé)把 LLM、工具列表、Prompt 組裝成一個真正意義上的 Agent 決策器。這里的 ReAct 是 Agent 的一種實現(xiàn)范式核心思想就是讓模型“先思考再行動再觀察”循環(huán)下去這個 Agent 在執(zhí)行流程中扮演“大腦”的角色。第二Prompt 中的{agent_scratchpad}。這是理解 Agent 執(zhí)行流程的關(guān)鍵變量。agent_scratchpad是 Agent 的“草稿紙”它會記錄前面所有“思考 - 行動 - 觀察”的過程。在循環(huán)中每次工具返回結(jié)果后框架會把結(jié)果追加到agent_scratchpad然后重新傳給模型讓模型基于完整的執(zhí)行歷史做下一步?jīng)Q策。簡單來說agent_scratchpad就是 Agent 的記憶載體。第三AgentExecutor的參數(shù)。verboseTrue會打印每次循環(huán)中模型的思考過程和工具執(zhí)行情況是調(diào)試 Agent 最有力的工具。max_iterations5限制最大循環(huán)次數(shù)防止 Agent 陷入死循環(huán)。handle_parsing_errorsTrue會在模型輸出無法解析時自動嘗試修復(fù)而不是直接崩潰。4.5 運行與驗證執(zhí)行以下命令運行程序python main.py預(yù)期輸出會大致分為兩部分Agent 執(zhí)行過程中的循環(huán)日志以及最終的回答。由于verboseTrue你會看到類似這樣的輸出 Entering new AgentExecutor chain... 思考我需要查詢上海的天氣同時計算兩個數(shù)字的和。先查天氣再算數(shù)。 行動get_weather 行動輸入{city: 上海} 觀察上海當(dāng)前天氣晴溫度 18℃風(fēng)力 3-4 級。時間為 2025-01-10 14:30。 思考天氣信息已經(jīng)拿到接下來計算 123 456。 行動add_numbers 行動輸入{a: 123, b: 456} 觀察579 思考兩個結(jié)果都已經(jīng)拿到我可以在最終答案中一起回復(fù)用戶。 最終答案上海當(dāng)前天氣晴溫度 18℃風(fēng)力 3-4 級。另外123 456 579。 Finished chain.觀察這個輸出你會發(fā)現(xiàn)一個完整的 Agent 執(zhí)行流程被分成了兩個“思考 - 行動 - 觀察”循環(huán)正好對應(yīng)兩次工具調(diào)用。這就是 Agent 與普通 LLM 調(diào)用的最大區(qū)別它不是一次性生成回答而是經(jīng)過多輪“推理 行動”后才形成最終答案。4.6 多種 Agent 范式說明ReAct Agent 是 LangChain 中最經(jīng)典、也最容易理解的 Agent 范式適合新手入門。但在 LangChain 6-9 版本中Agent 范式并不只有這一種。常見的還有OpenAI Tools Agent專門針對 OpenAI Function Calling 能力優(yōu)化的范式結(jié)構(gòu)化輸出更穩(wěn)定適合生產(chǎn)環(huán)境。Plan-and-Execute Agent先讓模型制定一個整體計劃再逐步執(zhí)行。適合任務(wù)步驟較多、依賴關(guān)系明確的場景。Self-Ask Agent通過不斷問自己子問題來完成任務(wù)適合需要多跳推理的問答場景。不同的 Agent 范式底層執(zhí)行流程略有差異但宏觀的“推理 - 行動 - 觀察”循環(huán)是不變的。實際項目中你可以根據(jù)任務(wù)的復(fù)雜度和模型的 Function Calling 能力來選擇。記住LangChain 的 Agent 設(shè)計允許你切換不同范式而不需要重寫業(yè)務(wù)代碼。這也是 LangChain 的核心價值之一。5. Agent 執(zhí)行流程中的記憶機制5.1 為什么 Agent 需要記憶前面我們提到agent_scratchpad是 Agent 在單次任務(wù)中的短期記憶。但在真實業(yè)務(wù)中用戶可能會和 Agent 進(jìn)行多輪對話比如用戶先問“上海天氣怎么樣”Agent 回復(fù)后用戶又問“那北京呢”此時 Agent 需要知道“那北京呢”指的是“北京的天氣怎么樣”這就是跨輪對話的記憶能力。在 Agent 執(zhí)行流程中Memorize 和agent_scratchpad是兩種不同維度的記憶agent_scratchpad單次任務(wù)內(nèi)的執(zhí)行軌跡記憶。Memory跨任務(wù)、跨對話輪的長期記憶。5.2 如何給 Agent 添加記憶LangChain 中AgentExecutor本身不帶長期記憶能力需要手動傳入memory參數(shù)。最常見的方式是結(jié)合ConversationBufferMemory。示例代碼如下from langchain.memory import ConversationBufferMemory # 創(chuàng)建記憶對象 memory ConversationBufferMemory( memory_keychat_history, return_messagesTrue, ) # 在 AgentExecutor 中傳入 memory agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations5, memorymemory, )同時在 Prompt 模板中增加{chat_history}變量prompt PromptTemplate.from_template( ... 問題{input} 聊天歷史{chat_history} 思考{agent_scratchpad} )這樣Agent 在每一輪決策時都能看到之前的對話歷史就能理解“那北京呢”是在問天氣。5.3 記憶使用的注意事項在實際項目中盲目地給 Agent 加記憶也會帶來問題上下文長度膨脹隨著對話輪次增加記憶內(nèi)容越來越長最終會超過模型的上下文窗口。無效信息干擾不是所有歷史都對當(dāng)前決策有幫助冗余信息可能讓模型的注意力分散。解決辦法通常有兩個方向使用ConversationSummaryBufferMemory對老消息做摘要只保留最近 N 條完整消息引入向量數(shù)據(jù)庫只根據(jù)語義相似度檢索與當(dāng)前問題相關(guān)的歷史片段。在 LangChain 6-9 版本中這兩類方案都有對應(yīng)的實現(xiàn)類可以直接使用關(guān)鍵是你要理解“記憶的本質(zhì)是把 Agent 的歷史上下文轉(zhuǎn)化為有用信息”。6. 常見問題與排查思路在 Agent 開發(fā)中你遇到的很多問題并不會直接報錯而是表現(xiàn)為“Agent 行為不符合預(yù)期”。下面我整理了幾個高頻問題也是 langchain 面試中經(jīng)常被問到的問題。6.1 Agent 陷入死循環(huán)現(xiàn)象Agent 反復(fù)調(diào)用同一個工具結(jié)果都一樣然后又繼續(xù)調(diào)用沒有要結(jié)束的意思。原因模型判斷工具結(jié)果“不夠好”想要再次執(zhí)行。Prompt 中沒有明確告訴模型“工具結(jié)果已經(jīng)拿到應(yīng)該總結(jié)回答”。max_iterations設(shè)置過大。排查步驟打開verboseTrue觀察每次循環(huán)中模型的“思考”內(nèi)容。檢查工具返回的結(jié)果是否有效。如果工具本身返回錯誤或空結(jié)果模型可能無法據(jù)此完成推理。檢查 Prompt 中是否明確給出了停止條件。解決方案適當(dāng)降低max_iterations例如設(shè)置為 3-5。在工具返回的結(jié)果中增加明確的狀態(tài)標(biāo)識如success: true/false。在 Prompt 中加入規(guī)則“如果工具已經(jīng)返回結(jié)果請直接給出最終答案?！?.2 模型不調(diào)用工具直接給答案現(xiàn)象用戶問了一個需要工具才能回答的問題但 Agent 直接憑自己的知識回答了而且可能是錯誤的。原因工具描述不清晰模型沒有意識到需要調(diào)用工具。模型版本太弱Function Calling 能力有限。Prompt 中工具列表的權(quán)重不夠。解決方案重新描述工具明確說明“該工具用于解決哪類問題”。在 Prompt 中強調(diào)“如果需要實時數(shù)據(jù)必須調(diào)用工具”。如果條件允許換用 Function Calling 能力更強的模型。6.3 工具參數(shù)解析失敗現(xiàn)象模型返回了工具調(diào)用意圖但生成的參數(shù)和工具函數(shù)簽名不匹配例如缺少必填參數(shù)、參數(shù)類型錯誤。原因工具函數(shù)的參數(shù)名、類型標(biāo)注與模型從 docstring 中理解的語義有偏差。模型輸出了非法的 JSON 格式。解決方案嚴(yán)格使用類型標(biāo)注并為每個參數(shù)寫清楚說明。在工具函數(shù)中加入?yún)?shù)校驗和異常處理避免拋出無法恢復(fù)的錯誤。開啟handle_parsing_errorsTrue讓 Agent 有機會根據(jù)錯誤信息重新生成。6.4 上下文窗口超限現(xiàn)象在 Agent 執(zhí)行過程中報錯提示context length exceeded。原因agent_scratchpad、記憶和工具結(jié)果共同占用的 token 數(shù)超過了模型的上下文窗口。解決方案減少max_iterations。使用摘要記憶替代完整緩沖記憶。減小工具返回結(jié)果的長度例如只返回關(guān)鍵字段。6.5 常見問題匯總表問題現(xiàn)象常見原因排查思路Agent 死循環(huán)模型未理解停止條件 / 工具結(jié)果無效查看 verbose 日志優(yōu)化 Prompt調(diào)低 max_iterations不調(diào)用工具工具描述不清晰 / 模型能力弱優(yōu)化工具描述更換模型強化 Prompt 指令參數(shù)解析失敗函數(shù)簽名與模型理解不一致 / 非法 JSON完善類型標(biāo)注和 docstring開啟 handle_parsing_errors上下文超限記憶和調(diào)試信息占用太多 token使用摘要記憶限制工具返回結(jié)果長度工具返回錯誤未處理工具內(nèi)部異常直接向上拋出在工具內(nèi)部捕獲異常返回錯誤信息字符串7. Agent 開發(fā)的最佳實踐7.1 工具命名與描述規(guī)范工具的名稱和描述是 Agent 決策的重要依據(jù)。在實際開發(fā)中建議遵循以下原則工具名使用動詞 名詞結(jié)構(gòu)例如query_weather、send_email。描述中明確說明工具用途、參數(shù)格式、返回格式。如果工具可能失敗在描述中說明失敗時的返回結(jié)構(gòu)。一個反例和一個正例反例calculate: 計算 正例calculate_sum: 計算兩個整數(shù)的和參數(shù)為 a 和 b返回整數(shù)結(jié)果7.2 異常處理與容錯設(shè)計工具函數(shù)內(nèi)部應(yīng)該具備完善的異常處理能力。tool def query_database(sql: str) - str: 執(zhí)行 SQL 查詢語句返回查詢結(jié)果。 參數(shù) sql: 合法的 SQL 查詢語句 返回 查詢結(jié)果的 JSON 字符串失敗時返回 error 信息 try: # 實際執(zhí)行 SQL result execute_sql(sql) return json.dumps(result, ensure_asciiFalse) except Exception as e: return json.dumps({error: str(e)}, ensure_asciiFalse)這樣設(shè)計的好處是即使工具執(zhí)行失敗Agent 也能拿到一個結(jié)構(gòu)化的錯誤信息并根據(jù)這個信息決定下一步是重試、換工具還是告訴用戶無法完成。7.3 Prompt 設(shè)計要兼顧約束與自由Agent 的 Prompt 與普通 LLM 應(yīng)用的 Prompt 要求類似但更需要強調(diào)“執(zhí)行規(guī)則”還要給模型足夠的推理空間。在編寫 Agent Prompt 時建議包含以下元素角色定位告訴模型它是什么角色。工具列表說明明確列出所有可用的工具和用途。執(zhí)行格式要求規(guī)定模型的輸出格式思考、行動、行動輸入、觀察、最終答案。結(jié)束條件告訴模型“當(dāng)你拿到足夠信息時應(yīng)該停止循環(huán)并給出最終答案”。邊界說明告訴模型“如果所有工具都無法解決用戶問題應(yīng)該如實告知”。7.4 日志與可追蹤性生產(chǎn)環(huán)境中的 Agent 問題非常隱蔽。為了快速定位問題一定要做到“全鏈路可追蹤”。在 LangChain 6-9 版本中verboseTrue只能用于開發(fā)調(diào)試不適合直接打到生產(chǎn)日志里。更推薦的做法是使用AgentExecutor的callbacks參數(shù)自定義日志回調(diào)。在每次工具調(diào)用時記錄工具名、入?yún)?、出參、耗時。在 LLM 調(diào)用時記錄 prompt 和 response。這樣當(dāng)線上 Agent 出現(xiàn)問題時你可以完整回放它的決策過程而不是面對一個黑盒。7.5 安全與權(quán)限控制Agent 能調(diào)用工具意味著它擁有了“行動能力”。在實際項目中對工具能力必須有嚴(yán)格的權(quán)限邊界。最小權(quán)限原則給 Agent 配置的工具只需要滿足業(yè)務(wù)需求不要暴露無關(guān)能力。敏感操作二次確認(rèn)涉及刪除、修改、發(fā)送消息等敏感操作工具內(nèi)部要增加確認(rèn)機制。輸入校驗工具函數(shù)內(nèi)部必須對模型傳入的參數(shù)做合法性校驗防止惡意構(gòu)造參數(shù)。7.6 性能與成本優(yōu)化Agent 的循環(huán)執(zhí)行機制決定了它比普通 LLM 調(diào)用更耗時、更耗 token。優(yōu)化方向主要有三個減少迭代次數(shù)通過優(yōu)化 Prompt 讓 Agent 更準(zhǔn)確地選擇工具減少無效循環(huán)。控制上下文長度在傳給模型之前對工具結(jié)果和記憶做截斷處理。優(yōu)先使用小模型簡單的工具推理可以使用小尺寸模型只有復(fù)雜推理才調(diào)用大模型。在實際項目中可以結(jié)合 LangChain 的分流機制根據(jù)任務(wù)復(fù)雜度動態(tài)選擇模型這樣能顯著降低成本。8. 總結(jié)與實踐建議本文圍繞 LangChain 6-9 版本中的 Agent 執(zhí)行流程講清楚了五個核心問題Agent 是什么以及它和普通 LLM 調(diào)用的區(qū)別Agent 執(zhí)行流程的完整閉環(huán)“推理 - 行動 - 觀察 - 循環(huán)”Agent 核心組件Agent、Tools、AgentExecutor、Memory、OutputParser的職責(zé)劃分如何從零構(gòu)建一個可運行的 ReAct Agent 并理解它的每一步執(zhí)行細(xì)節(jié)常見問題排查思路和 Agent 開發(fā)工程化相關(guān)的最佳實踐。如果你剛開始接觸 Agent 開發(fā)建議不要急著用 LangGraph 實現(xiàn)復(fù)雜編排先把本文中的 ReAct Agent 跑通打開verboseTrue看一遍完整的執(zhí)行日志再根據(jù)業(yè)務(wù)需要逐步添加記憶、工具和異常處理。只有親手觀察過 Agent 的完整執(zhí)行流程你才能真正理解“模型決策”和“工具執(zhí)行”是如何協(xié)同工作的。接下來你可以繼續(xù)深入了解LangChain 官方文檔中關(guān)于 Agent 不同范式的對比LangGraph 的節(jié)點與狀態(tài)管理機制掌握更底層的編排能力如何設(shè)計一套屬于自己的 Tool 服務(wù)層方便 Agent 接入公司內(nèi)部系統(tǒng)。Agent 開發(fā)的上手門檻并不高但要讓 Agent 在真實項目中穩(wěn)定、可控地執(zhí)行任務(wù)拼的是對執(zhí)行流程細(xì)節(jié)的理解和工程化能力。希望這篇文章能幫你邁過最難的那道坎。有任何執(zhí)行流程相關(guān)的問題歡迎在評論區(qū)交流。 LangChain Agent執(zhí)行流程拆解：從ReAct到工具調(diào)用
先問大家一個問題當(dāng)你在開發(fā)一個完整的 AI Agent 時最頭疼的是什么可能很多人會說“模型能力不夠”“工具不好接入”但真正把一個 Agent 從 Demo 推到可落地狀態(tài)時你會發(fā)現(xiàn)最復(fù)雜的其實是Agent 的執(zhí)行流程模型是怎么決定調(diào)用哪個工具的工具返回結(jié)果之后又要做什么循環(huán)什么時候終止如果中間報錯了整個流程又該怎么恢復(fù)這些問題如果只靠“調(diào) LLM 拼 Prompt”來解決會非常容易失控。LangChain 在 0.6 到 0.9 這個版本區(qū)間對 Agent 模塊做了大量重構(gòu)把很多隱式的執(zhí)行邏輯收斂到了框架內(nèi)部讓開發(fā)者可以把更多精力放在業(yè)務(wù)本身。但框架收斂邏輯并不代表我們不需要理解執(zhí)行流程。恰恰相反只有把執(zhí)行鏈路拆解清楚才能在真正遇到“Agent 不按預(yù)期工作”的時候快速定位問題。本文就把 LangChain 6-9 版本中的 Agent 執(zhí)行流程完整拆開從核心概念、環(huán)境準(zhǔn)備、組件原理到完整實戰(zhàn)和常見排查思路一次性講透。無論你是剛開始接觸 langchain 入門還是在項目中已經(jīng)用到 ai agent 開發(fā)這篇內(nèi)容都能給你一個清晰的框架。1. 背景與核心概念1.1 什么是 Agent在了解 LangChain 的 Agent 執(zhí)行流程之前我們需要先明確一件事Agent 到底是什么它和我們平時調(diào)大模型接口有什么區(qū)別。如果只是調(diào)用大模型流程非常簡單你給模型一個 Prompt模型返回一個回答。這個回答可能是文本、JSON、代碼片段但本質(zhì)上模型只是在“生成內(nèi)容”。而 Agent 是一個擁有“決策能力”的智能體。它不只是回答問題而是可以為了完成目標(biāo)自主選擇調(diào)用什么工具、按什么順序執(zhí)行、如何利用工具返回的信息繼續(xù)下一步。舉個例子用戶問“上海今天適合穿什么衣服”。普通模型只能根據(jù)它的訓(xùn)練知識給出模糊建議。但一個有工具的 Agent可以調(diào)用天氣插件查詢上海實時天氣拿到溫度、濕度、風(fēng)力數(shù)據(jù)再決定告訴用戶穿什么衣服。這個過程中Agent 是“主動”的它在不斷決定“下一步做什么”。1.2 LangChain Agent 解決什么問題LangChain 提供了一套標(biāo)準(zhǔn)化的 Agent 構(gòu)建框架。在 LangChain 6-9 這個版本區(qū)間框架解決的問題可以歸納為三塊Agent 決策鏈路讓模型根據(jù)用戶輸入和歷史信息推理出下一步應(yīng)該調(diào)用哪個工具。工具調(diào)用與結(jié)果回傳封裝了 Function Calling 和 Tool Calling 的標(biāo)準(zhǔn)流程讓 Agent 可以穩(wěn)定地觸發(fā)工具并拿到結(jié)構(gòu)化結(jié)果。循環(huán)控制Agent 不是跑一次就結(jié)束而是反復(fù)執(zhí)行“推理 - 行動 - 觀察”的循環(huán)直到得到最終答案或達(dá)到最大迭代次數(shù)。這些能力疊加起來就是 Agent 執(zhí)行流程的核心骨架。1.3 Agent 與 LangGraph 的關(guān)系如果你在搜索 langchain agent 相關(guān)內(nèi)容一定會頻繁看到一個叫 LangGraph 的詞。它們并不是替代關(guān)系而是側(cè)重點不同。LangChain 的 Agent 模塊也就是 AgentExecutor提供的是標(biāo)準(zhǔn)化的執(zhí)行流程封裝適合快速搭建 AgentLangGraph 則是一個更底層的編排框架可以讓你用圖的方式手動控制每個節(jié)點的狀態(tài)轉(zhuǎn)換。簡單理解AgentExecutor 自動化的循環(huán)引擎 LangGraph 可自定義的編排引擎在 LangChain 6-9 版本中AgentExecutor 底層也已經(jīng)可以基于 LangGraph 實現(xiàn)但在使用層面AgentExecutor 隱藏了圖的復(fù)雜度對多數(shù)業(yè)務(wù)場景來說已經(jīng)足夠了。如果你要對執(zhí)行流程做非常細(xì)粒度的控制再考慮直接上手 LangGraph。2. 環(huán)境準(zhǔn)備與版本說明2.1 基礎(chǔ)環(huán)境在開始代碼實戰(zhàn)前先把環(huán)境準(zhǔn)備好。本文示例基于 Python 3.10LangChain 版本以 0.6.x 至 0.9.x 區(qū)間為主。由于該區(qū)間內(nèi)部分 API 仍在迭代實際使用時請以你自己的環(huán)境中安裝的版本為準(zhǔn)。# 建議使用虛擬環(huán)境 python -m venv langchain-agent-demo source langchain-agent-demo/bin/activate # 安裝 LangChain 本體 pip install langchain # 安裝 LangChain 官方社區(qū)包 pip install langchain-community # 安裝 OpenAI 集成包本文示例使用 OpenAI 兼容接口 pip install langchain-openai # 安裝用于加載環(huán)境變量的庫 pip install python-dotenv如果你使用的是國內(nèi)可訪問的大模型服務(wù)比如 DeepSeek、通義千問、Kimi、智譜等只要它兼容 OpenAI 的接口格式也可以通過langchain-openai或自定義ChatOpenAI的base_url來接入。本文示例會預(yù)留這部分配置說明。2.2 環(huán)境變量配置在項目根目錄創(chuàng)建.env文件內(nèi)容如下# 你的模型 API Key OPENAI_API_KEYyour-api-key-here # 如果你使用的是兼容 OpenAI 接口的服務(wù)可以指定 base_url OPENAI_API_BASEhttps://api.example.com/v1 # 實際項目中推薦使用的模型名稱 MODEL_NAMEgpt-4o-mini注意OPENAI_API_BASE是可選的。如果使用 OpenAI 官方服務(wù)不需要配置這一項。加載方式import os from dotenv import load_dotenv load_dotenv() api_key os.getenv(OPENAI_API_KEY) base_url os.getenv(OPENAI_API_BASE) model_name os.getenv(MODEL_NAME, gpt-4o-mini)2.3 項目結(jié)構(gòu)本文示例項目結(jié)構(gòu)如下langchain-agent-demo/ ├── .env ├── main.py └── tools/ ├── __init__.py └── weather_tools.py我們通過一個“天氣查詢 計算器”的 Agent 案例完整演示 Agent 執(zhí)行流程。這個案例雖然業(yè)務(wù)簡單但能覆蓋 Agent 執(zhí)行鏈路中的大多數(shù)關(guān)鍵環(huán)節(jié)。3. Agent 執(zhí)行流程整體拆解3.1 一次 Agent 調(diào)用的完整鏈路在沒有理解執(zhí)行流程之前看 Agent 的代碼會覺得很“玄學(xué)”明明只是調(diào)了一個agent_executor.invoke({input: ...})為什么模型自己就知道該用哪個工具實際上一次完整的 Agent 調(diào)用在框架內(nèi)部經(jīng)歷了這樣的過程用戶輸入 ↓ Prompt 組裝System Prompt 用戶輸入 歷史記憶 工具描述 ↓ 調(diào)用 LLM 進(jìn)行推理 ↓ LLM 返回 Action決策 ↓ 判斷是否有工具調(diào)用 ├── 沒有工具調(diào)用 - 直接生成最終回答 - 結(jié)束 └── 有工具調(diào)用 ↓ 執(zhí)行對應(yīng) Tool ↓ 獲得 Observation觀察結(jié)果 ↓ 將 Observation 拼接到 Prompt再次調(diào)用 LLM ↓ 重復(fù)以上過程直到模型生成最終回答或達(dá)到最大迭代次數(shù)這個循環(huán)就是 Agent 執(zhí)行流程的核心學(xué)術(shù)上通常稱為ReAct 范式Reasoning推理 Acting行動。3.2 核心組件分工在 LangChain 6-9 版本的 Agent 架構(gòu)中參與執(zhí)行流程的組件有五個它們各司其職Agent 決策器Agent負(fù)責(zé)生成“下一步行動”的決策。它本質(zhì)上是一個綁定了一堆工具描述的大模型。工具ToolsAgent 可以調(diào)用的外部能力集合比如查天氣、執(zhí)行代碼、搜索網(wǎng)頁、操作數(shù)據(jù)庫。執(zhí)行器AgentExecutor負(fù)責(zé)編排整個循環(huán)。它把 Agent 的決策翻譯成實際動作把工具返回的結(jié)果再喂給 Agent循環(huán)往復(fù)。記憶Memory保存 Agent 執(zhí)行過程中的關(guān)鍵上下文避免模型“失憶”。輸出解析器OutputParser把模型輸出的原始文本解析成結(jié)構(gòu)化的AgentAction或AgentFinish。這一步非常關(guān)鍵因為大模型輸出可能是文本、JSON甚至夾雜著多余的描述。我們用一個表格來總結(jié)組件作用執(zhí)行流程中的位置Agent決策下一步行動每個循環(huán)的第一步Tools提供外部執(zhí)行能力Agent 決定調(diào)用時觸發(fā)AgentExecutor控制循環(huán)流程整個流程的調(diào)度者M(jìn)emory保存中間狀態(tài)和上下文每次調(diào)用前讀取調(diào)用后更新OutputParser解析模型輸出Agent 輸出之后工具調(diào)用之前3.3 工具調(diào)用協(xié)議LangChain 6-9 版本中Agent 的工具調(diào)用主要基于大模型的 Function Calling / Tool Calling 能力。這意味著模型在推理過程中會輸出一個結(jié)構(gòu)化的“函數(shù)調(diào)用請求”而不是普通的自然語言。這個請求通常包含name工具名稱arguments參數(shù)字典Agent 執(zhí)行器拿到這個請求后會去工具注冊表中找到對應(yīng)名稱的工具然后以arguments為參數(shù)執(zhí)行工具函數(shù)。這個設(shè)計最大的價值在于工具調(diào)用的決策和工具的執(zhí)行被徹底分離了。模型只負(fù)責(zé)“決定”不負(fù)責(zé)“實現(xiàn)”。這樣即使底層工具換了實現(xiàn)方式只要保持名稱和參數(shù)結(jié)構(gòu)一致Agent 的決策邏輯完全不需要改。4. 從零實現(xiàn)一個 Agent完整實戰(zhàn)4.1 創(chuàng)建項目結(jié)構(gòu)首先創(chuàng)建項目目錄mkdir langchain-agent-demo cd langchain-agent-demo然后按前面提到的結(jié)構(gòu)創(chuàng)建好tools包。4.2 定義工具工具是 Agent 執(zhí)行流程中真正“干活”的部分。我們先實現(xiàn)兩個工具天氣查詢和加法計算。文件路徑tools/weather_tools.pyimport random from datetime import datetime from langchain_core.tools import tool tool def get_weather(city: str) - str: 查詢指定城市的實時天氣信息。 參數(shù) city: 城市名稱例如 北京、上海 返回 包含溫度、天氣狀況、風(fēng)力等級等信息的字符串 # 這里使用模擬數(shù)據(jù)實際項目中可以替換為真實天氣 API 調(diào)用 temperature random.randint(-5, 35) conditions [晴, 多云, 陰, 小雨, 中雨, 大雨, 雪] weather random.choice(conditions) return ( f{city}當(dāng)前天氣{weather}溫度 {temperature}℃ f風(fēng)力 3-4 級。時間為 {datetime.now().strftime(%Y-%m-%d %H:%M)}。 ) tool def add_numbers(a: int, b: int) - int: 計算兩個整數(shù)的和。 參數(shù) a: 第一個整數(shù) b: 第二個整數(shù) 返回 兩個整數(shù)的和 return a b幾點說明tool裝飾器是 LangChain 推薦的工具定義方式。它可以把一個普通的 Python 函數(shù)包裝成 LangChain 認(rèn)識的 Tool 對象。函數(shù)名和 docstring 非常重要。在 Agent 執(zhí)行流程中函數(shù)名會被當(dāng)作工具的名稱docstring 中關(guān)于參數(shù)和返回值的描述會被發(fā)給模型作為模型決策是否調(diào)用該工具的依據(jù)。參數(shù)類型標(biāo)注也很關(guān)鍵。LangChain 會根據(jù)類型標(biāo)注生成工具的參數(shù) Schema模型在生成 Function Calling 請求時會嚴(yán)格按照這個 Schema 來生成 JSON 參數(shù)。4.3 創(chuàng)建 Agent 執(zhí)行器在項目根目錄創(chuàng)建main.py先看整體代碼再逐行解釋。文件路徑main.pyimport os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_react_agent from langchain.prompts import PromptTemplate from langchain_core.tools import Tool from tools.weather_tools import get_weather, add_numbers # 加載環(huán)境變量 load_dotenv() # 初始化 LLM llm ChatOpenAI( modelos.getenv(MODEL_NAME, gpt-4o-mini), api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_API_BASE), temperature0, ) # 將 tool 裝飾的函數(shù)包裝成 Agent 可用的工具列表 tools [ Tool( nameget_weather, funcget_weather.func, # 注意這里需要傳入原始函數(shù) description查詢指定城市的實時天氣信息參數(shù)為城市名稱例如北京, ), Tool( nameadd_numbers, funcadd_numbers.func, description計算兩個整數(shù)的和參數(shù)為兩個整數(shù) a 和 b, ), ] # 構(gòu)建 ReAct Agent 的 Prompt prompt PromptTemplate.from_template( 你是是一個智能助手可以調(diào)用工具來完成任務(wù)。 你可以使用以下工具 {tools} 工具名稱列表 {tool_names} 回答時請使用以下格式 問題需要回答的輸入問題 思考你應(yīng)當(dāng)思考如何回答這個問題 行動你應(yīng)當(dāng)采取的動作名稱必須是 [{tool_names}] 之一 行動輸入行動需要的輸入?yún)?shù)必須是一個 JSON 對象 觀察工具返回的結(jié)果 ... (這個思考/行動/行動輸入/觀察可以重復(fù) N 次) 思考我已經(jīng)拿到足夠的信息 最終答案對原始問題的最終回復(fù) 開始 問題{input} 思考{agent_scratchpad} ) # 創(chuàng)建 Agent agent create_react_agent( llmllm, toolstools, promptprompt, ) # 創(chuàng)建執(zhí)行器 agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations5, handle_parsing_errorsTrue, ) # 執(zhí)行測試 if __name__ __main__: result agent_executor.invoke( {input: 上海今天天氣怎么樣順便幫我算一下 123 456 等于多少} ) print(最終回答, result[output])4.4 代碼關(guān)鍵點解析這段代碼是 Agent 執(zhí)行流程的入口其中有幾個點需要重點理解。第一create_react_agent的作用。它負(fù)責(zé)把 LLM、工具列表、Prompt 組裝成一個真正意義上的 Agent 決策器。這里的 ReAct 是 Agent 的一種實現(xiàn)范式核心思想就是讓模型“先思考再行動再觀察”循環(huán)下去這個 Agent 在執(zhí)行流程中扮演“大腦”的角色。第二Prompt 中的{agent_scratchpad}。這是理解 Agent 執(zhí)行流程的關(guān)鍵變量。agent_scratchpad是 Agent 的“草稿紙”它會記錄前面所有“思考 - 行動 - 觀察”的過程。在循環(huán)中每次工具返回結(jié)果后框架會把結(jié)果追加到agent_scratchpad然后重新傳給模型讓模型基于完整的執(zhí)行歷史做下一步?jīng)Q策。簡單來說agent_scratchpad就是 Agent 的記憶載體。第三AgentExecutor的參數(shù)。verboseTrue會打印每次循環(huán)中模型的思考過程和工具執(zhí)行情況是調(diào)試 Agent 最有力的工具。max_iterations5限制最大循環(huán)次數(shù)防止 Agent 陷入死循環(huán)。handle_parsing_errorsTrue會在模型輸出無法解析時自動嘗試修復(fù)而不是直接崩潰。4.5 運行與驗證執(zhí)行以下命令運行程序python main.py預(yù)期輸出會大致分為兩部分Agent 執(zhí)行過程中的循環(huán)日志以及最終的回答。由于verboseTrue你會看到類似這樣的輸出 Entering new AgentExecutor chain... 思考我需要查詢上海的天氣同時計算兩個數(shù)字的和。先查天氣再算數(shù)。 行動get_weather 行動輸入{city: 上海} 觀察上海當(dāng)前天氣晴溫度 18℃風(fēng)力 3-4 級。時間為 2025-01-10 14:30。 思考天氣信息已經(jīng)拿到接下來計算 123 456。 行動add_numbers 行動輸入{a: 123, b: 456} 觀察579 思考兩個結(jié)果都已經(jīng)拿到我可以在最終答案中一起回復(fù)用戶。 最終答案上海當(dāng)前天氣晴溫度 18℃風(fēng)力 3-4 級。另外123 456 579。 Finished chain.觀察這個輸出你會發(fā)現(xiàn)一個完整的 Agent 執(zhí)行流程被分成了兩個“思考 - 行動 - 觀察”循環(huán)正好對應(yīng)兩次工具調(diào)用。這就是 Agent 與普通 LLM 調(diào)用的最大區(qū)別它不是一次性生成回答而是經(jīng)過多輪“推理 行動”后才形成最終答案。4.6 多種 Agent 范式說明ReAct Agent 是 LangChain 中最經(jīng)典、也最容易理解的 Agent 范式適合新手入門。但在 LangChain 6-9 版本中Agent 范式并不只有這一種。常見的還有OpenAI Tools Agent專門針對 OpenAI Function Calling 能力優(yōu)化的范式結(jié)構(gòu)化輸出更穩(wěn)定適合生產(chǎn)環(huán)境。Plan-and-Execute Agent先讓模型制定一個整體計劃再逐步執(zhí)行。適合任務(wù)步驟較多、依賴關(guān)系明確的場景。Self-Ask Agent通過不斷問自己子問題來完成任務(wù)適合需要多跳推理的問答場景。不同的 Agent 范式底層執(zhí)行流程略有差異但宏觀的“推理 - 行動 - 觀察”循環(huán)是不變的。實際項目中你可以根據(jù)任務(wù)的復(fù)雜度和模型的 Function Calling 能力來選擇。記住LangChain 的 Agent 設(shè)計允許你切換不同范式而不需要重寫業(yè)務(wù)代碼。這也是 LangChain 的核心價值之一。5. Agent 執(zhí)行流程中的記憶機制5.1 為什么 Agent 需要記憶前面我們提到agent_scratchpad是 Agent 在單次任務(wù)中的短期記憶。但在真實業(yè)務(wù)中用戶可能會和 Agent 進(jìn)行多輪對話比如用戶先問“上海天氣怎么樣”Agent 回復(fù)后用戶又問“那北京呢”此時 Agent 需要知道“那北京呢”指的是“北京的天氣怎么樣”這就是跨輪對話的記憶能力。在 Agent 執(zhí)行流程中Memorize 和agent_scratchpad是兩種不同維度的記憶agent_scratchpad單次任務(wù)內(nèi)的執(zhí)行軌跡記憶。Memory跨任務(wù)、跨對話輪的長期記憶。5.2 如何給 Agent 添加記憶LangChain 中AgentExecutor本身不帶長期記憶能力需要手動傳入memory參數(shù)。最常見的方式是結(jié)合ConversationBufferMemory。示例代碼如下from langchain.memory import ConversationBufferMemory # 創(chuàng)建記憶對象 memory ConversationBufferMemory( memory_keychat_history, return_messagesTrue, ) # 在 AgentExecutor 中傳入 memory agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, max_iterations5, memorymemory, )同時在 Prompt 模板中增加{chat_history}變量prompt PromptTemplate.from_template( ... 問題{input} 聊天歷史{chat_history} 思考{agent_scratchpad} )這樣Agent 在每一輪決策時都能看到之前的對話歷史就能理解“那北京呢”是在問天氣。5.3 記憶使用的注意事項在實際項目中盲目地給 Agent 加記憶也會帶來問題上下文長度膨脹隨著對話輪次增加記憶內(nèi)容越來越長最終會超過模型的上下文窗口。無效信息干擾不是所有歷史都對當(dāng)前決策有幫助冗余信息可能讓模型的注意力分散。解決辦法通常有兩個方向使用ConversationSummaryBufferMemory對老消息做摘要只保留最近 N 條完整消息引入向量數(shù)據(jù)庫只根據(jù)語義相似度檢索與當(dāng)前問題相關(guān)的歷史片段。在 LangChain 6-9 版本中這兩類方案都有對應(yīng)的實現(xiàn)類可以直接使用關(guān)鍵是你要理解“記憶的本質(zhì)是把 Agent 的歷史上下文轉(zhuǎn)化為有用信息”。6. 常見問題與排查思路在 Agent 開發(fā)中你遇到的很多問題并不會直接報錯而是表現(xiàn)為“Agent 行為不符合預(yù)期”。下面我整理了幾個高頻問題也是 langchain 面試中經(jīng)常被問到的問題。6.1 Agent 陷入死循環(huán)現(xiàn)象Agent 反復(fù)調(diào)用同一個工具結(jié)果都一樣然后又繼續(xù)調(diào)用沒有要結(jié)束的意思。原因模型判斷工具結(jié)果“不夠好”想要再次執(zhí)行。Prompt 中沒有明確告訴模型“工具結(jié)果已經(jīng)拿到應(yīng)該總結(jié)回答”。max_iterations設(shè)置過大。排查步驟打開verboseTrue觀察每次循環(huán)中模型的“思考”內(nèi)容。檢查工具返回的結(jié)果是否有效。如果工具本身返回錯誤或空結(jié)果模型可能無法據(jù)此完成推理。檢查 Prompt 中是否明確給出了停止條件。解決方案適當(dāng)降低max_iterations例如設(shè)置為 3-5。在工具返回的結(jié)果中增加明確的狀態(tài)標(biāo)識如success: true/false。在 Prompt 中加入規(guī)則“如果工具已經(jīng)返回結(jié)果請直接給出最終答案?！?.2 模型不調(diào)用工具直接給答案現(xiàn)象用戶問了一個需要工具才能回答的問題但 Agent 直接憑自己的知識回答了而且可能是錯誤的。原因工具描述不清晰模型沒有意識到需要調(diào)用工具。模型版本太弱Function Calling 能力有限。Prompt 中工具列表的權(quán)重不夠。解決方案重新描述工具明確說明“該工具用于解決哪類問題”。在 Prompt 中強調(diào)“如果需要實時數(shù)據(jù)必須調(diào)用工具”。如果條件允許換用 Function Calling 能力更強的模型。6.3 工具參數(shù)解析失敗現(xiàn)象模型返回了工具調(diào)用意圖但生成的參數(shù)和工具函數(shù)簽名不匹配例如缺少必填參數(shù)、參數(shù)類型錯誤。原因工具函數(shù)的參數(shù)名、類型標(biāo)注與模型從 docstring 中理解的語義有偏差。模型輸出了非法的 JSON 格式。解決方案嚴(yán)格使用類型標(biāo)注并為每個參數(shù)寫清楚說明。在工具函數(shù)中加入?yún)?shù)校驗和異常處理避免拋出無法恢復(fù)的錯誤。開啟handle_parsing_errorsTrue讓 Agent 有機會根據(jù)錯誤信息重新生成。6.4 上下文窗口超限現(xiàn)象在 Agent 執(zhí)行過程中報錯提示context length exceeded。原因agent_scratchpad、記憶和工具結(jié)果共同占用的 token 數(shù)超過了模型的上下文窗口。解決方案減少max_iterations。使用摘要記憶替代完整緩沖記憶。減小工具返回結(jié)果的長度例如只返回關(guān)鍵字段。6.5 常見問題匯總表問題現(xiàn)象常見原因排查思路Agent 死循環(huán)模型未理解停止條件 / 工具結(jié)果無效查看 verbose 日志優(yōu)化 Prompt調(diào)低 max_iterations不調(diào)用工具工具描述不清晰 / 模型能力弱優(yōu)化工具描述更換模型強化 Prompt 指令參數(shù)解析失敗函數(shù)簽名與模型理解不一致 / 非法 JSON完善類型標(biāo)注和 docstring開啟 handle_parsing_errors上下文超限記憶和調(diào)試信息占用太多 token使用摘要記憶限制工具返回結(jié)果長度工具返回錯誤未處理工具內(nèi)部異常直接向上拋出在工具內(nèi)部捕獲異常返回錯誤信息字符串7. Agent 開發(fā)的最佳實踐7.1 工具命名與描述規(guī)范工具的名稱和描述是 Agent 決策的重要依據(jù)。在實際開發(fā)中建議遵循以下原則工具名使用動詞 名詞結(jié)構(gòu)例如query_weather、send_email。描述中明確說明工具用途、參數(shù)格式、返回格式。如果工具可能失敗在描述中說明失敗時的返回結(jié)構(gòu)。一個反例和一個正例反例calculate: 計算 正例calculate_sum: 計算兩個整數(shù)的和參數(shù)為 a 和 b返回整數(shù)結(jié)果7.2 異常處理與容錯設(shè)計工具函數(shù)內(nèi)部應(yīng)該具備完善的異常處理能力。tool def query_database(sql: str) - str: 執(zhí)行 SQL 查詢語句返回查詢結(jié)果。 參數(shù) sql: 合法的 SQL 查詢語句 返回 查詢結(jié)果的 JSON 字符串失敗時返回 error 信息 try: # 實際執(zhí)行 SQL result execute_sql(sql) return json.dumps(result, ensure_asciiFalse) except Exception as e: return json.dumps({error: str(e)}, ensure_asciiFalse)這樣設(shè)計的好處是即使工具執(zhí)行失敗Agent 也能拿到一個結(jié)構(gòu)化的錯誤信息并根據(jù)這個信息決定下一步是重試、換工具還是告訴用戶無法完成。7.3 Prompt 設(shè)計要兼顧約束與自由Agent 的 Prompt 與普通 LLM 應(yīng)用的 Prompt 要求類似但更需要強調(diào)“執(zhí)行規(guī)則”還要給模型足夠的推理空間。在編寫 Agent Prompt 時建議包含以下元素角色定位告訴模型它是什么角色。工具列表說明明確列出所有可用的工具和用途。執(zhí)行格式要求規(guī)定模型的輸出格式思考、行動、行動輸入、觀察、最終答案。結(jié)束條件告訴模型“當(dāng)你拿到足夠信息時應(yīng)該停止循環(huán)并給出最終答案”。邊界說明告訴模型“如果所有工具都無法解決用戶問題應(yīng)該如實告知”。7.4 日志與可追蹤性生產(chǎn)環(huán)境中的 Agent 問題非常隱蔽。為了快速定位問題一定要做到“全鏈路可追蹤”。在 LangChain 6-9 版本中verboseTrue只能用于開發(fā)調(diào)試不適合直接打到生產(chǎn)日志里。更推薦的做法是使用AgentExecutor的callbacks參數(shù)自定義日志回調(diào)。在每次工具調(diào)用時記錄工具名、入?yún)?、出參、耗時。在 LLM 調(diào)用時記錄 prompt 和 response。這樣當(dāng)線上 Agent 出現(xiàn)問題時你可以完整回放它的決策過程而不是面對一個黑盒。7.5 安全與權(quán)限控制Agent 能調(diào)用工具意味著它擁有了“行動能力”。在實際項目中對工具能力必須有嚴(yán)格的權(quán)限邊界。最小權(quán)限原則給 Agent 配置的工具只需要滿足業(yè)務(wù)需求不要暴露無關(guān)能力。敏感操作二次確認(rèn)涉及刪除、修改、發(fā)送消息等敏感操作工具內(nèi)部要增加確認(rèn)機制。輸入校驗工具函數(shù)內(nèi)部必須對模型傳入的參數(shù)做合法性校驗防止惡意構(gòu)造參數(shù)。7.6 性能與成本優(yōu)化Agent 的循環(huán)執(zhí)行機制決定了它比普通 LLM 調(diào)用更耗時、更耗 token。優(yōu)化方向主要有三個減少迭代次數(shù)通過優(yōu)化 Prompt 讓 Agent 更準(zhǔn)確地選擇工具減少無效循環(huán)。控制上下文長度在傳給模型之前對工具結(jié)果和記憶做截斷處理。優(yōu)先使用小模型簡單的工具推理可以使用小尺寸模型只有復(fù)雜推理才調(diào)用大模型。在實際項目中可以結(jié)合 LangChain 的分流機制根據(jù)任務(wù)復(fù)雜度動態(tài)選擇模型這樣能顯著降低成本。8. 總結(jié)與實踐建議本文圍繞 LangChain 6-9 版本中的 Agent 執(zhí)行流程講清楚了五個核心問題Agent 是什么以及它和普通 LLM 調(diào)用的區(qū)別Agent 執(zhí)行流程的完整閉環(huán)“推理 - 行動 - 觀察 - 循環(huán)”Agent 核心組件Agent、Tools、AgentExecutor、Memory、OutputParser的職責(zé)劃分如何從零構(gòu)建一個可運行的 ReAct Agent 并理解它的每一步執(zhí)行細(xì)節(jié)常見問題排查思路和 Agent 開發(fā)工程化相關(guān)的最佳實踐。如果你剛開始接觸 Agent 開發(fā)建議不要急著用 LangGraph 實現(xiàn)復(fù)雜編排先把本文中的 ReAct Agent 跑通打開verboseTrue看一遍完整的執(zhí)行日志再根據(jù)業(yè)務(wù)需要逐步添加記憶、工具和異常處理。只有親手觀察過 Agent 的完整執(zhí)行流程你才能真正理解“模型決策”和“工具執(zhí)行”是如何協(xié)同工作的。接下來你可以繼續(xù)深入了解LangChain 官方文檔中關(guān)于 Agent 不同范式的對比LangGraph 的節(jié)點與狀態(tài)管理機制掌握更底層的編排能力如何設(shè)計一套屬于自己的 Tool 服務(wù)層方便 Agent 接入公司內(nèi)部系統(tǒng)。Agent 開發(fā)的上手門檻并不高但要讓 Agent 在真實項目中穩(wěn)定、可控地執(zhí)行任務(wù)拼的是對執(zhí)行流程細(xì)節(jié)的理解和工程化能力。希望這篇文章能幫你邁過最難的那道坎。有任何執(zhí)行流程相關(guān)的問題歡迎在評論區(qū)交流。