發(fā)入門(mén)：從零手寫(xiě)Agent循環(huán)，別一上來(lái)就啃框架)
1. 先搞清楚AI Agent 到底是個(gè)什么東西1.1 別被術(shù)語(yǔ)嚇到它就是個(gè)“會(huì)自己干活的程序”很多人第一次聽(tīng)到 AI Agent 這個(gè)詞腦子里浮現(xiàn)的是科幻電影里那種有自我意識(shí)的機(jī)器人。其實(shí)完全不是那么回事。你把它理解成一個(gè)“能自己判斷下一步該干什么的程序”就行了。傳統(tǒng)的程序是什么樣你寫(xiě)死邏輯第一步調(diào)A接口第二步判斷B條件第三步寫(xiě)C數(shù)據(jù)庫(kù)。每一步都是你提前規(guī)定好的程序自己不會(huì)變通。AI Agent 不一樣的地方在于它中間有一個(gè)“大腦”——通常是大語(yǔ)言模型——會(huì)根據(jù)當(dāng)前的情況自己決定下一步做什么。你給它一個(gè)目標(biāo)它自己拆解步驟、自己選工具、自己判斷有沒(méi)有做完。舉個(gè)例子。你讓傳統(tǒng)程序去“幫我查一下明天北京的天氣然后決定要不要帶傘”你得寫(xiě)調(diào)天氣API、解析返回結(jié)果、判斷降水概率是否大于某個(gè)閾值、輸出結(jié)論。每一步都是硬編碼。而 AI Agent 的做法是你把“查天氣”和“判斷是否帶傘”這兩個(gè)能力以工具的形式給它然后告訴它“幫我看看明天北京要不要帶傘”它自己會(huì)決定先調(diào)天氣工具拿到結(jié)果后自己推理最后告訴你結(jié)論。這就是本質(zhì)區(qū)別傳統(tǒng)程序是“你告訴它怎么做”AI Agent 是“你告訴它做什么”。那為什么現(xiàn)在 AI Agent 突然火起來(lái)了因?yàn)榇笳Z(yǔ)言模型的能力到了一個(gè)新的臨界點(diǎn)。2023年之前語(yǔ)言模型的理解和推理能力還不夠穩(wěn)定你讓它自己規(guī)劃步驟它經(jīng)常跑偏。但現(xiàn)在的主流模型在指令遵循、工具調(diào)用、多步推理這幾個(gè)維度上已經(jīng)相當(dāng)可靠了這才讓 Agent 從論文里的概念變成了能實(shí)際跑起來(lái)的東西。1.2 一個(gè) Agent 的最小構(gòu)成四個(gè)零件不管多復(fù)雜的 Agent 系統(tǒng)拆到最底層核心就四個(gè)部分第一大腦LLM。這是整個(gè) Agent 的決策中心。它負(fù)責(zé)理解用戶意圖、規(guī)劃步驟、選擇工具、判斷結(jié)果是否滿足要求。你可以用 OpenAI 的接口、Claude 的接口、也可以用本地部署的開(kāi)源模型。選哪個(gè)模型直接決定了 Agent 的“智商上限”。第二工具Tools。Agent 不能只靠嘴說(shuō)它得能干活。工具就是它跟外部世界交互的手段。查數(shù)據(jù)庫(kù)是一個(gè)工具發(fā)郵件是一個(gè)工具執(zhí)行一段代碼是一個(gè)工具甚至調(diào)用另一個(gè) Agent 也是一個(gè)工具。工具的定義通常包括名稱(chēng)、描述、參數(shù)列表、執(zhí)行邏輯。描述寫(xiě)得清不清楚直接影響到模型能不能正確選用這個(gè)工具。第三記憶Memory。包括短期記憶和長(zhǎng)期記憶。短期記憶就是當(dāng)前對(duì)話的上下文讓 Agent 知道剛才發(fā)生了什么。長(zhǎng)期記憶通常是外掛一個(gè)向量數(shù)據(jù)庫(kù)讓 Agent 能記住幾天前甚至幾個(gè)月前跟用戶的交互內(nèi)容。沒(méi)有記憶的 Agent 就像金魚(yú)每次對(duì)話都從零開(kāi)始。第四規(guī)劃Planning。這是 Agent 最核心也最難做好的部分。簡(jiǎn)單任務(wù)一步就完了但復(fù)雜任務(wù)需要拆解。比如“幫我策劃一場(chǎng)團(tuán)建活動(dòng)”Agent 得自己拆成確定人數(shù)、選場(chǎng)地、定預(yù)算、安排交通、發(fā)通知。怎么拆、按什么順序拆、拆到什么粒度這些都是規(guī)劃要解決的問(wèn)題。把這四個(gè)零件拼起來(lái)一個(gè)最簡(jiǎn)版的 Agent 循環(huán)就是接收用戶輸入 → LLM 思考該做什么 → 調(diào)用工具 → 拿到結(jié)果 → LLM 再思考 → 再調(diào)工具 → 直到任務(wù)完成 → 輸出最終結(jié)果。1.3 為什么新手容易走彎路一上來(lái)就啃框架的陷阱我見(jiàn)過(guò)太多人聽(tīng)說(shuō) LangChain 火上來(lái)就 pip install langchain然后對(duì)著文檔里那一堆 Chain、Agent、Tool、Memory 的類(lèi)發(fā)呆。折騰了兩天跑通了一個(gè) demo但問(wèn)他“這個(gè) Agent 為什么這么決策”完全答不上來(lái)。問(wèn)題出在哪框架幫你封裝了太多東西導(dǎo)致你看不到底層發(fā)生了什么。LangChain 確實(shí)好用它把工具調(diào)用、提示詞模板、輸出解析這些常見(jiàn)模式都封裝成了現(xiàn)成的類(lèi)。但這也意味著當(dāng) Agent 行為不符合預(yù)期的時(shí)候你根本不知道是提示詞的問(wèn)題、工具描述的問(wèn)題、還是模型本身能力不夠。你面對(duì)的是一個(gè)黑盒而調(diào)試黑盒是最痛苦的。我的建議很明確先用最原始的方式手寫(xiě)一個(gè) Agent 循環(huán)跑通了、理解了再去用框架。手寫(xiě)一個(gè)最簡(jiǎn) Agent 大概只需要 50 行 Python 代碼不依賴任何框架直接調(diào)模型的 API。這個(gè)過(guò)程會(huì)讓你真正理解 Agent 的工作原理之后再用 LangChain 或者 Spring AI 的時(shí)候你就知道框架在幫你做什么出了問(wèn)題也知道去哪里找原因。2. 新手和轉(zhuǎn)行者到底該先學(xué)什么2.1 第一優(yōu)先級(jí)Python 基礎(chǔ)但不用學(xué)到能寫(xiě)爬蟲(chóng)的程度AI Agent 開(kāi)發(fā)目前最主流的語(yǔ)言就是 Python。原因很簡(jiǎn)單幾乎所有大模型的官方 SDK 都是 Python 優(yōu)先LangChain、CrewAI、AutoGen 這些主流框架也都是 Python 寫(xiě)的。你用 Java 也能做Spring AI 就是干這個(gè)的但生態(tài)豐富度確實(shí)差一截。那 Python 要學(xué)到什么程度我的標(biāo)準(zhǔn)是能看懂函數(shù)定義和調(diào)用、會(huì)用列表和字典、知道怎么裝第三方庫(kù)、能寫(xiě) if-else 和 for 循環(huán)、會(huì)處理 JSON 數(shù)據(jù)。就這些足夠了。你不需要會(huì)寫(xiě)裝飾器、不需要理解元類(lèi)、不需要搞懂 GIL。那些東西等你真正遇到性能問(wèn)題或者需要讀框架源碼的時(shí)候再補(bǔ)。一開(kāi)始就抱著《流暢的Python》啃大概率是啃到一半就放棄了。具體來(lái)說(shuō)你需要掌握的知識(shí)點(diǎn)變量和基本數(shù)據(jù)類(lèi)型字符串、數(shù)字、布爾值列表和字典的增刪改查for 循環(huán)和 while 循環(huán)if-elif-else 條件判斷函數(shù)的定義和調(diào)用理解參數(shù)傳遞導(dǎo)入模塊和使用 pip 安裝包讀寫(xiě)文件尤其是 JSON 文件異常處理try-except虛擬環(huán)境的使用venv 或 conda這些內(nèi)容如果每天投入兩小時(shí)零基礎(chǔ)大概兩周就能達(dá)到“夠用”的水平。有編程基礎(chǔ)的人兩三天就能撿起來(lái)。注意不要花時(shí)間去學(xué) Python 的面向?qū)ο缶幊谈呒?jí)特性。Agent 開(kāi)發(fā)中你更多是在寫(xiě)函數(shù)和調(diào) API類(lèi)繼承、多態(tài)這些概念等你需要讀框架源碼的時(shí)候再學(xué)也不遲。2.2 第二優(yōu)先級(jí)理解大模型 API 的基本用法Agent 的大腦是 LLM所以你必須知道怎么跟 LLM 打交道?，F(xiàn)在主流的方式就是通過(guò) API 調(diào)用。不管你是用哪家的模型基本流程都是一樣的注冊(cè)賬號(hào)拿到 API Key安裝對(duì)應(yīng)廠商的 SDK或者直接用 HTTP 請(qǐng)求構(gòu)造請(qǐng)求把提示詞和參數(shù)傳進(jìn)去解析響應(yīng)拿到模型返回的文本以 OpenAI 的接口為例最核心的參數(shù)就幾個(gè)model用哪個(gè)模型比如 gpt-4o、gpt-4o-minimessages對(duì)話歷史是一個(gè)列表每條消息有 role 和 contenttemperature控制隨機(jī)性0 最確定1 最隨機(jī)max_tokens限制返回的最大長(zhǎng)度tools可調(diào)用的工具列表這是 Agent 的關(guān)鍵你需要理解messages的結(jié)構(gòu)。它通常包含三種角色system系統(tǒng)提示詞設(shè)定 Agent 的身份和行為規(guī)則user用戶輸入assistant模型之前的回復(fù)多輪對(duì)話就是把歷史消息都塞進(jìn)messages列表里模型會(huì)根據(jù)整個(gè)上下文來(lái)生成回復(fù)。這個(gè)機(jī)制看起來(lái)簡(jiǎn)單但它是 Agent 記憶功能的基礎(chǔ)。還有一個(gè)關(guān)鍵概念是Function Calling或者叫 Tool Use。這是 Agent 能干活的核心機(jī)制。你可以在請(qǐng)求里定義一組工具模型在回復(fù)的時(shí)候如果覺(jué)得需要調(diào)用某個(gè)工具它不會(huì)直接返回文本而是返回一個(gè)“工具調(diào)用請(qǐng)求”告訴你它想調(diào)哪個(gè)工具、傳什么參數(shù)。你的代碼拿到這個(gè)請(qǐng)求后執(zhí)行對(duì)應(yīng)的函數(shù)把結(jié)果再塞回對(duì)話歷史讓模型繼續(xù)處理。這個(gè)循環(huán)就是 Agent 的核心循環(huán)。手寫(xiě)一遍你就徹底懂了。2.3 第三優(yōu)先級(jí)手寫(xiě)一個(gè)最簡(jiǎn) Agent不依賴任何框架現(xiàn)在到了最關(guān)鍵的一步。我下面給出一段最簡(jiǎn) Agent 的偽代碼邏輯你用任何語(yǔ)言都能實(shí)現(xiàn)# 定義工具 def get_weather(city): # 實(shí)際調(diào)用天氣API return 晴25度 # 工具描述告訴模型這個(gè)工具是干什么的 tools [ { name: get_weather, description: 查詢指定城市的天氣, parameters: { city: 城市名稱(chēng) } } ] # 主循環(huán) messages [ {role: system, content: 你是一個(gè)助手可以查天氣}, {role: user, content: 北京今天天氣怎么樣} ] while True: # 調(diào)模型 response call_llm(messages, tools) # 如果模型返回的是工具調(diào)用 if response.has_tool_call(): tool_name response.tool_name tool_args response.tool_args # 執(zhí)行工具 result execute_tool(tool_name, tool_args) # 把工具結(jié)果塞回對(duì)話 messages.append(response.message) messages.append({ role: tool, content: result }) else: # 模型返回了最終文本 print(response.content) break這段代碼的核心邏輯就是調(diào)模型 → 看它要不要調(diào)工具 → 要就執(zhí)行工具并把結(jié)果喂回去 → 不要就輸出結(jié)果結(jié)束。就這么簡(jiǎn)單。你把這個(gè)邏輯手寫(xiě)一遍用真實(shí)的 API 跑通你就已經(jīng)跨過(guò)了 AI Agent 開(kāi)發(fā)的門(mén)檻。后面再學(xué) LangChain、LangGraph、Spring AI你就是在學(xué)“怎么把這個(gè)循環(huán)寫(xiě)得更優(yōu)雅、更可擴(kuò)展”而不是在學(xué)“Agent 是什么”。2.4 第四優(yōu)先級(jí)再學(xué)框架而且要有選擇地學(xué)等你手寫(xiě)跑通了再來(lái)看框架你的視角就完全不一樣了。你看到 LangChain 的AgentExecutor你會(huì)想“哦這就是把我剛才那個(gè) while 循環(huán)封裝了一下”。你看到Tool類(lèi)你會(huì)想“這就是我剛才那個(gè) tools 列表的面向?qū)ο蟀姹尽薄Ｄ强蚣茉趺催x我的建議是LangChain / LangGraph生態(tài)最全文檔最多社區(qū)最大。LangGraph 是 LangChain 團(tuán)隊(duì)后來(lái)推出的專(zhuān)門(mén)做有狀態(tài)的、多步驟的 Agent 編排。如果你要做復(fù)雜的、有分支和循環(huán)的 Agent 流程LangGraph 比原始的 LangChain Agent 更合適。缺點(diǎn)是抽象層多學(xué)習(xí)曲線陡。CrewAI主打多 Agent 協(xié)作。你可以定義多個(gè)角色比如“研究員”、“寫(xiě)手”、“審核員”讓它們互相配合完成任務(wù)。適合做內(nèi)容生產(chǎn)、數(shù)據(jù)分析這類(lèi)需要多角色協(xié)作的場(chǎng)景。API 設(shè)計(jì)比較直觀上手快。AutoGen微軟出的也是多 Agent 對(duì)話框架。特點(diǎn)是 Agent 之間可以自動(dòng)對(duì)話來(lái)解決問(wèn)題。適合做需要多輪討論和辯論的場(chǎng)景。Spring AIJava 生態(tài)的選擇。如果你本身是 Java 開(kāi)發(fā)者不想轉(zhuǎn) PythonSpring AI 提供了跟 LangChain 類(lèi)似的能力。但說(shuō)實(shí)話目前 Java 生態(tài)在 Agent 開(kāi)發(fā)這塊的成熟度還是不如 Python。Dify低代碼平臺(tái)可視化編排 Agent 流程。適合不寫(xiě)代碼或者代碼能力較弱的產(chǎn)品經(jīng)理、運(yùn)營(yíng)人員快速搭建原型。但靈活性受限復(fù)雜邏輯還是得寫(xiě)代碼。我的建議是先深入學(xué)一個(gè)別貪多。如果你主要做單 Agent 加工具調(diào)用的場(chǎng)景LangChain 就夠了。如果你要做多 Agent 協(xié)作看 CrewAI 或 AutoGen。如果你要精細(xì)控制 Agent 的狀態(tài)流轉(zhuǎn)看 LangGraph。2.5 關(guān)于 MCP它解決的是什么問(wèn)題MCP 最近熱度很高但很多人搞不清楚它到底是什么。我用一句話解釋MCP 是一個(gè)讓 Agent 跟外部工具對(duì)接的標(biāo)準(zhǔn)協(xié)議。在沒(méi)有 MCP 之前你每接一個(gè)工具都要自己寫(xiě)適配代碼。比如你要讓 Agent 能查數(shù)據(jù)庫(kù)你得寫(xiě)一個(gè)函數(shù)定義參數(shù)處理返回結(jié)果。你要讓它能操作文件系統(tǒng)又得寫(xiě)一套。每個(gè)工具的接入方式都不一樣復(fù)用性很差。MCP 的思路是定義一套標(biāo)準(zhǔn)接口工具提供方按照這個(gè)標(biāo)準(zhǔn)來(lái)實(shí)現(xiàn)Agent 這邊也按照這個(gè)標(biāo)準(zhǔn)來(lái)調(diào)用。這樣工具就能即插即用。你可以把它類(lèi)比成 USB 接口——以前每個(gè)設(shè)備都有自己的接口現(xiàn)在統(tǒng)一成 USB插上就能用。MCP 的核心概念包括MCP Server工具提供方暴露一組能力比如讀文件、查數(shù)據(jù)庫(kù)、調(diào) APIMCP ClientAgent 這邊負(fù)責(zé)連接 Server 并調(diào)用能力ResourcesServer 暴露的數(shù)據(jù)資源ToolsServer 暴露的可執(zhí)行操作Prompts預(yù)定義的提示詞模板現(xiàn)在很多工具已經(jīng)開(kāi)始支持 MCP 了比如 Playwright MCP 可以讓 Agent 操作瀏覽器百度地圖 MCP 可以讓 Agent 查地理位置。如果你要做的 Agent 需要跟大量外部工具對(duì)接花點(diǎn)時(shí)間了解 MCP 是值得的。但如果你只是做一個(gè)小 demo手寫(xiě)幾個(gè)工具函數(shù)就夠了不用急著上 MCP。3. 實(shí)操?gòu)牧闶謱?xiě)一個(gè)能查天氣和算數(shù)的 Agent3.1 環(huán)境準(zhǔn)備Python 安裝和虛擬環(huán)境先說(shuō) Python 安裝。Windows 用戶去 python.org 下載安裝包安裝的時(shí)候記得勾選“Add Python to PATH”。Mac 用戶可以用 Homebrew 裝brew install python。Linux 用戶一般系統(tǒng)自帶但版本可能比較老建議用 pyenv 裝一個(gè)新版本。裝完之后驗(yàn)證一下python --version pip --version然后建一個(gè)虛擬環(huán)境這是好習(xí)慣避免不同項(xiàng)目的依賴打架python -m venv agent-env # Windows agent-env\Scripts\activate # Mac/Linux source agent-env/bin/activate虛擬環(huán)境激活后命令行前面會(huì)出現(xiàn)(agent-env)的標(biāo)識(shí)。接下來(lái)裝依賴pip install openai requests如果你用的是其他廠商的模型把openai換成對(duì)應(yīng)的 SDK 就行。3.2 定義工具函數(shù)查天氣和做計(jì)算我們定義兩個(gè)工具一個(gè)查天氣一個(gè)做數(shù)學(xué)計(jì)算。查天氣我們用一個(gè)模擬函數(shù)實(shí)際項(xiàng)目中你可以接真實(shí) API。import json import math def get_weather(city: str) - str: 模擬查天氣實(shí)際項(xiàng)目中替換為真實(shí)API調(diào)用 weather_data { 北京: 晴氣溫25度濕度40%, 上海: 多云氣溫28度濕度65%, 廣州: 雷陣雨氣溫30度濕度80%, } return weather_data.get(city, f未找到{city}的天氣數(shù)據(jù)) def calculate(expression: str) - str: 計(jì)算數(shù)學(xué)表達(dá)式 try: # 只允許基本數(shù)學(xué)運(yùn)算避免安全問(wèn)題 allowed set(0123456789-*/.() ) if not all(c in allowed for c in expression): return 表達(dá)式包含不允許的字符 result eval(expression) return str(result) except Exception as e: return f計(jì)算錯(cuò)誤{str(e)}注意calculate函數(shù)里我做了字符白名單校驗(yàn)。直接用eval是有安全風(fēng)險(xiǎn)的雖然這只是個(gè) demo但養(yǎng)成好習(xí)慣很重要。3.3 構(gòu)造工具描述讓模型知道有什么工具可用工具描述是 Agent 能不能正確選用工具的關(guān)鍵。描述要清晰、準(zhǔn)確、包含參數(shù)說(shuō)明。tools [ { type: function, function: { name: get_weather, description: 查詢指定城市的當(dāng)前天氣情況, parameters: { type: object, properties: { city: { type: string, description: 城市名稱(chēng)例如北京、上海 } }, required: [city] } } }, { type: function, function: { name: calculate, description: 計(jì)算數(shù)學(xué)表達(dá)式支持加減乘除和括號(hào), parameters: { type: object, properties: { expression: { type: string, description: 數(shù)學(xué)表達(dá)式例如(35)*2 } }, required: [expression] } } } ]工具描述有幾個(gè)經(jīng)驗(yàn)第一description 要寫(xiě)清楚這個(gè)工具是干什么的什么時(shí)候該用。比如“查詢指定城市的當(dāng)前天氣情況”就比“查天氣”好。第二參數(shù)的 description 要給出示例。模型看到示例更容易傳對(duì)參數(shù)。第三required 要準(zhǔn)確。必填參數(shù)沒(méi)標(biāo) required模型可能不傳。3.4 主循環(huán)實(shí)現(xiàn)調(diào)模型、執(zhí)行工具、喂回結(jié)果from openai import OpenAI client OpenAI(api_key你的API_KEY) def run_agent(user_input: str): messages [ {role: system, content: 你是一個(gè)助手可以查天氣和做數(shù)學(xué)計(jì)算。需要時(shí)調(diào)用工具。}, {role: user, content: user_input} ] max_iterations 10 # 防止無(wú)限循環(huán) for i in range(max_iterations): response client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolstools, tool_choiceauto ) msg response.choices[0].message # 沒(méi)有工具調(diào)用直接返回文本 if not msg.tool_calls: return msg.content # 有工具調(diào)用把 assistant 消息加入歷史 messages.append(msg) # 逐個(gè)執(zhí)行工具 for tool_call in msg.tool_calls: func_name tool_call.function.name func_args json.loads(tool_call.function.arguments) if func_name get_weather: result get_weather(func_args[city]) elif func_name calculate: result calculate(func_args[expression]) else: result f未知工具{func_name} # 把工具結(jié)果加入歷史 messages.append({ role: tool, tool_call_id: tool_call.id, content: result }) return 達(dá)到最大迭代次數(shù)任務(wù)未完成這段代碼就是 Agent 的核心。max_iterations是必須的防止模型陷入死循環(huán)一直調(diào)工具。tool_call_id也很關(guān)鍵模型靠這個(gè) ID 來(lái)匹配哪個(gè)結(jié)果對(duì)應(yīng)哪個(gè)工具調(diào)用。3.5 跑起來(lái)看看效果# 測(cè)試 print(run_agent(北京今天天氣怎么樣)) print(run_agent(幫我算一下 (15 27) * 3 等于多少)) print(run_agent(上海和廣州的天氣分別怎么樣然后算一下兩個(gè)城市溫度的平均值))第三個(gè)測(cè)試用例比較有意思它需要 Agent 先調(diào)兩次天氣工具拿到結(jié)果后再調(diào)計(jì)算工具。這就是多步推理和工具編排。如果你的 Agent 能正確處理這個(gè) case說(shuō)明基本邏輯沒(méi)問(wèn)題了。實(shí)操心得調(diào)試 Agent 的時(shí)候把每一步的messages打印出來(lái)看。你會(huì)清楚地看到模型什么時(shí)候決定調(diào)工具、傳了什么參數(shù)、拿到結(jié)果后怎么繼續(xù)推理。這個(gè)習(xí)慣能幫你快速定位問(wèn)題。4. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄4.1 模型不調(diào)工具怎么辦這是最常見(jiàn)的問(wèn)題。你明明定義了工具用戶的問(wèn)題也明顯需要工具但模型就是直接返回文本不調(diào)工具。原因通常有三個(gè)第一工具描述不夠清晰。模型不知道這個(gè)工具是干什么的自然就不會(huì)用。解決辦法是把 description 寫(xiě)得更具體明確說(shuō)明“什么時(shí)候應(yīng)該使用這個(gè)工具”。第二系統(tǒng)提示詞沒(méi)有引導(dǎo)。在 system message 里加一句“當(dāng)需要查詢實(shí)時(shí)信息或進(jìn)行計(jì)算時(shí)請(qǐng)調(diào)用相應(yīng)的工具”能顯著提高工具調(diào)用率。第三模型能力不夠。一些小模型或者老模型對(duì) Function Calling 的支持不好。換個(gè)更強(qiáng)的模型試試。還有一個(gè)技巧是設(shè)置tool_choicerequired強(qiáng)制模型必須調(diào)用工具。但這只適合你確定每次都需要調(diào)工具的場(chǎng)景一般還是用auto。4.2 工具參數(shù)傳錯(cuò)怎么排查模型傳錯(cuò)參數(shù)也很常見(jiàn)。比如該傳城市名它傳了個(gè)省份名該傳數(shù)字它傳了個(gè)字符串。排查方法在json.loads(tool_call.function.arguments)之后打印一下參數(shù)看看模型到底傳了什么。如果參數(shù)格式不對(duì)在工具定義的 parameters 里把類(lèi)型和描述寫(xiě)得更嚴(yán)格。比如type: string加上enum: [北京, 上海, 廣州]限定取值范圍。另外在工具函數(shù)內(nèi)部做參數(shù)校驗(yàn)也很重要。不要假設(shè)模型傳的參數(shù)一定是對(duì)的該做的校驗(yàn)都要做。4.3 Agent 陷入死循環(huán)怎么處理死循環(huán)的表現(xiàn)是Agent 反復(fù)調(diào)同一個(gè)工具或者在不同工具之間來(lái)回跳就是不輸出最終結(jié)果。原因通常是工具返回的結(jié)果模型不滿意或者模型不知道下一步該干什么。解決辦法第一設(shè)置最大迭代次數(shù)。我上面代碼里的max_iterations就是干這個(gè)的。第二在工具返回結(jié)果里加入引導(dǎo)信息。比如查不到天氣的時(shí)候返回“未找到該城市數(shù)據(jù)請(qǐng)嘗試其他城市或告知用戶無(wú)法查詢”而不是簡(jiǎn)單返回一個(gè)空字符串。第三在系統(tǒng)提示詞里明確“如果工具無(wú)法提供有效信息請(qǐng)直接告知用戶”。4.4 常見(jiàn)問(wèn)題速查表問(wèn)題現(xiàn)象可能原因排查方法解決方案模型不調(diào)工具描述不清/提示詞沒(méi)引導(dǎo)/模型能力不足檢查工具 description 和 system prompt完善描述、加引導(dǎo)語(yǔ)、換模型參數(shù)傳錯(cuò)參數(shù)定義不明確/模型理解偏差打印實(shí)際傳入?yún)?shù)加 enum 限定、加參數(shù)校驗(yàn)死循環(huán)工具結(jié)果不滿足/無(wú)終止條件打印每輪 messages設(shè)最大迭代、優(yōu)化工具返回值返回結(jié)果不符合預(yù)期提示詞不夠具體檢查 system prompt細(xì)化角色設(shè)定和輸出格式要求API 調(diào)用報(bào)錯(cuò)Key 無(wú)效/額度用完/網(wǎng)絡(luò)問(wèn)題看錯(cuò)誤碼和錯(cuò)誤信息檢查 Key、充值、重試響應(yīng)太慢模型本身慢/工具執(zhí)行慢分別計(jì)時(shí)換更快的模型、優(yōu)化工具邏輯4.5 幾個(gè)我踩過(guò)的坑坑一工具函數(shù)拋異常導(dǎo)致整個(gè) Agent 崩潰。工具函數(shù)一定要用 try-except 包起來(lái)返回錯(cuò)誤信息而不是拋異常。模型拿到錯(cuò)誤信息后通常會(huì)自己調(diào)整策略。坑二對(duì)話歷史太長(zhǎng)導(dǎo)致 token 超限。多輪對(duì)話后messages 列表會(huì)越來(lái)越長(zhǎng)。解決辦法是定期截?cái)鄽v史只保留最近 N 輪或者用摘要的方式壓縮歷史。坑三工具描述里寫(xiě)了太多技術(shù)細(xì)節(jié)。工具描述是給模型看的不是給開(kāi)發(fā)者看的。用自然語(yǔ)言寫(xiě)清楚“這個(gè)工具做什么、什么時(shí)候用、參數(shù)是什么”就夠了不要寫(xiě)實(shí)現(xiàn)細(xì)節(jié)。坑四忽略了 tool_call_id 的匹配。多個(gè)工具調(diào)用時(shí)每個(gè) tool_call 有自己的 id返回結(jié)果時(shí)必須帶上對(duì)應(yīng)的 id。不匹配的話模型會(huì)混亂。5. 學(xué)完基礎(chǔ)之后往哪走5.1 下一步給 Agent 加上記憶你現(xiàn)在寫(xiě)的 Agent 每次對(duì)話都是獨(dú)立的沒(méi)有記憶。用戶說(shuō)“北京天氣怎么樣”Agent 查完告訴你。然后用戶說(shuō)“那上海呢”Agent 不知道“那”指的是天氣因?yàn)樗挥浀蒙弦惠唽?duì)話。加記憶最簡(jiǎn)單的方式就是把歷史消息都保留在 messages 列表里。但這樣 token 消耗會(huì)越來(lái)越大。更好的做法是用向量數(shù)據(jù)庫(kù)做長(zhǎng)期記憶把歷史對(duì)話存進(jìn)向量庫(kù)每次新對(duì)話時(shí)檢索最相關(guān)的幾條歷史記錄塞進(jìn)上下文。LangChain 提供了ConversationBufferMemory、ConversationSummaryMemory等現(xiàn)成的記憶組件但建議你先手寫(xiě)一個(gè)最簡(jiǎn)單的版本理解原理后再用框架的。5.2 再下一步多 Agent 協(xié)作單個(gè) Agent 能做的事情有限。當(dāng)你需要完成一個(gè)復(fù)雜任務(wù)時(shí)可以拆成多個(gè) Agent 各司其職。比如做一個(gè)“市場(chǎng)調(diào)研報(bào)告生成”系統(tǒng)研究員 Agent負(fù)責(zé)搜索和收集信息分析師 Agent負(fù)責(zé)分析數(shù)據(jù)、提煉觀點(diǎn)寫(xiě)手 Agent負(fù)責(zé)撰寫(xiě)報(bào)告審核員 Agent負(fù)責(zé)檢查事實(shí)和邏輯每個(gè) Agent 有自己的系統(tǒng)提示詞和工具集它們之間通過(guò)消息傳遞來(lái)協(xié)作。CrewAI 和 AutoGen 就是專(zhuān)門(mén)做這個(gè)的框架。但我要提醒一句多 Agent 系統(tǒng)的復(fù)雜度是指數(shù)級(jí)上升的。兩個(gè) Agent 協(xié)作還好五個(gè) Agent 協(xié)作的時(shí)候調(diào)試會(huì)變得非常困難。建議先把單 Agent 玩透再考慮多 Agent。5.3 關(guān)于框架學(xué)習(xí)的最終建議回到標(biāo)題那句話別一上來(lái)就啃框架。我見(jiàn)過(guò)太多人LangChain 的文檔翻了一遍各種概念背得滾瓜爛熟但讓他從零寫(xiě)一個(gè) Agent 循環(huán)寫(xiě)不出來(lái)。這就是本末倒置了。正確的學(xué)習(xí)路徑是Python 基礎(chǔ)兩周大模型 API 基本用法三天手寫(xiě)最簡(jiǎn) Agent 循環(huán)一天手寫(xiě)帶記憶和多工具的 Agent三天選一個(gè)框架深入學(xué)習(xí)一周用框架重構(gòu)你之前手寫(xiě)的 Agent兩天這個(gè)路徑走下來(lái)大概一個(gè)月左右你就能獨(dú)立開(kāi)發(fā)一個(gè)可用的 AI Agent 了。比上來(lái)就啃框架快得多也扎實(shí)得多。框架是工具不是知識(shí)。工具會(huì)過(guò)時(shí)LangChain 可能明年就被別的框架取代了但 Agent 的核心原理——LLM 決策、工具調(diào)用、循環(huán)執(zhí)行——這些是不會(huì)變的。把原理吃透換什么框架你都能快速上手。我在實(shí)際帶新人的過(guò)程中發(fā)現(xiàn)那些先手寫(xiě)再學(xué)框架的人遇到問(wèn)題時(shí)的排查能力強(qiáng)很多。因?yàn)樗麄冎赖讓影l(fā)生了什么框架報(bào)錯(cuò)的時(shí)候能判斷是框架的問(wèn)題還是自己代碼的問(wèn)題。而直接學(xué)框架的人遇到報(bào)錯(cuò)往往一臉懵只能去社區(qū)提問(wèn)等回答。最后分享一個(gè)小技巧每次學(xué)一個(gè)新框架的時(shí)候先別急著看它的文檔先自己想“如果讓我設(shè)計(jì)這個(gè)框架我會(huì)怎么設(shè)計(jì)”然后再去看它的 API。這樣你學(xué)起來(lái)會(huì)快很多因?yàn)槟闶窃隍?yàn)證自己的想法而不是被動(dòng)接受信息。 AI Agent開(kāi)發(fā)入門(mén)：從零手寫(xiě)Agent循環(huán)，別一上來(lái)就啃框架
1. 先搞清楚AI Agent 到底是個(gè)什么東西1.1 別被術(shù)語(yǔ)嚇到它就是個(gè)“會(huì)自己干活的程序”很多人第一次聽(tīng)到 AI Agent 這個(gè)詞腦子里浮現(xiàn)的是科幻電影里那種有自我意識(shí)的機(jī)器人。其實(shí)完全不是那么回事。你把它理解成一個(gè)“能自己判斷下一步該干什么的程序”就行了。傳統(tǒng)的程序是什么樣你寫(xiě)死邏輯第一步調(diào)A接口第二步判斷B條件第三步寫(xiě)C數(shù)據(jù)庫(kù)。每一步都是你提前規(guī)定好的程序自己不會(huì)變通。AI Agent 不一樣的地方在于它中間有一個(gè)“大腦”——通常是大語(yǔ)言模型——會(huì)根據(jù)當(dāng)前的情況自己決定下一步做什么。你給它一個(gè)目標(biāo)它自己拆解步驟、自己選工具、自己判斷有沒(méi)有做完。舉個(gè)例子。你讓傳統(tǒng)程序去“幫我查一下明天北京的天氣然后決定要不要帶傘”你得寫(xiě)調(diào)天氣API、解析返回結(jié)果、判斷降水概率是否大于某個(gè)閾值、輸出結(jié)論。每一步都是硬編碼。而 AI Agent 的做法是你把“查天氣”和“判斷是否帶傘”這兩個(gè)能力以工具的形式給它然后告訴它“幫我看看明天北京要不要帶傘”它自己會(huì)決定先調(diào)天氣工具拿到結(jié)果后自己推理最后告訴你結(jié)論。這就是本質(zhì)區(qū)別傳統(tǒng)程序是“你告訴它怎么做”AI Agent 是“你告訴它做什么”。那為什么現(xiàn)在 AI Agent 突然火起來(lái)了因?yàn)榇笳Z(yǔ)言模型的能力到了一個(gè)新的臨界點(diǎn)。2023年之前語(yǔ)言模型的理解和推理能力還不夠穩(wěn)定你讓它自己規(guī)劃步驟它經(jīng)常跑偏。但現(xiàn)在的主流模型在指令遵循、工具調(diào)用、多步推理這幾個(gè)維度上已經(jīng)相當(dāng)可靠了這才讓 Agent 從論文里的概念變成了能實(shí)際跑起來(lái)的東西。1.2 一個(gè) Agent 的最小構(gòu)成四個(gè)零件不管多復(fù)雜的 Agent 系統(tǒng)拆到最底層核心就四個(gè)部分第一大腦LLM。這是整個(gè) Agent 的決策中心。它負(fù)責(zé)理解用戶意圖、規(guī)劃步驟、選擇工具、判斷結(jié)果是否滿足要求。你可以用 OpenAI 的接口、Claude 的接口、也可以用本地部署的開(kāi)源模型。選哪個(gè)模型直接決定了 Agent 的“智商上限”。第二工具Tools。Agent 不能只靠嘴說(shuō)它得能干活。工具就是它跟外部世界交互的手段。查數(shù)據(jù)庫(kù)是一個(gè)工具發(fā)郵件是一個(gè)工具執(zhí)行一段代碼是一個(gè)工具甚至調(diào)用另一個(gè) Agent 也是一個(gè)工具。工具的定義通常包括名稱(chēng)、描述、參數(shù)列表、執(zhí)行邏輯。描述寫(xiě)得清不清楚直接影響到模型能不能正確選用這個(gè)工具。第三記憶Memory。包括短期記憶和長(zhǎng)期記憶。短期記憶就是當(dāng)前對(duì)話的上下文讓 Agent 知道剛才發(fā)生了什么。長(zhǎng)期記憶通常是外掛一個(gè)向量數(shù)據(jù)庫(kù)讓 Agent 能記住幾天前甚至幾個(gè)月前跟用戶的交互內(nèi)容。沒(méi)有記憶的 Agent 就像金魚(yú)每次對(duì)話都從零開(kāi)始。第四規(guī)劃Planning。這是 Agent 最核心也最難做好的部分。簡(jiǎn)單任務(wù)一步就完了但復(fù)雜任務(wù)需要拆解。比如“幫我策劃一場(chǎng)團(tuán)建活動(dòng)”Agent 得自己拆成確定人數(shù)、選場(chǎng)地、定預(yù)算、安排交通、發(fā)通知。怎么拆、按什么順序拆、拆到什么粒度這些都是規(guī)劃要解決的問(wèn)題。把這四個(gè)零件拼起來(lái)一個(gè)最簡(jiǎn)版的 Agent 循環(huán)就是接收用戶輸入 → LLM 思考該做什么 → 調(diào)用工具 → 拿到結(jié)果 → LLM 再思考 → 再調(diào)工具 → 直到任務(wù)完成 → 輸出最終結(jié)果。1.3 為什么新手容易走彎路一上來(lái)就啃框架的陷阱我見(jiàn)過(guò)太多人聽(tīng)說(shuō) LangChain 火上來(lái)就 pip install langchain然后對(duì)著文檔里那一堆 Chain、Agent、Tool、Memory 的類(lèi)發(fā)呆。折騰了兩天跑通了一個(gè) demo但問(wèn)他“這個(gè) Agent 為什么這么決策”完全答不上來(lái)。問(wèn)題出在哪框架幫你封裝了太多東西導(dǎo)致你看不到底層發(fā)生了什么。LangChain 確實(shí)好用它把工具調(diào)用、提示詞模板、輸出解析這些常見(jiàn)模式都封裝成了現(xiàn)成的類(lèi)。但這也意味著當(dāng) Agent 行為不符合預(yù)期的時(shí)候你根本不知道是提示詞的問(wèn)題、工具描述的問(wèn)題、還是模型本身能力不夠。你面對(duì)的是一個(gè)黑盒而調(diào)試黑盒是最痛苦的。我的建議很明確先用最原始的方式手寫(xiě)一個(gè) Agent 循環(huán)跑通了、理解了再去用框架。手寫(xiě)一個(gè)最簡(jiǎn) Agent 大概只需要 50 行 Python 代碼不依賴任何框架直接調(diào)模型的 API。這個(gè)過(guò)程會(huì)讓你真正理解 Agent 的工作原理之后再用 LangChain 或者 Spring AI 的時(shí)候你就知道框架在幫你做什么出了問(wèn)題也知道去哪里找原因。2. 新手和轉(zhuǎn)行者到底該先學(xué)什么2.1 第一優(yōu)先級(jí)Python 基礎(chǔ)但不用學(xué)到能寫(xiě)爬蟲(chóng)的程度AI Agent 開(kāi)發(fā)目前最主流的語(yǔ)言就是 Python。原因很簡(jiǎn)單幾乎所有大模型的官方 SDK 都是 Python 優(yōu)先LangChain、CrewAI、AutoGen 這些主流框架也都是 Python 寫(xiě)的。你用 Java 也能做Spring AI 就是干這個(gè)的但生態(tài)豐富度確實(shí)差一截。那 Python 要學(xué)到什么程度我的標(biāo)準(zhǔn)是能看懂函數(shù)定義和調(diào)用、會(huì)用列表和字典、知道怎么裝第三方庫(kù)、能寫(xiě) if-else 和 for 循環(huán)、會(huì)處理 JSON 數(shù)據(jù)。就這些足夠了。你不需要會(huì)寫(xiě)裝飾器、不需要理解元類(lèi)、不需要搞懂 GIL。那些東西等你真正遇到性能問(wèn)題或者需要讀框架源碼的時(shí)候再補(bǔ)。一開(kāi)始就抱著《流暢的Python》啃大概率是啃到一半就放棄了。具體來(lái)說(shuō)你需要掌握的知識(shí)點(diǎn)變量和基本數(shù)據(jù)類(lèi)型字符串、數(shù)字、布爾值列表和字典的增刪改查for 循環(huán)和 while 循環(huán)if-elif-else 條件判斷函數(shù)的定義和調(diào)用理解參數(shù)傳遞導(dǎo)入模塊和使用 pip 安裝包讀寫(xiě)文件尤其是 JSON 文件異常處理try-except虛擬環(huán)境的使用venv 或 conda這些內(nèi)容如果每天投入兩小時(shí)零基礎(chǔ)大概兩周就能達(dá)到“夠用”的水平。有編程基礎(chǔ)的人兩三天就能撿起來(lái)。注意不要花時(shí)間去學(xué) Python 的面向?qū)ο缶幊谈呒?jí)特性。Agent 開(kāi)發(fā)中你更多是在寫(xiě)函數(shù)和調(diào) API類(lèi)繼承、多態(tài)這些概念等你需要讀框架源碼的時(shí)候再學(xué)也不遲。2.2 第二優(yōu)先級(jí)理解大模型 API 的基本用法Agent 的大腦是 LLM所以你必須知道怎么跟 LLM 打交道?，F(xiàn)在主流的方式就是通過(guò) API 調(diào)用。不管你是用哪家的模型基本流程都是一樣的注冊(cè)賬號(hào)拿到 API Key安裝對(duì)應(yīng)廠商的 SDK或者直接用 HTTP 請(qǐng)求構(gòu)造請(qǐng)求把提示詞和參數(shù)傳進(jìn)去解析響應(yīng)拿到模型返回的文本以 OpenAI 的接口為例最核心的參數(shù)就幾個(gè)model用哪個(gè)模型比如 gpt-4o、gpt-4o-minimessages對(duì)話歷史是一個(gè)列表每條消息有 role 和 contenttemperature控制隨機(jī)性0 最確定1 最隨機(jī)max_tokens限制返回的最大長(zhǎng)度tools可調(diào)用的工具列表這是 Agent 的關(guān)鍵你需要理解messages的結(jié)構(gòu)。它通常包含三種角色system系統(tǒng)提示詞設(shè)定 Agent 的身份和行為規(guī)則user用戶輸入assistant模型之前的回復(fù)多輪對(duì)話就是把歷史消息都塞進(jìn)messages列表里模型會(huì)根據(jù)整個(gè)上下文來(lái)生成回復(fù)。這個(gè)機(jī)制看起來(lái)簡(jiǎn)單但它是 Agent 記憶功能的基礎(chǔ)。還有一個(gè)關(guān)鍵概念是Function Calling或者叫 Tool Use。這是 Agent 能干活的核心機(jī)制。你可以在請(qǐng)求里定義一組工具模型在回復(fù)的時(shí)候如果覺(jué)得需要調(diào)用某個(gè)工具它不會(huì)直接返回文本而是返回一個(gè)“工具調(diào)用請(qǐng)求”告訴你它想調(diào)哪個(gè)工具、傳什么參數(shù)。你的代碼拿到這個(gè)請(qǐng)求后執(zhí)行對(duì)應(yīng)的函數(shù)把結(jié)果再塞回對(duì)話歷史讓模型繼續(xù)處理。這個(gè)循環(huán)就是 Agent 的核心循環(huán)。手寫(xiě)一遍你就徹底懂了。2.3 第三優(yōu)先級(jí)手寫(xiě)一個(gè)最簡(jiǎn) Agent不依賴任何框架現(xiàn)在到了最關(guān)鍵的一步。我下面給出一段最簡(jiǎn) Agent 的偽代碼邏輯你用任何語(yǔ)言都能實(shí)現(xiàn)# 定義工具 def get_weather(city): # 實(shí)際調(diào)用天氣API return 晴25度 # 工具描述告訴模型這個(gè)工具是干什么的 tools [ { name: get_weather, description: 查詢指定城市的天氣, parameters: { city: 城市名稱(chēng) } } ] # 主循環(huán) messages [ {role: system, content: 你是一個(gè)助手可以查天氣}, {role: user, content: 北京今天天氣怎么樣} ] while True: # 調(diào)模型 response call_llm(messages, tools) # 如果模型返回的是工具調(diào)用 if response.has_tool_call(): tool_name response.tool_name tool_args response.tool_args # 執(zhí)行工具 result execute_tool(tool_name, tool_args) # 把工具結(jié)果塞回對(duì)話 messages.append(response.message) messages.append({ role: tool, content: result }) else: # 模型返回了最終文本 print(response.content) break這段代碼的核心邏輯就是調(diào)模型 → 看它要不要調(diào)工具 → 要就執(zhí)行工具并把結(jié)果喂回去 → 不要就輸出結(jié)果結(jié)束。就這么簡(jiǎn)單。你把這個(gè)邏輯手寫(xiě)一遍用真實(shí)的 API 跑通你就已經(jīng)跨過(guò)了 AI Agent 開(kāi)發(fā)的門(mén)檻。后面再學(xué) LangChain、LangGraph、Spring AI你就是在學(xué)“怎么把這個(gè)循環(huán)寫(xiě)得更優(yōu)雅、更可擴(kuò)展”而不是在學(xué)“Agent 是什么”。2.4 第四優(yōu)先級(jí)再學(xué)框架而且要有選擇地學(xué)等你手寫(xiě)跑通了再來(lái)看框架你的視角就完全不一樣了。你看到 LangChain 的AgentExecutor你會(huì)想“哦這就是把我剛才那個(gè) while 循環(huán)封裝了一下”。你看到Tool類(lèi)你會(huì)想“這就是我剛才那個(gè) tools 列表的面向?qū)ο蟀姹尽薄Ｄ强蚣茉趺催x我的建議是LangChain / LangGraph生態(tài)最全文檔最多社區(qū)最大。LangGraph 是 LangChain 團(tuán)隊(duì)后來(lái)推出的專(zhuān)門(mén)做有狀態(tài)的、多步驟的 Agent 編排。如果你要做復(fù)雜的、有分支和循環(huán)的 Agent 流程LangGraph 比原始的 LangChain Agent 更合適。缺點(diǎn)是抽象層多學(xué)習(xí)曲線陡。CrewAI主打多 Agent 協(xié)作。你可以定義多個(gè)角色比如“研究員”、“寫(xiě)手”、“審核員”讓它們互相配合完成任務(wù)。適合做內(nèi)容生產(chǎn)、數(shù)據(jù)分析這類(lèi)需要多角色協(xié)作的場(chǎng)景。API 設(shè)計(jì)比較直觀上手快。AutoGen微軟出的也是多 Agent 對(duì)話框架。特點(diǎn)是 Agent 之間可以自動(dòng)對(duì)話來(lái)解決問(wèn)題。適合做需要多輪討論和辯論的場(chǎng)景。Spring AIJava 生態(tài)的選擇。如果你本身是 Java 開(kāi)發(fā)者不想轉(zhuǎn) PythonSpring AI 提供了跟 LangChain 類(lèi)似的能力。但說(shuō)實(shí)話目前 Java 生態(tài)在 Agent 開(kāi)發(fā)這塊的成熟度還是不如 Python。Dify低代碼平臺(tái)可視化編排 Agent 流程。適合不寫(xiě)代碼或者代碼能力較弱的產(chǎn)品經(jīng)理、運(yùn)營(yíng)人員快速搭建原型。但靈活性受限復(fù)雜邏輯還是得寫(xiě)代碼。我的建議是先深入學(xué)一個(gè)別貪多。如果你主要做單 Agent 加工具調(diào)用的場(chǎng)景LangChain 就夠了。如果你要做多 Agent 協(xié)作看 CrewAI 或 AutoGen。如果你要精細(xì)控制 Agent 的狀態(tài)流轉(zhuǎn)看 LangGraph。2.5 關(guān)于 MCP它解決的是什么問(wèn)題MCP 最近熱度很高但很多人搞不清楚它到底是什么。我用一句話解釋MCP 是一個(gè)讓 Agent 跟外部工具對(duì)接的標(biāo)準(zhǔn)協(xié)議。在沒(méi)有 MCP 之前你每接一個(gè)工具都要自己寫(xiě)適配代碼。比如你要讓 Agent 能查數(shù)據(jù)庫(kù)你得寫(xiě)一個(gè)函數(shù)定義參數(shù)處理返回結(jié)果。你要讓它能操作文件系統(tǒng)又得寫(xiě)一套。每個(gè)工具的接入方式都不一樣復(fù)用性很差。MCP 的思路是定義一套標(biāo)準(zhǔn)接口工具提供方按照這個(gè)標(biāo)準(zhǔn)來(lái)實(shí)現(xiàn)Agent 這邊也按照這個(gè)標(biāo)準(zhǔn)來(lái)調(diào)用。這樣工具就能即插即用。你可以把它類(lèi)比成 USB 接口——以前每個(gè)設(shè)備都有自己的接口現(xiàn)在統(tǒng)一成 USB插上就能用。MCP 的核心概念包括MCP Server工具提供方暴露一組能力比如讀文件、查數(shù)據(jù)庫(kù)、調(diào) APIMCP ClientAgent 這邊負(fù)責(zé)連接 Server 并調(diào)用能力ResourcesServer 暴露的數(shù)據(jù)資源ToolsServer 暴露的可執(zhí)行操作Prompts預(yù)定義的提示詞模板現(xiàn)在很多工具已經(jīng)開(kāi)始支持 MCP 了比如 Playwright MCP 可以讓 Agent 操作瀏覽器百度地圖 MCP 可以讓 Agent 查地理位置。如果你要做的 Agent 需要跟大量外部工具對(duì)接花點(diǎn)時(shí)間了解 MCP 是值得的。但如果你只是做一個(gè)小 demo手寫(xiě)幾個(gè)工具函數(shù)就夠了不用急著上 MCP。3. 實(shí)操?gòu)牧闶謱?xiě)一個(gè)能查天氣和算數(shù)的 Agent3.1 環(huán)境準(zhǔn)備Python 安裝和虛擬環(huán)境先說(shuō) Python 安裝。Windows 用戶去 python.org 下載安裝包安裝的時(shí)候記得勾選“Add Python to PATH”。Mac 用戶可以用 Homebrew 裝brew install python。Linux 用戶一般系統(tǒng)自帶但版本可能比較老建議用 pyenv 裝一個(gè)新版本。裝完之后驗(yàn)證一下python --version pip --version然后建一個(gè)虛擬環(huán)境這是好習(xí)慣避免不同項(xiàng)目的依賴打架python -m venv agent-env # Windows agent-env\Scripts\activate # Mac/Linux source agent-env/bin/activate虛擬環(huán)境激活后命令行前面會(huì)出現(xiàn)(agent-env)的標(biāo)識(shí)。接下來(lái)裝依賴pip install openai requests如果你用的是其他廠商的模型把openai換成對(duì)應(yīng)的 SDK 就行。3.2 定義工具函數(shù)查天氣和做計(jì)算我們定義兩個(gè)工具一個(gè)查天氣一個(gè)做數(shù)學(xué)計(jì)算。查天氣我們用一個(gè)模擬函數(shù)實(shí)際項(xiàng)目中你可以接真實(shí) API。import json import math def get_weather(city: str) - str: 模擬查天氣實(shí)際項(xiàng)目中替換為真實(shí)API調(diào)用 weather_data { 北京: 晴氣溫25度濕度40%, 上海: 多云氣溫28度濕度65%, 廣州: 雷陣雨氣溫30度濕度80%, } return weather_data.get(city, f未找到{city}的天氣數(shù)據(jù)) def calculate(expression: str) - str: 計(jì)算數(shù)學(xué)表達(dá)式 try: # 只允許基本數(shù)學(xué)運(yùn)算避免安全問(wèn)題 allowed set(0123456789-*/.() ) if not all(c in allowed for c in expression): return 表達(dá)式包含不允許的字符 result eval(expression) return str(result) except Exception as e: return f計(jì)算錯(cuò)誤{str(e)}注意calculate函數(shù)里我做了字符白名單校驗(yàn)。直接用eval是有安全風(fēng)險(xiǎn)的雖然這只是個(gè) demo但養(yǎng)成好習(xí)慣很重要。3.3 構(gòu)造工具描述讓模型知道有什么工具可用工具描述是 Agent 能不能正確選用工具的關(guān)鍵。描述要清晰、準(zhǔn)確、包含參數(shù)說(shuō)明。tools [ { type: function, function: { name: get_weather, description: 查詢指定城市的當(dāng)前天氣情況, parameters: { type: object, properties: { city: { type: string, description: 城市名稱(chēng)例如北京、上海 } }, required: [city] } } }, { type: function, function: { name: calculate, description: 計(jì)算數(shù)學(xué)表達(dá)式支持加減乘除和括號(hào), parameters: { type: object, properties: { expression: { type: string, description: 數(shù)學(xué)表達(dá)式例如(35)*2 } }, required: [expression] } } } ]工具描述有幾個(gè)經(jīng)驗(yàn)第一description 要寫(xiě)清楚這個(gè)工具是干什么的什么時(shí)候該用。比如“查詢指定城市的當(dāng)前天氣情況”就比“查天氣”好。第二參數(shù)的 description 要給出示例。模型看到示例更容易傳對(duì)參數(shù)。第三required 要準(zhǔn)確。必填參數(shù)沒(méi)標(biāo) required模型可能不傳。3.4 主循環(huán)實(shí)現(xiàn)調(diào)模型、執(zhí)行工具、喂回結(jié)果from openai import OpenAI client OpenAI(api_key你的API_KEY) def run_agent(user_input: str): messages [ {role: system, content: 你是一個(gè)助手可以查天氣和做數(shù)學(xué)計(jì)算。需要時(shí)調(diào)用工具。}, {role: user, content: user_input} ] max_iterations 10 # 防止無(wú)限循環(huán) for i in range(max_iterations): response client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolstools, tool_choiceauto ) msg response.choices[0].message # 沒(méi)有工具調(diào)用直接返回文本 if not msg.tool_calls: return msg.content # 有工具調(diào)用把 assistant 消息加入歷史 messages.append(msg) # 逐個(gè)執(zhí)行工具 for tool_call in msg.tool_calls: func_name tool_call.function.name func_args json.loads(tool_call.function.arguments) if func_name get_weather: result get_weather(func_args[city]) elif func_name calculate: result calculate(func_args[expression]) else: result f未知工具{func_name} # 把工具結(jié)果加入歷史 messages.append({ role: tool, tool_call_id: tool_call.id, content: result }) return 達(dá)到最大迭代次數(shù)任務(wù)未完成這段代碼就是 Agent 的核心。max_iterations是必須的防止模型陷入死循環(huán)一直調(diào)工具。tool_call_id也很關(guān)鍵模型靠這個(gè) ID 來(lái)匹配哪個(gè)結(jié)果對(duì)應(yīng)哪個(gè)工具調(diào)用。3.5 跑起來(lái)看看效果# 測(cè)試 print(run_agent(北京今天天氣怎么樣)) print(run_agent(幫我算一下 (15 27) * 3 等于多少)) print(run_agent(上海和廣州的天氣分別怎么樣然后算一下兩個(gè)城市溫度的平均值))第三個(gè)測(cè)試用例比較有意思它需要 Agent 先調(diào)兩次天氣工具拿到結(jié)果后再調(diào)計(jì)算工具。這就是多步推理和工具編排。如果你的 Agent 能正確處理這個(gè) case說(shuō)明基本邏輯沒(méi)問(wèn)題了。實(shí)操心得調(diào)試 Agent 的時(shí)候把每一步的messages打印出來(lái)看。你會(huì)清楚地看到模型什么時(shí)候決定調(diào)工具、傳了什么參數(shù)、拿到結(jié)果后怎么繼續(xù)推理。這個(gè)習(xí)慣能幫你快速定位問(wèn)題。4. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄4.1 模型不調(diào)工具怎么辦這是最常見(jiàn)的問(wèn)題。你明明定義了工具用戶的問(wèn)題也明顯需要工具但模型就是直接返回文本不調(diào)工具。原因通常有三個(gè)第一工具描述不夠清晰。模型不知道這個(gè)工具是干什么的自然就不會(huì)用。解決辦法是把 description 寫(xiě)得更具體明確說(shuō)明“什么時(shí)候應(yīng)該使用這個(gè)工具”。第二系統(tǒng)提示詞沒(méi)有引導(dǎo)。在 system message 里加一句“當(dāng)需要查詢實(shí)時(shí)信息或進(jìn)行計(jì)算時(shí)請(qǐng)調(diào)用相應(yīng)的工具”能顯著提高工具調(diào)用率。第三模型能力不夠。一些小模型或者老模型對(duì) Function Calling 的支持不好。換個(gè)更強(qiáng)的模型試試。還有一個(gè)技巧是設(shè)置tool_choicerequired強(qiáng)制模型必須調(diào)用工具。但這只適合你確定每次都需要調(diào)工具的場(chǎng)景一般還是用auto。4.2 工具參數(shù)傳錯(cuò)怎么排查模型傳錯(cuò)參數(shù)也很常見(jiàn)。比如該傳城市名它傳了個(gè)省份名該傳數(shù)字它傳了個(gè)字符串。排查方法在json.loads(tool_call.function.arguments)之后打印一下參數(shù)看看模型到底傳了什么。如果參數(shù)格式不對(duì)在工具定義的 parameters 里把類(lèi)型和描述寫(xiě)得更嚴(yán)格。比如type: string加上enum: [北京, 上海, 廣州]限定取值范圍。另外在工具函數(shù)內(nèi)部做參數(shù)校驗(yàn)也很重要。不要假設(shè)模型傳的參數(shù)一定是對(duì)的該做的校驗(yàn)都要做。4.3 Agent 陷入死循環(huán)怎么處理死循環(huán)的表現(xiàn)是Agent 反復(fù)調(diào)同一個(gè)工具或者在不同工具之間來(lái)回跳就是不輸出最終結(jié)果。原因通常是工具返回的結(jié)果模型不滿意或者模型不知道下一步該干什么。解決辦法第一設(shè)置最大迭代次數(shù)。我上面代碼里的max_iterations就是干這個(gè)的。第二在工具返回結(jié)果里加入引導(dǎo)信息。比如查不到天氣的時(shí)候返回“未找到該城市數(shù)據(jù)請(qǐng)嘗試其他城市或告知用戶無(wú)法查詢”而不是簡(jiǎn)單返回一個(gè)空字符串。第三在系統(tǒng)提示詞里明確“如果工具無(wú)法提供有效信息請(qǐng)直接告知用戶”。4.4 常見(jiàn)問(wèn)題速查表問(wèn)題現(xiàn)象可能原因排查方法解決方案模型不調(diào)工具描述不清/提示詞沒(méi)引導(dǎo)/模型能力不足檢查工具 description 和 system prompt完善描述、加引導(dǎo)語(yǔ)、換模型參數(shù)傳錯(cuò)參數(shù)定義不明確/模型理解偏差打印實(shí)際傳入?yún)?shù)加 enum 限定、加參數(shù)校驗(yàn)死循環(huán)工具結(jié)果不滿足/無(wú)終止條件打印每輪 messages設(shè)最大迭代、優(yōu)化工具返回值返回結(jié)果不符合預(yù)期提示詞不夠具體檢查 system prompt細(xì)化角色設(shè)定和輸出格式要求API 調(diào)用報(bào)錯(cuò)Key 無(wú)效/額度用完/網(wǎng)絡(luò)問(wèn)題看錯(cuò)誤碼和錯(cuò)誤信息檢查 Key、充值、重試響應(yīng)太慢模型本身慢/工具執(zhí)行慢分別計(jì)時(shí)換更快的模型、優(yōu)化工具邏輯4.5 幾個(gè)我踩過(guò)的坑坑一工具函數(shù)拋異常導(dǎo)致整個(gè) Agent 崩潰。工具函數(shù)一定要用 try-except 包起來(lái)返回錯(cuò)誤信息而不是拋異常。模型拿到錯(cuò)誤信息后通常會(huì)自己調(diào)整策略。坑二對(duì)話歷史太長(zhǎng)導(dǎo)致 token 超限。多輪對(duì)話后messages 列表會(huì)越來(lái)越長(zhǎng)。解決辦法是定期截?cái)鄽v史只保留最近 N 輪或者用摘要的方式壓縮歷史。坑三工具描述里寫(xiě)了太多技術(shù)細(xì)節(jié)。工具描述是給模型看的不是給開(kāi)發(fā)者看的。用自然語(yǔ)言寫(xiě)清楚“這個(gè)工具做什么、什么時(shí)候用、參數(shù)是什么”就夠了不要寫(xiě)實(shí)現(xiàn)細(xì)節(jié)。坑四忽略了 tool_call_id 的匹配。多個(gè)工具調(diào)用時(shí)每個(gè) tool_call 有自己的 id返回結(jié)果時(shí)必須帶上對(duì)應(yīng)的 id。不匹配的話模型會(huì)混亂。5. 學(xué)完基礎(chǔ)之后往哪走5.1 下一步給 Agent 加上記憶你現(xiàn)在寫(xiě)的 Agent 每次對(duì)話都是獨(dú)立的沒(méi)有記憶。用戶說(shuō)“北京天氣怎么樣”Agent 查完告訴你。然后用戶說(shuō)“那上海呢”Agent 不知道“那”指的是天氣因?yàn)樗挥浀蒙弦惠唽?duì)話。加記憶最簡(jiǎn)單的方式就是把歷史消息都保留在 messages 列表里。但這樣 token 消耗會(huì)越來(lái)越大。更好的做法是用向量數(shù)據(jù)庫(kù)做長(zhǎng)期記憶把歷史對(duì)話存進(jìn)向量庫(kù)每次新對(duì)話時(shí)檢索最相關(guān)的幾條歷史記錄塞進(jìn)上下文。LangChain 提供了ConversationBufferMemory、ConversationSummaryMemory等現(xiàn)成的記憶組件但建議你先手寫(xiě)一個(gè)最簡(jiǎn)單的版本理解原理后再用框架的。5.2 再下一步多 Agent 協(xié)作單個(gè) Agent 能做的事情有限。當(dāng)你需要完成一個(gè)復(fù)雜任務(wù)時(shí)可以拆成多個(gè) Agent 各司其職。比如做一個(gè)“市場(chǎng)調(diào)研報(bào)告生成”系統(tǒng)研究員 Agent負(fù)責(zé)搜索和收集信息分析師 Agent負(fù)責(zé)分析數(shù)據(jù)、提煉觀點(diǎn)寫(xiě)手 Agent負(fù)責(zé)撰寫(xiě)報(bào)告審核員 Agent負(fù)責(zé)檢查事實(shí)和邏輯每個(gè) Agent 有自己的系統(tǒng)提示詞和工具集它們之間通過(guò)消息傳遞來(lái)協(xié)作。CrewAI 和 AutoGen 就是專(zhuān)門(mén)做這個(gè)的框架。但我要提醒一句多 Agent 系統(tǒng)的復(fù)雜度是指數(shù)級(jí)上升的。兩個(gè) Agent 協(xié)作還好五個(gè) Agent 協(xié)作的時(shí)候調(diào)試會(huì)變得非常困難。建議先把單 Agent 玩透再考慮多 Agent。5.3 關(guān)于框架學(xué)習(xí)的最終建議回到標(biāo)題那句話別一上來(lái)就啃框架。我見(jiàn)過(guò)太多人LangChain 的文檔翻了一遍各種概念背得滾瓜爛熟但讓他從零寫(xiě)一個(gè) Agent 循環(huán)寫(xiě)不出來(lái)。這就是本末倒置了。正確的學(xué)習(xí)路徑是Python 基礎(chǔ)兩周大模型 API 基本用法三天手寫(xiě)最簡(jiǎn) Agent 循環(huán)一天手寫(xiě)帶記憶和多工具的 Agent三天選一個(gè)框架深入學(xué)習(xí)一周用框架重構(gòu)你之前手寫(xiě)的 Agent兩天這個(gè)路徑走下來(lái)大概一個(gè)月左右你就能獨(dú)立開(kāi)發(fā)一個(gè)可用的 AI Agent 了。比上來(lái)就啃框架快得多也扎實(shí)得多。框架是工具不是知識(shí)。工具會(huì)過(guò)時(shí)LangChain 可能明年就被別的框架取代了但 Agent 的核心原理——LLM 決策、工具調(diào)用、循環(huán)執(zhí)行——這些是不會(huì)變的。把原理吃透換什么框架你都能快速上手。我在實(shí)際帶新人的過(guò)程中發(fā)現(xiàn)那些先手寫(xiě)再學(xué)框架的人遇到問(wèn)題時(shí)的排查能力強(qiáng)很多。因?yàn)樗麄冎赖讓影l(fā)生了什么框架報(bào)錯(cuò)的時(shí)候能判斷是框架的問(wèn)題還是自己代碼的問(wèn)題。而直接學(xué)框架的人遇到報(bào)錯(cuò)往往一臉懵只能去社區(qū)提問(wèn)等回答。最后分享一個(gè)小技巧每次學(xué)一個(gè)新框架的時(shí)候先別急著看它的文檔先自己想“如果讓我設(shè)計(jì)這個(gè)框架我會(huì)怎么設(shè)計(jì)”然后再去看它的 API。這樣你學(xué)起來(lái)會(huì)快很多因?yàn)槟闶窃隍?yàn)證自己的想法而不是被動(dòng)接受信息。