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