如果你正準備學 AI Agent但搜了一圈資料發(fā)現(xiàn)要么是“三分鐘看懂 Agent”的概念科普要么是“教你用框架調(diào)接口”的 API 拼裝那就說明你看的內(nèi)容還不夠落地。真正的 Agent 開發(fā)最核心的并不是某個框架、某個模型而是你能不能把一個“會思考的模型”接進你自己的業(yè)務(wù)工具里讓它真的幫你干活。本篇文章就按照“應(yīng)用解讀 項目實戰(zhàn)”兩條線從 0 到 1 帶你拆一個最小可運行的 AI Agent 項目看懂運行邏輯也拿得出手。先說我對 2026 年 AI Agent 學習路線的判斷越早上手做“最小閉環(huán)”成長越快?，F(xiàn)在很多崗位描述里寫“熟悉 Agent 開發(fā)”“了解 ReAct 原理”本質(zhì)上都是在問一件事——你是否理解模型、工具、編排這三個層次的關(guān)系。本文不會讓你上來就啃 LangChain 源碼而是先用一個不到 300 行的 Python 項目把 Agent 的完整運行鏈路跑通然后再講清楚它背后的原理以及工程化落地的坑。你不需要先成為提示詞專家也不需要會微調(diào)模型只需要有一點 Python 基礎(chǔ)能打開命令行就能跟上這篇文章。讀完以后你會得到一套可復(fù)制的 Agent 項目代碼一套工具調(diào)用的安全設(shè)計思路以及一份能用來準備面試或?qū)嶋H項目開發(fā)的排錯清單。1. 這篇文章真正要解決的問題如果你去搜“AI Agent”看到的一定是一堆名詞ReAct、Function Calling、多 Agent 協(xié)作、記憶機制、規(guī)劃能力?？吹臅r候覺得懂了合上文章還是不會寫代碼。這是目前 AI Agent 學習最普遍的問題——信息密度高但項目閉環(huán)少。這篇文章要解決的痛點有三個第一個痛點只會用 ChatGPT 聊天不知道怎么讓模型主動調(diào)用工具。很多人以為 Agent 就是“模型更聰明了什么都能答”實際上它是“模型在推理過程中能決定去調(diào)用某個外部函數(shù)”。這個動作聽起來簡單但真正寫代碼時會遇到一連串問題工具怎么定義參數(shù)怎么傳模型返回的結(jié)果怎么解析一旦出錯怎么恢復(fù)第二個痛點會用 LangChain 但只停留在復(fù)制粘貼。LangChain 這類框架確實封裝了大量能力但也把 Agent 的運行邏輯藏在了黑盒里。一旦出現(xiàn) bug你很難判斷是模型問題、工具問題還是編排問題。我見過不少同學簡歷上寫“熟悉 LangChain”面試官問“Agent 的循環(huán)依賴怎么處理”就卡住了。所以本文故意不用框架而是基于大模型的 Function Calling 接口手寫一個最小執(zhí)行器。第三個痛點缺少從“代碼跑通”到“項目落地”的工程意識。寫一個 demo 和做一個可部署的服務(wù)中間還隔著很多東西環(huán)境隔離、密鑰管理、超時控制、工具權(quán)限邊界、日志追蹤。文章后面會專門用一章來交代最佳實踐。什么背景的讀者最該看這篇文章后端開發(fā)想把 Agent 能力嵌入自己的 Spring Boot、FastAPI 服務(wù)測試開發(fā)想用 Agent 做自動化測試用例生成、缺陷分析前端開發(fā)想給自己的應(yīng)用增加“自然語言操作數(shù)據(jù)”的交互層產(chǎn)品和運營不需要寫核心算法但需要理解 Agent 能力邊界能和技術(shù)有效溝通正在準備 Agent 相關(guān)面試的求職者需要把原理講清楚也要能現(xiàn)場寫一個最小實現(xiàn)。說到底2026 年判斷一個開發(fā)者“懂不懂 Agent”看的不是他收藏了多少資料而是他能不能從一個空目錄開始把一個帶工具的 Agent 服務(wù)搭起來。2. AI Agent 的核心概念它和聊天機器人到底差在哪要理解 Agent先要破除一個直觀誤解ChatGPT 本身不是一個 Agent它只是一個對話模型。你問它“幫我查一下服務(wù)器日志”它只能告訴你“你可以用 grep 命令”但它不會真的去執(zhí)行 grep。Agent 則不同它可以在推理后決定調(diào)用一個工具把工具執(zhí)行的結(jié)果拿回來繼續(xù)推理最終給你一個答案。用一句話概括Agent 大模型 工具 循環(huán)決策。這里拆開看四個核心要素模型Model負責理解意圖、生成推理、決定下一步行動。2026 年幾乎所有主流模型都支持 Function Calling這是 Agent 能落地的關(guān)鍵能力。工具Tool模型與外部世界交互的“手腳”?？梢允遣閿?shù)據(jù)庫、調(diào) API、執(zhí)行搜索、讀寫文件、發(fā)消息。模型的訓(xùn)練數(shù)據(jù)是固定的工具讓它可以獲取實時信息并產(chǎn)生真實影響。記憶Memory短期記憶就是當前對話上下文長期記憶一般靠向量數(shù)據(jù)庫保存歷史知識。最小實現(xiàn)里短期記憶已經(jīng)足夠。規(guī)劃Planning把一個復(fù)雜任務(wù)拆成多個步驟。簡單 Agent 靠 ReAct 循環(huán)自動規(guī)劃復(fù)雜 Agent 會顯式生成計劃再逐步執(zhí)行。再看幾個容易混淆的詞概念常見誤解更準確的理解ChatBot能回答問題就是 Agent只輸出文本不產(chǎn)生外部動作Function Calling模型“會”調(diào)用函數(shù)模型只是輸出結(jié)構(gòu)化的調(diào)用意圖實際執(zhí)行靠你的代碼ReAct一種框架一種“推理-行動-觀察”的循環(huán)模式Agent 框架等于 LangChainLangChain 只是工具Agent 的核心是編排邏輯Tool由模型內(nèi)置工具由開發(fā)者實現(xiàn)模型只會描述“想調(diào)哪個”這里真正容易踩坑的是 Function Calling 的邊界。模型并不會真的去連接數(shù)據(jù)庫、發(fā)送 HTTP 請求它只是在生成的內(nèi)容里多了一種結(jié)構(gòu)化字段。例如模型可能返回{ name: safe_calc, arguments: {\expression\: \23*4\} }你的代碼解析這個字段執(zhí)行真正的加法邏輯再把結(jié)果作為消息回傳給模型。這個“發(fā)起調(diào)用 - 執(zhí)行工具 - 回傳結(jié)果 - 繼續(xù)推理”的過程就是 Agent 最核心的循環(huán)。ReAct 思想也值得單獨說。ReAct 是 Reasoning Acting它強調(diào)模型不能只“想”不“做”也不能只“做”不“想”。每一輪循環(huán)里模型先根據(jù)當前信息判斷下一步該干什么然后行動觀察行動結(jié)果再繼續(xù)推理。你會在下面的代碼里實際看到這個模式。3. 從 0 到 1 的落地思路為什么先手寫一個最小 Agent既然框架很多為什么還要手寫因為手寫一遍你會被迫搞清楚三個問題工具如何被描述、模型輸出如何被解析、多輪上下文如何被組織。這三個問題恰恰是任何一個 Agent 框架都要替你解決的核心。先不用框架跑通之后再切換到 LangChain、LangGraph 或者 Spring AI你會發(fā)現(xiàn)自己是在“降維使用”而不是被框架牽著走。本文的項目叫minimal_agent_demo整體結(jié)構(gòu)如下minimal_agent_demo/ ├── tools.py # 工具實現(xiàn)與注冊 ├── agent_core.py # 最小 ReAct 執(zhí)行器 ├── main.py # FastAPI 封裝把 Agent 暴露成 HTTP 接口 └── docs/ # 本地知識庫目錄用于演示文檔檢索工具演示場景選了一個貼近日常的組合Agent 需要具備三個能力——獲取當前時間、做數(shù)學計算、檢索本地文檔。這三個能力分別代表了 Agent 的常見工具類型系統(tǒng)類工具、計算類工具、檢索類工具。在技術(shù)選型上我采用 OpenAI 兼容的 Chat Completions 接口。這樣做的原因是兼容接口非常普遍無論是官方模型服務(wù)還是各種私有化部署的模型網(wǎng)關(guān)大都支持這一協(xié)議。項目代碼不綁定某個具體廠商你只需要配置模型服務(wù)地址和 API Key 就能運行。關(guān)于“為什么不用 LangChain”還要多說一句。并不是 LangChain 不好而是對學習者來說先用最少的依賴理解原理更符合“從 0 到 1”的目標。等你看懂了手寫版本再去看 LangChain 的 AgentExecutor 源碼思路會非常流暢。4. 環(huán)境準備與項目初始化項目依賴很少只有三個openai官方 Python SDK、fastapi、uvicorn。其中 fastapi 和 uvicorn 只在最后封裝 HTTP 服務(wù)時用到如果你只想跑命令行版本可以先不裝。操作系統(tǒng)不限macOS、Linux、Windows 都可以。建議使用 Python 3.10 及以上版本并且創(chuàng)建獨立的虛擬環(huán)境。mkdir minimal_agent_demo cd minimal_agent_demo python -m venv .venv # Windows .venv\Scripts\activate # macOS / Linux source .venv/bin/activate pip install openai1.0 fastapi uvicorn安裝完成之后需要配置模型服務(wù)的訪問變量。強烈建議不要直接在代碼里寫死 API Key而是通過環(huán)境變量注入避免不小心提交到 Git 倉庫。# macOS / Linux export OPENAI_API_KEY你的API-KEY export OPENAI_BASE_URL你的兼容模型服務(wù)地址例如 https://your-model-service.example.com/v1 # Windows PowerShell # $env:OPENAI_API_KEY 你的API-KEY # $env:OPENAI_BASE_URL 你的兼容模型服務(wù)地址如果你的模型服務(wù)就是官方默認地址OPENAI_BASE_URL可以不設(shè)置代碼里會按默認地址處理。但要注意本項目的 Agent 依賴 Function Calling 能力所以模型服務(wù)需要支持 tools 參數(shù)這一點在選型時要提前確認。啟動時建議先做一個連通性測試用下列命令確認 SDK 能正常訪問模型python -c from openai import OpenAI; import os; client OpenAI(api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL) or None); print(client.chat.completions.create(model你的模型名, messages[{role:user,content:hi}]).choices[0].message.content)如果這里能返回結(jié)果說明基礎(chǔ)環(huán)境沒問題可以直接進入下一步。否則先排查地址、Key 和網(wǎng)絡(luò)連通性不用急著往下寫代碼。5. 工具設(shè)計Agent 的“手腳”從哪來工具是 Agent 價值和風險并存的來源。一方面沒有工具模型只能憑訓(xùn)練知識回答無法觸達你的業(yè)務(wù)系統(tǒng)另一方面如果給 Agent 掛載了危險工具比如任意命令執(zhí)行、刪庫接口一旦模型誤調(diào)用后果會很嚴重。下面這段代碼定義三個工具函數(shù)。注意安全計算器的實現(xiàn)方式我沒有直接用eval而是用 Python 的ast模塊解析表達式只允許白名單內(nèi)的運算節(jié)點。這是一個非常值得保留的工程習慣——凡是給 Agent 用的工具都要盡量縮小能力邊界。# 文件路徑minimal_agent_demo/tools.py import ast import operator from datetime import datetime from pathlib import Path def get_current_time() - str: 返回當前的日期和時間格式為 YYYY-MM-DD HH:MM:SS。 return datetime.now().strftime(%Y-%m-%d %H:%M:%S) # 安全計算器只允許四則運算、取模、整除和冪運算避免 eval 注入風險 _ALLOWED_OPS { ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul, ast.Div: operator.truediv, ast.Mod: operator.mod, ast.FloorDiv: operator.floordiv, ast.Pow: operator.pow, } def safe_calc(expression: str) - float: 計算一個僅包含數(shù)字和四則運算的數(shù)學表達式。 tree ast.parse(expression, modeeval) for node in ast.walk(tree): if isinstance(node, ast.Expression): continue if isinstance(node, ast.Constant): continue if type(node) not in _ALLOWED_OPS: raise ValueError(f表達式包含不允許的語法: {type(node).__name__}) result eval(compile(tree, filename, modeeval), {__builtins__: {}}, {}) return float(result) def search_docs(keyword: str, base_dir: str ./docs) - str: 在 docs 目錄下的 .md / .txt 文件中搜索包含關(guān)鍵詞的片段。 results [] for path in Path(base_dir).rglob(*): if path.suffix not in (.md, .txt): continue try: lines path.read_text(encodingutf-8).splitlines() except Exception: continue for idx, line in enumerate(lines, 1): if keyword in line: results.append(f{path}:{idx}: {line.strip()}) if not results: return 沒有找到相關(guān)文檔。 return \n.join(results[:20])tools.py里的函數(shù)還只是普通 Python 函數(shù)模型并不知道它們的存在。要讓模型知道“可以調(diào)用哪些工具”需要把工具描述成結(jié)構(gòu)化的 schema這就是 Function Calling 里最關(guān)鍵的一步。# 文件路徑minimal_agent_demo/tools.py繼續(xù)追加 TOOLS_META [ { type: function, function: { name: get_current_time, description: 獲取當前日期和時間。適合回答現(xiàn)在幾點、今天是幾號等問題。, parameters: { type: object, properties: {}, required: [] } } }, { type: function, function: { name: safe_calc, description: 計算數(shù)學表達式例如 23*4。適合需要精確計算的場景。, parameters: { type: object, properties: { expression: {type: string, description: 要計算的數(shù)學表達式} }, required: [expression] } } }, { type: function, function: { name: search_docs, description: 在本地知識庫 docs 目錄中搜索包含關(guān)鍵詞的文檔片段。, parameters: { type: object, properties: { keyword: {type: string, description: 要搜索的關(guān)鍵詞} }, required: [keyword] } } }, ] TOOLS_DISPATCH { get_current_time: lambda args: get_current_time(), safe_calc: lambda args: str(safe_calc(args[expression])), search_docs: lambda args: search_docs(keywordargs[keyword]), }TOOLS_META發(fā)給模型告訴它“環(huán)境里有哪些工具可用”。TOOLS_DISPATCH是開發(fā)者自己的函數(shù)路由表等模型真的喊出“我要調(diào)用 safe_calc”時程序從這個字典里找到對應(yīng)的函數(shù)并執(zhí)行。這里有三個值得注意的設(shè)計和單純調(diào) API 不同第一description很重要。模型不會看你的函數(shù)源碼它只知道這些文字描述。描述寫得越清楚模型選對工具的概率越高。第二TOOLS_DISPATCH采用字典映射而不是一堆 if-else方便以后動態(tài)注冊新工具。第三search_docs的base_dir沒有暴露在 schema 里這樣即使模型“想”去掃描其他目錄也沒有參數(shù)入口。這是權(quán)限收斂的典型做法。6. Agent 核心循環(huán)手寫一個最小 ReAct 執(zhí)行器有了工具下面實現(xiàn) Agent 的核心類。這個類的任務(wù)很簡單接收用戶問題進入一個最多執(zhí)行 N 輪的循環(huán)每一輪把當前消息列表發(fā)給模型如果模型要求調(diào)用工具就執(zhí)行工具并把結(jié)果加入消息列表如果模型直接給出最終回答就返回結(jié)果。# 文件路徑minimal_agent_demo/agent_core.py import json import os from openai import OpenAI from tools import TOOLS_DISPATCH, TOOLS_META SYSTEM_PROMPT 你是一個運行在本地的最小 AI Agent 助手可以幫助用戶查詢時間、計算數(shù)學表達式以及檢索本地知識庫。 請根據(jù)用戶的問題決定是否需要調(diào)用工具 - 如果需要工具返回對應(yīng)的 function_call - 如果已有工具結(jié)果請根據(jù)工具結(jié)果組織自然語言回答 - 如果不需要工具直接回答用戶。 回答請保持簡潔不要重復(fù)工具輸出中不必要的信息。 class MinimalAgent: def __init__(self, model: str 你的模型名, max_iters: int 5): api_key os.getenv(OPENAI_API_KEY) base_url os.getenv(OPENAI_BASE_URL) or None if not api_key: raise ValueError(請先設(shè)置環(huán)境變量 OPENAI_API_KEY) self.client OpenAI(api_keyapi_key, base_urlbase_url) self.model model self.max_iters max_iters def run(self, user_input: str) - str: messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input}, ] step 0 while step self.max_iters: step 1 print(f[Agent] 第 {step} 輪推理 ...) response self.client.chat.completions.create( modelself.model, messagesmessages, toolsTOOLS_META, ) message response.choices[0].message # 1. 不需要調(diào)用工具直接返回最終回答 if not message.tool_calls: return message.content or # 2. 模型請求調(diào)用工具先把這條 assistant 消息追加進上下文 messages.append({ role: assistant, content: message.content, tool_calls: [ { id: tc.id, type: function, function: { name: tc.function.name, arguments: tc.function.arguments, }, } for tc in message.tool_calls ], }) # 3. 依次執(zhí)行工具并把執(zhí)行結(jié)果作為 tool 消息回傳 for tc in message.tool_calls: print(f[Agent] 調(diào)用工具: {tc.function.name}, 參數(shù): {tc.function.arguments}) try: tool_output TOOLS_DISPATCH[tc.function.name]( json.loads(tc.function.arguments) ) except Exception as e: tool_output f工具執(zhí)行出錯: {e} messages.append({ role: tool, tool_call_id: tc.id, content: tool_output, }) # 4. 達到最大輪數(shù)之后讓模型基于已有上下文做一次最終總結(jié) final_response self.client.chat.completions.create( modelself.model, messagesmessages, ) return final_response.choices[0].message.content or 達到最大推理輪數(shù)任務(wù)未完成。 if __name__ __main__: agent MinimalAgent() while True: question input(請輸入問題輸入 q 退出) if question.lower() q: break print(回答:, agent.run(question))這段代碼就是 ReAct 循環(huán)的骨架。它的核心邏輯可以抽象成四步第一步把系統(tǒng)提示詞、用戶問題和所有歷史消息一起發(fā)送給模型并帶上工具 schema。第二步檢查模型返回結(jié)果里是否有tool_calls。沒有說明模型已經(jīng)可以根據(jù)現(xiàn)有信息回答直接返回。第三步如果模型決定調(diào)用工具先把 assistant 消息連同 tool_calls 完整存入消息列表再逐個執(zhí)行工具。執(zhí)行結(jié)果以role: tool的消息回傳并攜帶對應(yīng)的tool_call_id讓模型知道這個結(jié)果屬于哪一次調(diào)用。第四步回到循環(huán)頂部繼續(xù)推理。如果達到最大輪數(shù)額外讓模型做一次最終總結(jié)避免返回空內(nèi)容。有個細節(jié)值得強調(diào)連續(xù)多輪工具調(diào)用時消息列表的順序非常重要。大模型并不是“記住”了工具結(jié)果而是每次從你傳的 messages 里重新理解上下文。如果你在追加 assistant 消息時遺漏了tool_calls字段或者 tool 消息沒有對應(yīng)上tool_call_id推理就會中斷或者報錯。這是手寫 Agent 時最常見的技術(shù)債務(wù)。另一個細節(jié)是工具異常處理。我在執(zhí)行工具時用 try-except 包裹并把錯誤信息作為 tool 結(jié)果返回。這樣做的好處是即使某個工具運行失敗Agent 也能繼續(xù)推理而不是整個流程崩潰。真正生產(chǎn)中錯誤信息甚至會被模型學習幫它調(diào)整下一步策略。7. 用 FastAPI 把 Agent 包裝成可調(diào)用的服務(wù)到了這里命令行版 Agent 已經(jīng)能跑了。但如果要接入真實業(yè)務(wù)通常需要把它包裝成 API 服務(wù)。下面用 FastAPI 寫一個最小接口只暴露一個POST /agent/ask。# 文件路徑minimal_agent_demo/main.py from fastapi import FastAPI from pydantic import BaseModel from agent_core import MinimalAgent app FastAPI(titleMinimal Agent API) try: agent MinimalAgent() except ValueError as e: agent None print(f警告: {e}) class QueryRequest(BaseModel): question: str class QueryResponse(BaseModel): answer: str app.post(/agent/ask, response_modelQueryResponse) def ask(req: QueryRequest): if agent is None: return QueryResponse(answerAgent 未初始化請先檢查環(huán)境變量 OPENAI_API_KEY。) answer agent.run(req.question) return QueryResponse(answeranswer)這里我把MinimalAgent()初始化放進了 try-except。因為main.py一旦被 uvicorn 加載如果環(huán)境變量缺失整個服務(wù)會啟動失敗。對工程來說與其讓服務(wù)崩潰不如把它降級為一個可讀的錯誤提示。這種“防御式初始化”在微服務(wù)場景里很有參考價值。啟動服務(wù)uvicorn main:app --reload --port 8000看到類似下面的日志說明服務(wù)已經(jīng)就緒INFO: Uvicorn running on http://127.0.0.1:8000 INFO: Application startup complete.然后打開另一個終端用 curl 調(diào)用接口curl -X POST http://127.0.0.1:8000/agent/ask \ -H Content-Type: application/json \ -d {question: 現(xiàn)在幾點了}也可以借助 FastAPI 自帶的交互文檔在瀏覽器打開http://127.0.0.1:8000/docs直接點擊接口調(diào)試對新手更友好。到這里你已經(jīng)從“一個會對話的模型”走到了“一個能對外提供能力的 Agent 服務(wù)”。這個服務(wù)的前景是無限的你可以把入?yún)⒏某蓸I(yè)務(wù)字段把工具換成訂單查詢接口就變成了一個能處理業(yè)務(wù)問題的“數(shù)字員工”。8. 運行結(jié)果與效果驗證按前面的步驟先把 docs 目錄建好寫一個測試文檔mkdir docs echo AI Agent 的核心是模型、工具與循環(huán)決策。 docs/agent_notes.txt然后運行命令行版python agent_core.py在交互界面輸入“現(xiàn)在幾點了”正常輸出類似[Agent] 第 1 輪推理 ... [Agent] 調(diào)用工具: get_current_time, 參數(shù): {} 回答: 現(xiàn)在是 2026-06-14 10:23:45。再輸入“計算 23*4 的結(jié)果”Agent 會先調(diào)用 safe_calc再結(jié)合計算結(jié)果回答而不是自己硬算。這說明函數(shù)調(diào)用鏈路是通的。最后輸入“搜索文檔中關(guān)于 Agent 的內(nèi)容”Agent 會調(diào)用 search_docs從agent_notes.txt中找到匹配片段并組織回答。如果用 FastAPI 方式驗證curl 的返回格式類似{answer:現(xiàn)在是 2026-06-14 10:23:45。}如何判斷 Agent 是否真的工作正常不是只看返回值而是看兩件事第一模型是否在需要時主動發(fā)起了工具調(diào)用。如果輸入“現(xiàn)在幾點了”模型沒有調(diào)用get_current_time而是直接給出一個編造的時間說明 Function Calling 沒有生效或者模型不支持 tools 參數(shù)。第二工具結(jié)果是否正確回傳到了上下文。如果模型明明調(diào)用了safe_calc但沒有基于工具結(jié)果回答而是自己又算了一遍多半是消息列表組織有誤tool 結(jié)果沒有真正被模型感知。如果啟動失敗先按順序排查三件事環(huán)境變量是否生效、模型服務(wù)地址是否能訪問、模型是否支持 Function Calling。不要一上來就懷疑代碼邏輯絕大多數(shù)初學問題都出在前兩層。9. 常見問題與排查思路手寫 Agent 的過程中有幾個問題出現(xiàn)頻率極高。下面用表格整理出來方便你對照排查。問題現(xiàn)象可能原因排查方式解決方案報錯Please set OPENAI_API_KEY環(huán)境變量未設(shè)置或未在當前終端生效在終端執(zhí)行echo $OPENAI_API_KEY重新 export 環(huán)境變量或把配置寫入.env文件并加載模型返回內(nèi)容為空模型不支持 Function Calling或 tools 參數(shù)被忽略查看返回的原始 message確認tool_calls字段是否存在換用支持 function calling 的模型或檢查模型服務(wù)兼容性工具被調(diào)用但報錯參數(shù)格式不匹配或函數(shù)內(nèi)部拋異?？串惓Ｐ畔⒋蛴son.loads(tc.function.arguments)的結(jié)構(gòu)在工具函數(shù)內(nèi)部加 try-except按實際參數(shù)調(diào)整解析邏輯Agent 陷入死循環(huán)工具結(jié)果不符合模型預(yù)期模型反復(fù)嘗試給循環(huán)設(shè)置 max_iters打印每一輪消息優(yōu)化工具返回格式讓結(jié)果更結(jié)構(gòu)化便于模型判斷多輪工具調(diào)用后上下文錯亂assistant 消息缺少 tool_calls 字段或 tool 消息未關(guān)聯(lián) tool_call_id檢查發(fā)送給模型的 messages 結(jié)構(gòu)嚴格按照 OpenAI 的協(xié)議要求組織消息API 請求超時模型推理時間較長或網(wǎng)絡(luò)不穩(wěn)定查看請求日志統(tǒng)計耗時提高 timeout 參數(shù)或者把模型換成推理速度更快的版本搜索文檔找不到內(nèi)容目錄路徑不對或文件編碼不是 UTF-8在 search_docs 里打印實際搜索的目錄確認當前工作目錄或使用絕對路徑看到這些現(xiàn)象時記憶一個原則先定位是模型層、工具層還是編排層的問題。模型層看返回內(nèi)容質(zhì)量工具層看函數(shù)執(zhí)行結(jié)果編排層看 messages 結(jié)構(gòu)。三個層面分開排查定位會快很多。10. 最佳實踐與工程化建議代碼跑通只是起點真正進入生產(chǎn)環(huán)境還需要考慮可維護性、權(quán)限安全和可觀測性。下面這些建議來自實際 Agent 項目里常見的教訓(xùn)。10.1 安全邊界要設(shè)得足夠小Agent 的工具調(diào)用一旦失控影響面遠超普通代碼異常。一個讀文件工具如果路徑由模型任意指定就可能變成任意文件讀取一個命令執(zhí)行工具如果沒做白名單就相當于把服務(wù)器權(quán)限交給了外部輸入。建議遵循這些原則不要給 Agent 開放任意 shell如果必須執(zhí)行命令把命令列表限制在白名單內(nèi)。文件工具只允許訪問指定目錄并用路徑標準化校驗繞過../之類的跳轉(zhuǎn)。涉及數(shù)據(jù)庫、支付、刪除等高風險操作不要直接讓 Agent 執(zhí)行而是讓 Agent 生成“待確認指令”由人工審核后執(zhí)行。API Key 一律通過環(huán)境變量或密鑰管理服務(wù)注入禁止寫在代碼和日志里。10.2 工具描述就是你的接口文檔模型對工具的理解完全來自description字段。同一個函數(shù)如果描述寫“搜索文檔”模型可能不知道什么時候該用如果描述寫成“當用戶提供關(guān)鍵詞時在本地知識庫 docs 目錄中檢索并返回相關(guān)行文本”模型就會更準確地觸發(fā)它。寫工具描述時盡量包含三個信息工具解決什么問題、什么場景下使用、輸入?yún)?shù)的具體含義。不要惜字如金也不要寫模型用不上的內(nèi)部實現(xiàn)細節(jié)。10.3 引入超時、輪數(shù)與并發(fā)控制Agent 的循環(huán)比普通 HTTP 請求更難以預(yù)估耗時。一個復(fù)雜任務(wù)可能觸發(fā) 3 到 5 次模型調(diào)用單次 10 秒總時長可能超過 30 秒。對外提供服務(wù)時一定要設(shè)置超時上限最好用異步任務(wù)或者流式返回避免請求長時間占用連接。max_iters是防止死循環(huán)的最后防線建議按業(yè)務(wù)復(fù)雜度調(diào)整。簡單問答 3 輪足夠復(fù)雜任務(wù)可以放寬到 8 輪。另外要考慮并發(fā)當多個用戶同時調(diào)用 Agent 時工具執(zhí)行是否會相互影響那些帶全局狀態(tài)的工具特別容易踩這個問題。10.4 日志與可觀測性Agent 的調(diào)試難度遠高于普通代碼因為它多了一層“模型為什么這樣決策”的不確定性。建議在代碼里把每一輪的 assistant 回復(fù)、工具調(diào)用、工具結(jié)果都記錄下來至少包含用戶請求 ID模型名稱推理輪次工具調(diào)用名稱和參數(shù)工具執(zhí)行耗時和結(jié)果有了這些日志當線上回答表現(xiàn)異常時你才能判斷是模型決策錯誤、工具結(jié)果錯誤還是上游數(shù)據(jù)問題。簡單項目可以用 print 或 logging 輸出生產(chǎn)環(huán)境建議接入可觀測平臺。10.5 用一組黃金測試集做回歸模型不是確定性代碼同一個問題在不同時間可能得到不同回答。為了保證業(yè)務(wù)穩(wěn)定可以準備一組“黃金測試用例”覆蓋每個工具的核心場景和邊界場景。每次修改工具描述、替換模型或調(diào)整 Prompt 時都用同一組用例跑一遍回歸。例如本文項目至少應(yīng)該覆蓋這些測試python agent_core.py EOF 現(xiàn)在幾點了 計算 100/8 的結(jié)果 搜索文檔中關(guān)于模型的內(nèi)容 EOF把輸出人工確認一遍再考慮發(fā)布。這種方式成本很低但能攔住大部分明顯的劣化。11. 總結(jié)與學習路線圖現(xiàn)在回到標題里的問題AI Agent 到底該怎么學怎么實戰(zhàn)這篇文章給出的答案是先別急著追新框架先理解 Agent 的底層運行邏輯。你通過tools.py學會了工具設(shè)計和注冊通過agent_core.py學會了 ReAct 循環(huán)和 Function Calling 的消息組織通過main.py學會了把 Agent 變成可調(diào)用的服務(wù)。這三件事本質(zhì)上就是 2026 年大多數(shù) Agent 崗位要求的核心能力。下一步可以按這個路線繼續(xù)深入第一步把本文的項目擴展到自己熟悉的領(lǐng)域。如果你是后端開發(fā)可以把 safe_calc 換成訂單查詢接口如果你是測試開發(fā)可以把 search_docs 換成缺陷庫檢索。替換工具的過程就是對 Agent 理解加深的過程。第二步復(fù)用框架但讀懂源碼。當你跑通手寫版本后再去看 LangChain 的 AgentExecutor、LangGraph 的 StateGraph、Spring AI 的 Tool Calling就不會被包裝層迷惑。它們解決的核心問題和本文的循環(huán)本質(zhì)上是一致的只是把可復(fù)用性、可觀測性和復(fù)雜狀態(tài)管理做得更完善。第三步補上記憶與規(guī)劃能力。手寫版只用了短期對話上下文真實項目往往需要向量庫存儲歷史知識需要任務(wù)分解流程處理復(fù)雜問題。你可以從例如向量檢索入門再嘗試多 Agent 協(xié)作模式。第四步準備面試時把“運行邏輯”講透。面試官問到 Agent 時你可以直接畫出這段循環(huán)模型通過 tools 描述感知可用工具在推理中決定是否調(diào)用工具代碼執(zhí)行工具并把結(jié)果回填上下文模型再基于新上下文繼續(xù)推理或生成最終答案。這條鏈路講清楚了比背十個名詞都管用。最后提醒一件事Agent 工具不是越多越好而是越收斂越好。真正可用的 Agent背后一定有一套清晰的工具邊界、完善的日志鏈路和嚴格的人工審核機制。這也是從“能跑 demo”到“敢上生產(chǎn)”之間最需要補的課。