04 · Agent 框架與工具呼叫

來源:本機技能沉澱(無單一原始文件;以官方文件與實務經驗綜合) 網路充實:2026-11-12(MCP 規格 2026-07-28 的 transport 變更、OpenAI Agents SDK/LangGraph/Pydantic AI/CrewAI 現況與版本)

一、tool calling 到底怎麼運作

模型不會「執行程式」,只輸出結構化物件:

  1. 工具清單(name、description、JSON Schema)放進 prompt。
  2. 模型回傳 tool_calls(可能一次多個,平行呼叫)。
  3. 你的程式執行,把結果以 tool 訊息塞回對話。
  4. 模型再決定:繼續呼叫、或給最終答案。

實務要點:

  • 錯誤也要回傳給模型,不要拋例外中斷。格式化成 {"error": "...", "retryable": true},模型多半能自己修參數。
  • 平行呼叫要處理部分失敗,並保證工具 idempotent(重試不重複下單)。
  • 參數驗證(Pydantic/Zod)擋在執行前,比事後修 prompt 有效得多。
  • 工具超過 15–20 個,模型選錯率明顯上升;先分類,再用「選單工具」兩段式檢索。

二、框架比較:先問「你需要什麼」

框架 核心抽象 何時選
原生 SDK 自己寫 while 迴圈 單一供應商、工具 <10 個
OpenAI Agents SDK Agents/Handoffs/Guardrails OpenAI 為主,要小而完整
LangGraph 節點+邊+state+checkpointer 需明確狀態機、可回放、人為中斷
Pydantic AI 型別化 Agent、依賴注入 Python 團隊、要強驗證與可換模型
CrewAI 角色/任務/Crew+Flow 流程真能拆成角色分工
Google ADK 圖工作流+A2A GCP/Gemini 生態

什麼時候不要用框架:單一 agent、三五個工具、無持久化需求。此時框架帶來的是抽象稅——出錯時要穿透三層才知道模型收到什麼。先用 200 行原生程式跑通,再決定是否引入。

三、三種推理模式的差異

模式 行為 適用 風險
ReAct 想一步→做一步→看結果 探索型、結果不可預測 步數膨脹、繞圈
Plan-and-execute 先產出計畫再逐步執行 步驟可預先拆解 計畫錯就一路錯
Reflection 產出後自我批評再修 寫作、程式碼、格式要求高 成本翻倍、可能愈改愈差

多數系統是 ReAct 為骨幹+一次 reflection,而不是全部疊上。reflection 要有外部訊號(測試通過、schema 驗證)才有意義;純靠模型自評經常無效。

四、記憶:多數時候你不該給

類型 實作 注意
短期 context 內的訊息 最可靠,成本隨輪數成長
摘要式 舊對話壓成摘要 會丟細節,錯誤不可逆
長期向量 互動寫進向量庫 檢索不準等於注入雜訊
結構化 KV/資料庫 最可控,優先選

原則:能寫進資料庫的就不要放進向量記憶。記憶要有寫入策略(什麼值得記)、讀取策略(何時檢索)、刪除機制(使用者要求遺忘)。缺這三者,記憶只是把錯誤長期化。

五、MCP:工具生態的共通介面

MCP 用 JSON-RPC 2.0,三種 primitive:tools(模型可呼叫,有副作用)、resources(可讀資料)、prompts(使用者可選的範本工作流)。

Transport 機制 場合
stdio 客戶端啟動子程序,逐行 JSON 本機、單人、CLI 工具
Streamable HTTP 單一 endpoint、每訊息一個 POST、可回 SSE 遠端、多客戶端、共享服務

2026-07-28 版移除 protocol 層 session 與 GET 串流,改以 subscriptions/listen 訂閱變更。一定要釘版本,舊教學的 session 寫法已不適用。

六、可靠度:四個必須的護欄

  1. 輸入/輸出驗證:工具參數用 schema 擋;最終答案也要檢查(例如必須含引用)。
  2. 步數與成本上限:max_steps(建議 8–15)、token 預算、timeout。沒有上限的 agent 一定會在某天爆帳。
  3. retry 與 idempotency:只重試可重試的錯誤(429、5xx、schema 錯);寫入型工具帶 idempotency key。
  4. human-in-the-loop:付款、刪除、對外發信暫停等核可,並把暫停狀態序列化,才能重啟續跑。

可觀測性不是選配:每次 run 要能還原「模型看到什麼、回了什麼、工具做了什麼」。沒有 trace 只能重寫,無法除錯。

七、四個反模式

  • 多 agent 過度設計:一個 agent 能做好的事拆成五個角色,換來溝通成本與不可預測性。
  • 工具描述寫太爛:"do stuff" 等於沒有。要寫何時該用、何時不該用、參數格式、回傳長相。
  • 沒有限制步數:模型會禮貌地永無止境地「再確認一次」。
  • 工具結果原封不動塞回 context:一個 API 回 40 KB JSON,兩輪就爆。先裁剪、只留必要欄位。

實務檢查清單

  • [ ] 每個工具都有 schema、範例、與「不要用」的說明
  • [ ] 工具錯誤回傳結構化訊息,而不是拋例外
  • [ ] 設 max_steps、token 上限、timeout 三件套
  • [ ] 寫入型操作具 idempotency key
  • [ ] 高風險動作接 human-in-the-loop,狀態可序列化
  • [ ] 每次 run 有完整 trace(prompt/tool/result/latency)
  • [ ] MCP server 釘住 protocol 版本,並驗證 Origin header

常見誤解

  • 「agent 會自己規劃,所以不用設計流程」:模型負責決策,流程與護欄仍要人寫。
  • 「框架越重越專業」:抽象層越厚,除錯越貴;多數產品只需要一個迴圈。
  • 「記憶越多越貼心」:錯的記憶比沒有記憶更傷害體驗。
  • 「多 agent 比較強」:目前沒有獨立證據顯示某種多 agent 設計穩定勝過單 agent。
  • 「tool calling 是模型在執行程式」:執行永遠在你的程式碼裡,那是信任邊界。

← 回首頁