工具以名稱、說明與參數格式約定請求,再用同一個 id 對回結果
深讀 L2 912 字 2 分鐘 v2.0.0 更新 2026-11-16
工具對模型來說,是名稱、說明與參數格式的約定。模型外圍負責迴圈與工具執行的程式,稱為 harness。模型依說明選工具,harness 依名稱執行,請求與結果用相同的 id 配對。
先把工具定義送給模型
在 Agent Loop 的每次模型請求中,工具定義都會一起送出。模型讀得到的介面是名稱、說明與參數格式,因此說明必須讓模型判斷何時該選這個工具。
參數格式用 JSON Schema 描述,也就是規定輸入格式的描述方式。模型選定工具後,輸出工具請求,內容包含 id、工具名稱與參數;此時還沒有執行工具。
不同 API 使用不同的訊息名稱。Anthropic 使用 tool_use 與 tool_result,OpenAI 使用 function_call 與 function_call_output,Gemini 使用 functionCall 與 functionResponse。
從請求走到函式,再送回結果
harness 收到請求後,先依參數格式檢查 input。工具表則把每個名稱對應到說明、參數格式與執行函式,供 run_tool 查找。
以圖中的讀檔流程為例,harness 呼叫 read_file(path),工具回傳檔案文字。harness 再把文字包成工具結果,附上原請求的 id,送回模型。
模型輸出工具請求:一個 id、工具名稱與參數。
唯讀請求可以同時執行,改動請求依序執行
一則模型回覆可以帶多份工具請求。安排執行順序時,唯讀呼叫可以同時執行,會改動資料的呼叫則依序執行。
工具說明與功能區分決定模型能否選對
替常用指令寫工具定義時,先寫名稱、說明與參數格式,再只讀名稱與說明,判斷用途是否清楚。
工具集合也會影響選擇。讀檔、寫檔、改檔與執行指令就能組成 coding agent;功能重疊的工具會讓模型難以選擇。
失敗也要送回對應的結果
每份工具請求都必須有結果,包含執行失敗的請求。少了一份結果,多數 API 會拒絕下一個請求。
分派函式用 TOOLS.get(call.name) 查工具表,查不到就回傳帶同一個 id 的錯誤結果:result(call.id, "unknown tool", error=True)。
若函式執行時拋出例外,示意程式會把 str(e) 放入錯誤結果。不過,錯誤文字還需要寫明原因與下一步,模型讀到後才有依據自行修正。
下圖示範工具表與 run_tool 如何分派請求,並處理成功、名稱不存在與執行例外的結果。
說明與參數格式送給模型。函式留在 harness,模型看不到。
結果內容不能變成使用者要求
工具成功執行,不代表回傳內容可信。網頁與檔案可能夾帶指令,這些文字只能放在工具結果中,不能當成使用者的要求。
一次請求送給模型的全部內容稱為 context。工具結果與使用者要求在 context 裡都是文字,所以結果裡的指令可能被模型照做;把指令藏進模型會讀到的內容,就是 prompt injection。
來源
- Handle tool calls Claude API docs
- Parallel tool use Claude API docs
- Writing effective tools for AI agents Anthropic
- What I learned building an opinionated and minimal coding agent Mario Zechner
- Agentic Coding Recommendations Armin Ronacher
- Function calling OpenAI API docs
- Function calling Gemini API docs