04 · Agent 框架與工具呼叫
來源:本機技能沉澱(無單一原始文件;以官方文件與實務經驗綜合) 網路充實:2026-11-12(MCP 規格 2026-07-28 的 transport 變更、OpenAI Agents SDK/LangGraph/Pydantic AI/CrewAI 現況與版本)
一、tool calling 到底怎麼運作
模型不會「執行程式」,只輸出結構化物件:
- 工具清單(name、description、JSON Schema)放進 prompt。
- 模型回傳
tool_calls(可能一次多個,平行呼叫)。 - 你的程式執行,把結果以 tool 訊息塞回對話。
- 模型再決定:繼續呼叫、或給最終答案。
實務要點:
- 錯誤也要回傳給模型,不要拋例外中斷。格式化成
{"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 寫法已不適用。
六、可靠度:四個必須的護欄
- 輸入/輸出驗證:工具參數用 schema 擋;最終答案也要檢查(例如必須含引用)。
- 步數與成本上限:
max_steps(建議 8–15)、token 預算、timeout。沒有上限的 agent 一定會在某天爆帳。 - retry 與 idempotency:只重試可重試的錯誤(429、5xx、schema 錯);寫入型工具帶 idempotency key。
- 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 是模型在執行程式」:執行永遠在你的程式碼裡,那是信任邊界。