工具呼叫是 Agent 與真實系統之間的邊界。工具越多,越應將名稱、參數、權限、逾時和錯誤編成穩定契約,而不是依賴提示詞中的自然語言約定。
核心概念
將工具分為唯讀、可寫入和高風險三類。唯讀工具可以自動執行;可寫入工具需要冪等鍵;高風險工具必須回傳待確認狀態。錯誤要區分輸入錯誤、權限錯誤、依賴暫時不可用和業務拒絕。
from dataclasses import dataclass
@dataclass(frozen=True)
class SearchArgs:
query: str
limit: int = 10
def validate(args: SearchArgs) -> None:
if not args.query or len(args.query) > 120:
raise ValueError('invalid query')
if not 1 <= args.limit <= 50:
raise ValueError('invalid limit')
def tool_result(ok: bool, code: str, data: dict | None = None) -> dict:
return {'ok': ok, 'code': code, 'data': data}
操作步驟
- 為每個工具撰寫版本化 schema,明確必填欄位與最大長度。
- 將 schema 驗證放在解析模型輸出之後、實際呼叫之前。
- 為寫入操作計算冪等鍵,重複請求回傳第一次結果,不重複執行副作用。
- 把工具錯誤映射成模型可理解的短代碼,詳細堆疊只留在受限日誌。
適用情境
適用於 CRM 查詢、庫存讀取、內部知識搜尋和需要審批的流程。
常見問題
schema 變更如何相容? 新增選填欄位;重大變更使用新的工具名稱或版本。
工具逾時怎麼辦? 回傳明確的 temporary_unavailable,並限制重試次數。
所有錯誤都要交給模型嗎? 只回傳必要資訊,不能洩露權限和內部路徑。
官方參考
OpenAI Function Calling;OpenAI Structured Outputs。
最後核對日期:2026-11-16。版本與介面請以連結的官方資料為準。
