← 返回學習路線
章節 · 已發布

工具呼叫與函式契約:讓 Agent 可控

設計工具 schema、錯誤回應與冪等策略,減少參數漂移與副作用。

來源: knowledge/p24-b/collection_8023a8d754046b6c2ae7220f/tutorials/agent-tool-contracts-and-function-calling.mdAI Agent 工程實踐
本章閱讀進度 0%學習路線進度 0% · 0/10 已完成章節繼續學習路線 →

工具呼叫是 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}

操作步驟

  1. 為每個工具撰寫版本化 schema,明確必填欄位與最大長度。
  2. 將 schema 驗證放在解析模型輸出之後、實際呼叫之前。
  3. 為寫入操作計算冪等鍵,重複請求回傳第一次結果,不重複執行副作用。
  4. 把工具錯誤映射成模型可理解的短代碼,詳細堆疊只留在受限日誌。

適用情境

適用於 CRM 查詢、庫存讀取、內部知識搜尋和需要審批的流程。

常見問題

schema 變更如何相容? 新增選填欄位;重大變更使用新的工具名稱或版本。

工具逾時怎麼辦? 回傳明確的 temporary_unavailable,並限制重試次數。

所有錯誤都要交給模型嗎? 只回傳必要資訊,不能洩露權限和內部路徑。

官方參考

OpenAI Function Calling;OpenAI Structured Outputs。

最後核對日期:2026-11-16。版本與介面請以連結的官方資料為準。

相關實戰案例

知識實戰:可稽核的工單分流 Agent知識實戰:帶人工審批的部署建議 Agent知識實戰:Agent 失敗後的證據包與人工接管

延伸閱讀

知識AI Agent:從基礎概念到實際應用知識AI 自動化工作流程設計與實踐知識結構化輸出與工具契約:讓 Agent 動作可驗證
產品中心 Demo · V0.3