工具以名稱、說明與參數格式約定請求,再用同一個 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。

來源

讀完之後

HarnessLLM迴圈工具context快取KV接手協定權限沙箱層注入子 agent實作評測