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