用綜合實踐：用 TaoToken 統(tǒng)一 Key 打通 Agent 工具注冊表)
1. 從單工具到工具注冊表Agent 工具調(diào)用綜合實踐要解決什么如果你已經(jīng)跟著前幾課把聯(lián)網(wǎng)搜索、本地文件讀寫這些單點工具跑通了大概率會遇到一個很具體的瓶頸每個工具都寫死在一個if/else里Agent 只能按固定順序調(diào)用稍微復(fù)雜一點的任務(wù)就卡住。比如「先在我電腦里找一份銷售數(shù)據(jù)再聯(lián)網(wǎng)查行業(yè)增速最后寫一份對比報告」這種需求單工具腳本根本接不住。這一課要解決的核心問題就是把散落的工具收進(jìn)一張工具注冊表讓 LLM 在ReAct 循環(huán)里自己決定「下一步該調(diào)哪個工具、傳什么參數(shù)、拿到結(jié)果后要不要繼續(xù)」。說白了Agent 從「只會用一把錘子」升級成「有一個工具箱還能自己挑工具」。工具調(diào)用Tool Calling / Function Calling是 LLM Agent 最核心的能力之一。它讓模型不再只是輸出文字而是能輸出結(jié)構(gòu)化的調(diào)用意圖由外部執(zhí)行器去真正干活。ReAct 范式則提供了「推理—行動—觀察」的循環(huán)骨架模型先想一步再動手再看結(jié)果再想下一步。把這兩者結(jié)合再加上一個統(tǒng)一的工具注冊表你就能搭出一個能處理多步任務(wù)的 Agent。適合誰看已經(jīng)寫過至少一個工具函數(shù)、懂基本 Python 和 OpenAI 兼容接口調(diào)用、想從「玩具 demo」邁向「能編排多工具」的開發(fā)者。整篇會交付三樣可復(fù)制的東西——工具注冊表配置、ReAct 提示模板、端到端驗證步驟跟著敲一遍就能跑通完整鏈路。我試過把這套結(jié)構(gòu)用在個人助理場景里最大的感受是工具注冊表一旦標(biāo)準(zhǔn)化新增工具的成本幾乎為零你只需要寫一個函數(shù)加一條 SchemaAgent 立刻就能用上。下面從統(tǒng)一 Key 接入開始講。2. TaoToken 統(tǒng)一 Key 接入一個 API 通道管住所有工具調(diào)用多工具 Agent 有個容易被忽略的坑工具一多模型調(diào)用次數(shù)暴漲如果你每個工具背后都接不同的模型服務(wù)商、不同的 Key管理起來會非常亂。更現(xiàn)實的問題是ReAct 循環(huán)里每一輪都要請求一次模型延遲和穩(wěn)定性直接決定 Agent 能不能用。我的做法是用TaoToken 統(tǒng)一 Key作為唯一的模型調(diào)用通道。它提供 OpenAI 兼容的接口意味著你現(xiàn)有的openaiSDK 代碼幾乎不用改只需要把base_url和api_key換掉。這樣工具注冊表里的所有工具、ReAct 循環(huán)里的每一次決策都走同一個通道Key 管理、額度查看、模型切換都在一處完成。先拿到你的 Key進(jìn)入控制臺創(chuàng)建 API Key路徑是console下的api-keys頁面。創(chuàng)建后復(fù)制那串以sk-開頭的字符串存到環(huán)境變量里別硬編碼進(jìn)代碼。# .env 文件 TAOTOKEN_API_KEYsk-你的key TAOTOKEN_BASE_URLhttps://taotoken.net/api這里有個細(xì)節(jié)要注意base_url填https://taotoken.net/api不要自己加/v1OpenAI SDK 會自動拼接路徑。很多人第一次接入報 404就是因為多寫了一段。為什么強(qiáng)調(diào)「統(tǒng)一」因為 ReAct 循環(huán)里模型會被調(diào)用很多次如果每次調(diào)用都換服務(wù)商你的調(diào)試成本會指數(shù)級上升。統(tǒng)一通道之后你只需要在一個地方排查問題是 Key 失效、模型名寫錯還是網(wǎng)絡(luò)超時。工具本身的邏輯反而變得純粹——它只管執(zhí)行不管模型怎么調(diào)。如果你打算長期跑編碼類或 Agent 類任務(wù)可以關(guān)注一下 Coding Plan它更適合高頻、長時間的調(diào)用場景比按次計費更劃算。但這一課我們先聚焦把鏈路跑通計費方式后面再優(yōu)化。3. 可復(fù)制的工具注冊表配置與 ReAct 提示模板這一節(jié)是全文的技術(shù)核心給你可以直接抄的配置。整個 Agent 由四部分組成工具注冊表、ReAct 提示模板、執(zhí)行器、主循環(huán)。我們逐個來。3.1 工具注冊表用 JSON Schema 描述每個工具工具注冊表的本質(zhì)是一張「工具清單」每個工具包含三樣?xùn)|西名字、功能描述、參數(shù) Schema。LLM 就是靠這份清單來決定調(diào)哪個工具的。先定義兩個基礎(chǔ)工具一個聯(lián)網(wǎng)搜索、一個本地文件讀取。# tool_registry.py import json def web_search(query: str) - dict: 模擬聯(lián)網(wǎng)搜索實際項目替換為真實搜索 API return {query: query, result: f關(guān)于「{query}」的行業(yè)數(shù)據(jù)2024 年增長率約 18%} def read_file(path: str) - dict: 讀取本地文件內(nèi)容 try: with open(path, r, encodingutf-8) as f: return {path: path, content: f.read()} except FileNotFoundError: return {path: path, error: 文件不存在} # 工具注冊表名稱 - {函數(shù), Schema} TOOL_REGISTRY { web_search: { func: web_search, schema: { type: function, function: { name: web_search, description: 聯(lián)網(wǎng)搜索實時信息適合查詢行業(yè)數(shù)據(jù)、最新動態(tài), parameters: { type: object, properties: { query: {type: string, description: 搜索關(guān)鍵詞} }, required: [query] } } } }, read_file: { func: read_file, schema: { type: function, function: { name: read_file, description: 讀取本地文件內(nèi)容適合處理用戶電腦里的文檔, parameters: { type: object, properties: { path: {type: string, description: 文件路徑} }, required: [path] } } } } } def get_tool_schemas(): return [t[schema] for t in TOOL_REGISTRY.values()] def execute_tool(name: str, args: dict) - str: if name not in TOOL_REGISTRY: return json.dumps({error: f未知工具{name}}, ensure_asciiFalse) try: result TOOL_REGISTRY[name][func](**args) return json.dumps(result, ensure_asciiFalse) except Exception as e: return json.dumps({error: str(e)}, ensure_asciiFalse)這份注冊表的關(guān)鍵設(shè)計是Schema 和函數(shù)放在一起。新增工具時你只改一個字典主循環(huán)完全不用動。description字段一定要寫清楚「什么時候用」這是 LLM 選工具的主要依據(jù)寫得越具體選錯工具的概率越低。3.2 ReAct 提示模板讓模型先推理再行動ReAct 的精髓在于把「思考」顯式化。我們不直接讓模型輸出工具調(diào)用而是先讓它用一段文字說明「我現(xiàn)在要做什么、為什么」再輸出結(jié)構(gòu)化的調(diào)用。這樣調(diào)試時你能看到它的決策鏈路。REACT_SYSTEM_PROMPT 你是一個會使用工具的智能助手遵循 ReAct 循環(huán)工作。 每一輪你必須按以下格式輸出 Thought: 分析當(dāng)前已知信息說明下一步需要做什么、為什么。 Action: 如果需要調(diào)用工具輸出工具名和參數(shù)如果信息已足夠輸出 Final Answer。 可用工具清單 {tool_schemas} 規(guī)則 1. 一次只調(diào)用一個工具拿到結(jié)果后再決定下一步。 2. 優(yōu)先用本地文件工具處理用戶本地數(shù)據(jù)用聯(lián)網(wǎng)搜索補(bǔ)充外部信息。 3. 如果工具返回錯誤分析原因后決定是否換工具或直接回答。 4. 信息足夠時用 Final Answer 給出整合后的結(jié)論。 把{tool_schemas}用json.dumps(get_tool_schemas(), ensure_asciiFalse)填進(jìn)去。這個模板的作用是給模型一個穩(wěn)定的輸出結(jié)構(gòu)避免它東一句西一句。實測下來加了 Thought 步驟之后多步任務(wù)的完成率明顯提升因為模型被迫先規(guī)劃再動手。3.3 主循環(huán)串起決策與執(zhí)行主循環(huán)負(fù)責(zé)把模型輸出解析成工具調(diào)用執(zhí)行后再把結(jié)果喂回去直到模型給出 Final Answer 或達(dá)到最大步數(shù)。# agent.py import os, json, re from openai import OpenAI from dotenv import load_dotenv from tool_registry import get_tool_schemas, execute_tool load_dotenv() client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL) ) def run_agent(user_query: str, max_steps: int 6): system REACT_SYSTEM_PROMPT.format( tool_schemasjson.dumps(get_tool_schemas(), ensure_asciiFalse) ) messages [ {role: system, content: system}, {role: user, content: user_query} ] for step in range(max_steps): resp client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolsget_tool_schemas(), tool_choiceauto ) msg resp.choices[0].message messages.append(msg) if not msg.tool_calls: return msg.content for call in msg.tool_calls: name call.function.name args json.loads(call.function.arguments) print(f[Step {step1}] 調(diào)用工具 {name}參數(shù) {args}) result execute_tool(name, args) print(f[Step {step1}] 返回 {result}) messages.append({ role: tool, tool_call_id: call.id, content: result }) return 達(dá)到最大步數(shù)任務(wù)未完成注意tool_choiceauto讓模型自己決定要不要調(diào)工具max_steps是防止死循環(huán)的保險絲。工具返回的消息必須帶tool_call_id否則接口會報錯這是很多人第一次寫會漏的地方。4. 端到端驗證跑通一次多工具編排配置寫完了現(xiàn)在驗證。準(zhǔn)備一個測試文件然后提一個需要「本地文件 聯(lián)網(wǎng)搜索」協(xié)同的問題。mkdir -p ./agent_files echo 2023 年公司銷售額 500 萬同比增長 12% ./agent_files/sales.txt然后運行if __name__ __main__: query 讀取 ./agent_files/sales.txt 的內(nèi)容再聯(lián)網(wǎng)查一下 2024 年行業(yè)平均增長率對比分析我們是否達(dá)標(biāo) print(run_agent(query))預(yù)期你會看到類似這樣的過程輸出[Step 1] 調(diào)用工具 read_file參數(shù) {path: ./agent_files/sales.txt} [Step 1] 返回 {path: ./agent_files/sales.txt, content: 2023 年公司銷售額 500 萬同比增長 12%} [Step 2] 調(diào)用工具 web_search參數(shù) {query: 2024 年行業(yè)平均增長率} [Step 2] 返回 {query: 2024 年行業(yè)平均增長率, result: 關(guān)于「2024 年行業(yè)平均增長率」的行業(yè)數(shù)據(jù)2024 年增長率約 18%}最后模型會輸出一段整合結(jié)論大意是「公司 2023 年增長 12%低于行業(yè)平均 18%存在差距」。到這里一次完整的 ReAct 多工具編排就跑通了。驗證時重點看三件事第一模型是否先讀本地文件再聯(lián)網(wǎng)順序合理第二每次工具調(diào)用的參數(shù)是否正確解析第三最終回答是否同時用到了兩個工具的結(jié)果。如果最終回答只提了文件內(nèi)容、沒提搜索數(shù)據(jù)說明結(jié)果整合環(huán)節(jié)出了問題通常是工具返回的 JSON 沒被正確塞回對話歷史。想快速驗證模型本身是否正?？梢韵扔媚Ｐ蛯υ掜撁姘l(fā)一條簡單消息確認(rèn) Key 和通道沒問題再回來跑 Agent。這樣能把「模型通道問題」和「Agent 邏輯問題」分開排查。5. 常見報錯排查401、local proxy failed、reading choices 怎么解多工具 Agent 的報錯大多集中在接入層和解析層下面按真實遇到的順序列出來。401 Unauthorized / invalid api key九成是 Key 沒讀到或?qū)戝e。先確認(rèn).env里的TAOTOKEN_API_KEY沒有多余空格再確認(rèn)load_dotenv()在OpenAI()初始化之前執(zhí)行。如果你把 Key 寫進(jìn)了系統(tǒng)環(huán)境變量又同時有.env可能讀到舊值建議只保留一處。local proxy failed / connection error這類報錯通常是base_url寫錯或網(wǎng)絡(luò)環(huán)境問題。檢查base_url是否為https://taotoken.net/api不要帶/v1也不要帶結(jié)尾斜杠。如果公司網(wǎng)絡(luò)有額外限制換一個網(wǎng)絡(luò)環(huán)境再試。reading choices of undefined這個報錯說明resp.choices是空的常見原因是模型名寫錯接口返回了錯誤結(jié)構(gòu)但代碼直接取choices[0]。把model換成通道支持的模型 ID并在取choices前加一層判斷if not resp.choices: raise RuntimeError(f接口返回異常{resp})tool_calls 解析失敗 / arguments 不是合法 JSON模型偶爾會輸出帶注釋的 JSON。穩(wěn)妥做法是用json.loads包一層 try失敗時把原始字符串作為錯誤信息回傳給模型讓它重試try: args json.loads(call.function.arguments) except json.JSONDecodeError: args {} result json.dumps({error: 參數(shù)解析失敗請重新生成合法 JSON}, ensure_asciiFalse)OAuth / 認(rèn)證方式?jīng)_突如果你之前用過某些 CLI 工具的 OAuth 登錄環(huán)境里可能殘留了舊的認(rèn)證配置導(dǎo)致 SDK 走了錯誤的認(rèn)證路徑。清理掉相關(guān)環(huán)境變量只保留TAOTOKEN_API_KEY這一條通道。工具被反復(fù)調(diào)用、停不下來這是 ReAct 循環(huán)的典型問題通常是max_steps設(shè)太大或者工具返回的錯誤信息讓模型誤以為「再試一次就好」。把max_steps控制在 5 到 8 之間并在工具返回錯誤時明確告訴模型「此路不通請換方案」。排查時記住一個原則先隔離通道再隔離工具最后看編排邏輯。用模型對話頁面確認(rèn)通道正常單獨調(diào)用每個工具函數(shù)確認(rèn)工具正常剩下的問題一定在 ReAct 循環(huán)的解析和消息拼接上。6. 把工具注冊表用起來從跑通到長期可用鏈路跑通只是起點。真正讓這套結(jié)構(gòu)產(chǎn)生價值是把它變成你日常能復(fù)用的基礎(chǔ)設(shè)施。這里給幾個我踩過坑之后總結(jié)的實用建議。第一工具描述要當(dāng)成 Prompt 來寫。description不是注釋是給模型看的說明書。寫「讀取文件」不如寫「讀取用戶本地指定路徑的文本文件適合處理 CSV、TXT、Markdown不支持二進(jìn)制」。描述越精確模型選錯工具的概率越低。第二給工具加白名單和超時。文件工具一定要限制可訪問目錄搜索工具一定要設(shè)超時。Agent 自己決定參數(shù)意味著它可能傳進(jìn)來任何路徑安全邊界必須由執(zhí)行器兜住不能指望模型自覺。第三把 ReAct 的中間過程落盤。每次運行的 Thought、Action、Observation 都寫進(jìn)日志文件出問題時能完整回放。多工具編排的 bug 往往藏在第三步、第四步?jīng)]有日志根本定位不到。第四新增工具時先單獨測再進(jìn)注冊表。工具函數(shù)本身跑不通放進(jìn)注冊表只會讓 Agent 的報錯更難懂。先用一個簡單腳本單獨調(diào)用確認(rèn)輸入輸出符合預(yù)期再補(bǔ) Schema。如果你打算把這套 Agent 長期跑在編碼或自動化任務(wù)上可以了解一下 Coding Plan它針對高頻調(diào)用場景做了優(yōu)化適合把工具注冊表擴(kuò)展成幾十個工具之后的使用強(qiáng)度。接入文檔里有完整的參數(shù)說明和示例遇到通道層面的問題可以直接對照排查。工具注冊表這套結(jié)構(gòu)的真正威力在于它把「Agent 能做什么」和「Agent 怎么決策」解耦了。你負(fù)責(zé)往注冊表里加工具模型負(fù)責(zé)在 ReAct 循環(huán)里挑工具兩邊互不干擾。今天你跑通的是兩個工具明天加到十個、二十個主循環(huán)一行都不用改。這才是 Agent 區(qū)別于普通 LLM 應(yīng)用的地方——它不只是會說話而是有一個能持續(xù)擴(kuò)展的工具箱并且知道什么時候該伸手去拿哪一件。 第 7 課__工具調(diào)用綜合實踐：用 TaoToken 統(tǒng)一 Key 打通 Agent 工具注冊表
1. 從單工具到工具注冊表Agent 工具調(diào)用綜合實踐要解決什么如果你已經(jīng)跟著前幾課把聯(lián)網(wǎng)搜索、本地文件讀寫這些單點工具跑通了大概率會遇到一個很具體的瓶頸每個工具都寫死在一個if/else里Agent 只能按固定順序調(diào)用稍微復(fù)雜一點的任務(wù)就卡住。比如「先在我電腦里找一份銷售數(shù)據(jù)再聯(lián)網(wǎng)查行業(yè)增速最后寫一份對比報告」這種需求單工具腳本根本接不住。這一課要解決的核心問題就是把散落的工具收進(jìn)一張工具注冊表讓 LLM 在ReAct 循環(huán)里自己決定「下一步該調(diào)哪個工具、傳什么參數(shù)、拿到結(jié)果后要不要繼續(xù)」。說白了Agent 從「只會用一把錘子」升級成「有一個工具箱還能自己挑工具」。工具調(diào)用Tool Calling / Function Calling是 LLM Agent 最核心的能力之一。它讓模型不再只是輸出文字而是能輸出結(jié)構(gòu)化的調(diào)用意圖由外部執(zhí)行器去真正干活。ReAct 范式則提供了「推理—行動—觀察」的循環(huán)骨架模型先想一步再動手再看結(jié)果再想下一步。把這兩者結(jié)合再加上一個統(tǒng)一的工具注冊表你就能搭出一個能處理多步任務(wù)的 Agent。適合誰看已經(jīng)寫過至少一個工具函數(shù)、懂基本 Python 和 OpenAI 兼容接口調(diào)用、想從「玩具 demo」邁向「能編排多工具」的開發(fā)者。整篇會交付三樣可復(fù)制的東西——工具注冊表配置、ReAct 提示模板、端到端驗證步驟跟著敲一遍就能跑通完整鏈路。我試過把這套結(jié)構(gòu)用在個人助理場景里最大的感受是工具注冊表一旦標(biāo)準(zhǔn)化新增工具的成本幾乎為零你只需要寫一個函數(shù)加一條 SchemaAgent 立刻就能用上。下面從統(tǒng)一 Key 接入開始講。2. TaoToken 統(tǒng)一 Key 接入一個 API 通道管住所有工具調(diào)用多工具 Agent 有個容易被忽略的坑工具一多模型調(diào)用次數(shù)暴漲如果你每個工具背后都接不同的模型服務(wù)商、不同的 Key管理起來會非常亂。更現(xiàn)實的問題是ReAct 循環(huán)里每一輪都要請求一次模型延遲和穩(wěn)定性直接決定 Agent 能不能用。我的做法是用TaoToken 統(tǒng)一 Key作為唯一的模型調(diào)用通道。它提供 OpenAI 兼容的接口意味著你現(xiàn)有的openaiSDK 代碼幾乎不用改只需要把base_url和api_key換掉。這樣工具注冊表里的所有工具、ReAct 循環(huán)里的每一次決策都走同一個通道Key 管理、額度查看、模型切換都在一處完成。先拿到你的 Key進(jìn)入控制臺創(chuàng)建 API Key路徑是console下的api-keys頁面。創(chuàng)建后復(fù)制那串以sk-開頭的字符串存到環(huán)境變量里別硬編碼進(jìn)代碼。# .env 文件 TAOTOKEN_API_KEYsk-你的key TAOTOKEN_BASE_URLhttps://taotoken.net/api這里有個細(xì)節(jié)要注意base_url填https://taotoken.net/api不要自己加/v1OpenAI SDK 會自動拼接路徑。很多人第一次接入報 404就是因為多寫了一段。為什么強(qiáng)調(diào)「統(tǒng)一」因為 ReAct 循環(huán)里模型會被調(diào)用很多次如果每次調(diào)用都換服務(wù)商你的調(diào)試成本會指數(shù)級上升。統(tǒng)一通道之后你只需要在一個地方排查問題是 Key 失效、模型名寫錯還是網(wǎng)絡(luò)超時。工具本身的邏輯反而變得純粹——它只管執(zhí)行不管模型怎么調(diào)。如果你打算長期跑編碼類或 Agent 類任務(wù)可以關(guān)注一下 Coding Plan它更適合高頻、長時間的調(diào)用場景比按次計費更劃算。但這一課我們先聚焦把鏈路跑通計費方式后面再優(yōu)化。3. 可復(fù)制的工具注冊表配置與 ReAct 提示模板這一節(jié)是全文的技術(shù)核心給你可以直接抄的配置。整個 Agent 由四部分組成工具注冊表、ReAct 提示模板、執(zhí)行器、主循環(huán)。我們逐個來。3.1 工具注冊表用 JSON Schema 描述每個工具工具注冊表的本質(zhì)是一張「工具清單」每個工具包含三樣?xùn)|西名字、功能描述、參數(shù) Schema。LLM 就是靠這份清單來決定調(diào)哪個工具的。先定義兩個基礎(chǔ)工具一個聯(lián)網(wǎng)搜索、一個本地文件讀取。# tool_registry.py import json def web_search(query: str) - dict: 模擬聯(lián)網(wǎng)搜索實際項目替換為真實搜索 API return {query: query, result: f關(guān)于「{query}」的行業(yè)數(shù)據(jù)2024 年增長率約 18%} def read_file(path: str) - dict: 讀取本地文件內(nèi)容 try: with open(path, r, encodingutf-8) as f: return {path: path, content: f.read()} except FileNotFoundError: return {path: path, error: 文件不存在} # 工具注冊表名稱 - {函數(shù), Schema} TOOL_REGISTRY { web_search: { func: web_search, schema: { type: function, function: { name: web_search, description: 聯(lián)網(wǎng)搜索實時信息適合查詢行業(yè)數(shù)據(jù)、最新動態(tài), parameters: { type: object, properties: { query: {type: string, description: 搜索關(guān)鍵詞} }, required: [query] } } } }, read_file: { func: read_file, schema: { type: function, function: { name: read_file, description: 讀取本地文件內(nèi)容適合處理用戶電腦里的文檔, parameters: { type: object, properties: { path: {type: string, description: 文件路徑} }, required: [path] } } } } } def get_tool_schemas(): return [t[schema] for t in TOOL_REGISTRY.values()] def execute_tool(name: str, args: dict) - str: if name not in TOOL_REGISTRY: return json.dumps({error: f未知工具{name}}, ensure_asciiFalse) try: result TOOL_REGISTRY[name][func](**args) return json.dumps(result, ensure_asciiFalse) except Exception as e: return json.dumps({error: str(e)}, ensure_asciiFalse)這份注冊表的關(guān)鍵設(shè)計是Schema 和函數(shù)放在一起。新增工具時你只改一個字典主循環(huán)完全不用動。description字段一定要寫清楚「什么時候用」這是 LLM 選工具的主要依據(jù)寫得越具體選錯工具的概率越低。3.2 ReAct 提示模板讓模型先推理再行動ReAct 的精髓在于把「思考」顯式化。我們不直接讓模型輸出工具調(diào)用而是先讓它用一段文字說明「我現(xiàn)在要做什么、為什么」再輸出結(jié)構(gòu)化的調(diào)用。這樣調(diào)試時你能看到它的決策鏈路。REACT_SYSTEM_PROMPT 你是一個會使用工具的智能助手遵循 ReAct 循環(huán)工作。 每一輪你必須按以下格式輸出 Thought: 分析當(dāng)前已知信息說明下一步需要做什么、為什么。 Action: 如果需要調(diào)用工具輸出工具名和參數(shù)如果信息已足夠輸出 Final Answer。 可用工具清單 {tool_schemas} 規(guī)則 1. 一次只調(diào)用一個工具拿到結(jié)果后再決定下一步。 2. 優(yōu)先用本地文件工具處理用戶本地數(shù)據(jù)用聯(lián)網(wǎng)搜索補(bǔ)充外部信息。 3. 如果工具返回錯誤分析原因后決定是否換工具或直接回答。 4. 信息足夠時用 Final Answer 給出整合后的結(jié)論。 把{tool_schemas}用json.dumps(get_tool_schemas(), ensure_asciiFalse)填進(jìn)去。這個模板的作用是給模型一個穩(wěn)定的輸出結(jié)構(gòu)避免它東一句西一句。實測下來加了 Thought 步驟之后多步任務(wù)的完成率明顯提升因為模型被迫先規(guī)劃再動手。3.3 主循環(huán)串起決策與執(zhí)行主循環(huán)負(fù)責(zé)把模型輸出解析成工具調(diào)用執(zhí)行后再把結(jié)果喂回去直到模型給出 Final Answer 或達(dá)到最大步數(shù)。# agent.py import os, json, re from openai import OpenAI from dotenv import load_dotenv from tool_registry import get_tool_schemas, execute_tool load_dotenv() client OpenAI( api_keyos.getenv(TAOTOKEN_API_KEY), base_urlos.getenv(TAOTOKEN_BASE_URL) ) def run_agent(user_query: str, max_steps: int 6): system REACT_SYSTEM_PROMPT.format( tool_schemasjson.dumps(get_tool_schemas(), ensure_asciiFalse) ) messages [ {role: system, content: system}, {role: user, content: user_query} ] for step in range(max_steps): resp client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolsget_tool_schemas(), tool_choiceauto ) msg resp.choices[0].message messages.append(msg) if not msg.tool_calls: return msg.content for call in msg.tool_calls: name call.function.name args json.loads(call.function.arguments) print(f[Step {step1}] 調(diào)用工具 {name}參數(shù) {args}) result execute_tool(name, args) print(f[Step {step1}] 返回 {result}) messages.append({ role: tool, tool_call_id: call.id, content: result }) return 達(dá)到最大步數(shù)任務(wù)未完成注意tool_choiceauto讓模型自己決定要不要調(diào)工具max_steps是防止死循環(huán)的保險絲。工具返回的消息必須帶tool_call_id否則接口會報錯這是很多人第一次寫會漏的地方。4. 端到端驗證跑通一次多工具編排配置寫完了現(xiàn)在驗證。準(zhǔn)備一個測試文件然后提一個需要「本地文件 聯(lián)網(wǎng)搜索」協(xié)同的問題。mkdir -p ./agent_files echo 2023 年公司銷售額 500 萬同比增長 12% ./agent_files/sales.txt然后運行if __name__ __main__: query 讀取 ./agent_files/sales.txt 的內(nèi)容再聯(lián)網(wǎng)查一下 2024 年行業(yè)平均增長率對比分析我們是否達(dá)標(biāo) print(run_agent(query))預(yù)期你會看到類似這樣的過程輸出[Step 1] 調(diào)用工具 read_file參數(shù) {path: ./agent_files/sales.txt} [Step 1] 返回 {path: ./agent_files/sales.txt, content: 2023 年公司銷售額 500 萬同比增長 12%} [Step 2] 調(diào)用工具 web_search參數(shù) {query: 2024 年行業(yè)平均增長率} [Step 2] 返回 {query: 2024 年行業(yè)平均增長率, result: 關(guān)于「2024 年行業(yè)平均增長率」的行業(yè)數(shù)據(jù)2024 年增長率約 18%}最后模型會輸出一段整合結(jié)論大意是「公司 2023 年增長 12%低于行業(yè)平均 18%存在差距」。到這里一次完整的 ReAct 多工具編排就跑通了。驗證時重點看三件事第一模型是否先讀本地文件再聯(lián)網(wǎng)順序合理第二每次工具調(diào)用的參數(shù)是否正確解析第三最終回答是否同時用到了兩個工具的結(jié)果。如果最終回答只提了文件內(nèi)容、沒提搜索數(shù)據(jù)說明結(jié)果整合環(huán)節(jié)出了問題通常是工具返回的 JSON 沒被正確塞回對話歷史。想快速驗證模型本身是否正?？梢韵扔媚Ｐ蛯υ掜撁姘l(fā)一條簡單消息確認(rèn) Key 和通道沒問題再回來跑 Agent。這樣能把「模型通道問題」和「Agent 邏輯問題」分開排查。5. 常見報錯排查401、local proxy failed、reading choices 怎么解多工具 Agent 的報錯大多集中在接入層和解析層下面按真實遇到的順序列出來。401 Unauthorized / invalid api key九成是 Key 沒讀到或?qū)戝e。先確認(rèn).env里的TAOTOKEN_API_KEY沒有多余空格再確認(rèn)load_dotenv()在OpenAI()初始化之前執(zhí)行。如果你把 Key 寫進(jìn)了系統(tǒng)環(huán)境變量又同時有.env可能讀到舊值建議只保留一處。local proxy failed / connection error這類報錯通常是base_url寫錯或網(wǎng)絡(luò)環(huán)境問題。檢查base_url是否為https://taotoken.net/api不要帶/v1也不要帶結(jié)尾斜杠。如果公司網(wǎng)絡(luò)有額外限制換一個網(wǎng)絡(luò)環(huán)境再試。reading choices of undefined這個報錯說明resp.choices是空的常見原因是模型名寫錯接口返回了錯誤結(jié)構(gòu)但代碼直接取choices[0]。把model換成通道支持的模型 ID并在取choices前加一層判斷if not resp.choices: raise RuntimeError(f接口返回異常{resp})tool_calls 解析失敗 / arguments 不是合法 JSON模型偶爾會輸出帶注釋的 JSON。穩(wěn)妥做法是用json.loads包一層 try失敗時把原始字符串作為錯誤信息回傳給模型讓它重試try: args json.loads(call.function.arguments) except json.JSONDecodeError: args {} result json.dumps({error: 參數(shù)解析失敗請重新生成合法 JSON}, ensure_asciiFalse)OAuth / 認(rèn)證方式?jīng)_突如果你之前用過某些 CLI 工具的 OAuth 登錄環(huán)境里可能殘留了舊的認(rèn)證配置導(dǎo)致 SDK 走了錯誤的認(rèn)證路徑。清理掉相關(guān)環(huán)境變量只保留TAOTOKEN_API_KEY這一條通道。工具被反復(fù)調(diào)用、停不下來這是 ReAct 循環(huán)的典型問題通常是max_steps設(shè)太大或者工具返回的錯誤信息讓模型誤以為「再試一次就好」。把max_steps控制在 5 到 8 之間并在工具返回錯誤時明確告訴模型「此路不通請換方案」。排查時記住一個原則先隔離通道再隔離工具最后看編排邏輯。用模型對話頁面確認(rèn)通道正常單獨調(diào)用每個工具函數(shù)確認(rèn)工具正常剩下的問題一定在 ReAct 循環(huán)的解析和消息拼接上。6. 把工具注冊表用起來從跑通到長期可用鏈路跑通只是起點。真正讓這套結(jié)構(gòu)產(chǎn)生價值是把它變成你日常能復(fù)用的基礎(chǔ)設(shè)施。這里給幾個我踩過坑之后總結(jié)的實用建議。第一工具描述要當(dāng)成 Prompt 來寫。description不是注釋是給模型看的說明書。寫「讀取文件」不如寫「讀取用戶本地指定路徑的文本文件適合處理 CSV、TXT、Markdown不支持二進(jìn)制」。描述越精確模型選錯工具的概率越低。第二給工具加白名單和超時。文件工具一定要限制可訪問目錄搜索工具一定要設(shè)超時。Agent 自己決定參數(shù)意味著它可能傳進(jìn)來任何路徑安全邊界必須由執(zhí)行器兜住不能指望模型自覺。第三把 ReAct 的中間過程落盤。每次運行的 Thought、Action、Observation 都寫進(jìn)日志文件出問題時能完整回放。多工具編排的 bug 往往藏在第三步、第四步?jīng)]有日志根本定位不到。第四新增工具時先單獨測再進(jìn)注冊表。工具函數(shù)本身跑不通放進(jìn)注冊表只會讓 Agent 的報錯更難懂。先用一個簡單腳本單獨調(diào)用確認(rèn)輸入輸出符合預(yù)期再補(bǔ) Schema。如果你打算把這套 Agent 長期跑在編碼或自動化任務(wù)上可以了解一下 Coding Plan它針對高頻調(diào)用場景做了優(yōu)化適合把工具注冊表擴(kuò)展成幾十個工具之后的使用強(qiáng)度。接入文檔里有完整的參數(shù)說明和示例遇到通道層面的問題可以直接對照排查。工具注冊表這套結(jié)構(gòu)的真正威力在于它把「Agent 能做什么」和「Agent 怎么決策」解耦了。你負(fù)責(zé)往注冊表里加工具模型負(fù)責(zé)在 ReAct 循環(huán)里挑工具兩邊互不干擾。今天你跑通的是兩個工具明天加到十個、二十個主循環(huán)一行都不用改。這才是 Agent 區(qū)別于普通 LLM 應(yīng)用的地方——它不只是會說話而是有一個能持續(xù)擴(kuò)展的工具箱并且知道什么時候該伸手去拿哪一件。