把產品能力交給 Agent：工具契約、執行計畫與核准流程

把產品原有的查詢與操作能力交給 Agent，不需要重寫所有服務，但需要清楚的工具邊界。模型提出工具呼叫，產品後端確認參數與權限，工具回傳結果，再讓模型決定下一步，這才形成能在產品裡運作的工具迴圈。

「查天氣，幫我排週末行程」包含幾種工作

這句話至少需要地點、時間、天氣資料與行程條件。若已經知道使用者想去臺南，可以省掉一次澄清；若不知道地點，直接搜尋「週末天氣」就可能拿到不相關的城市。

把句子裡出現「天氣」當成必用某工具的規則，只處理了表面觸發。把整句交給 LLM 選工具，則取得一個帶有語意判斷的提案，但還沒回答參數從哪裡來、使用者允許讀什麼、哪些結果必須先完成，以及失敗後哪些工作仍有意義。

因此，選工具與執行工具要拆開。選擇器提出候選與理由，執行器才負責驗證與執行。模型不能因為認為某工具合適，就替呼叫者增加權限。

定義工具契約與權限

工具註冊表要提供可檢查的契約

每個工具至少要有穩定名稱、輸入 schema、能力、讀寫類型與依賴。描述文字幫助選擇器理解用途，schema 則限制可接受參數；兩者不能互相代替。

例如天氣工具可以要求 location 與 dateRange，只讀取外部資料。建立行事曆事件則需要明確的開始與結束時間、時區、目標行事曆與寫入核准。即使兩個工具都和「行程」有關，執行風險也不同。

時間需求也要保留。今天的天氣需要近期資料，解釋氣候概念未必需要搜尋。歷史查詢則不能因為出現「天氣」就自動加今年的搜尋條件。把時間敏感性獨立出來，目的是讓選擇器看見這種差異。

「週末」還需要請求發生時間與時區。「行程」可能只是產生建議，也可能是在行事曆建立事件，兩者授權不同。選擇器應先整理已知條件與缺少條件，必要時澄清，不用增加工具數量來猜使用者要做哪一種動作。

參數來源也要可追查：地點是本次輸入、已授權偏好，還是模型猜測？日期經過哪個時區換算？把這些資訊放在執行計畫中，才有機會在執行前阻擋錯誤目標。工具名稱相同，但參數改成另一座城市或另一個行事曆，已經是不同操作，不能沿用先前核准。

切換天氣、行程與知識查詢情境，觀察各工具的教學分數與入選原因。再提高門檻，看哪些工具被排除，以及低分工具是否因必要依賴被補回。對照批次計畫，確認取得位置、查天氣與組合行程的先後關係。

分數長條是這個範例的排序訊號，沒有經過校準，不能讀成「成功機率」。門檻調高也不保證更安全或更準確，可能只是讓必要工具消失。圖解展示候選選擇與必要依賴的批次計畫，不會真正執行工具。參數驗證、權限與執行結果仍是另外的邊界。

把既有產品 API 包成 SDK 工具

不用為了 Agent 另造一套不受控的產品後端。先挑一個已有授權與測試的只讀能力，例如依登入者查詢自己的部署設定，再把名稱、說明與參數結構交給 SDK。工具執行時仍呼叫原本的產品服務，讓同一套租戶權限在網頁 API 和 Agent 工具都生效。

OpenAI Agents SDK 可以用 tool() 註冊函式工具，或透過 MCP 接入既有服務。SDK 處理模型提出工具呼叫後的迴圈；執行函式負責真實資料的取得。登入者與服務依賴可放在執行程式的 context，不直接送進模型。工具應從這份受信任的狀態取得身分，而不是接受模型填寫的 tenantId 作為授權依據。OpenAI：工具整合、執行程式的 context

Claude Agent SDK 提供 tool() 與 createSdkMcpServer()，可以把自己的產品能力包成程序內 MCP 工具。它的工具搜尋可等需要時才載入工具結構，但工具搜尋只解決「有哪些能力值得提供給模型」，不決定登入者能操作哪些資料，也不等於圖解中的自訂排序規則。Claude：Custom tools、Tool search

當只讀流程能正確完成，再加一個需要核准的寫入工具。OpenAI Agents SDK 的 needsApproval 可讓執行暫停，產品保留 interruptions 與 state，等收到有效核准再接續原任務。Claude 的 canUseTool 可以處理仍需詢問的權限決策，但要注意已自動核准的工具可能不進入這個回呼；每次都需要檢查的產品政策應放在 PreToolUse，或直接在工具服務端執行。OpenAI：人工核准、Claude：權限判斷順序

MCP 是能力的連接方式，不是權限保證。不論函式在哪個程序執行，產品都要能回答：這次操作屬於誰、參數從哪裡來、為什麼可以執行，以及完成後留下了什麼結果。

排序是軟性偏好，授權是硬性條件

可以用相關性、時效、歷史表現與成本構成一個教學分數，但不能讓分數決定能否讀取私人資料。低成本工具沒有權限也不能執行，高相關工具缺少必要參數也不能執行。

下面是執行端的流程示意。它刻意不接受模型宣稱的「已授權」，而是向獨立的授權服務檢查目前身分與目標資源：

type ToolCall = { name: string; arguments: unknown };
type Tool = {
  name: string;
  effect: 'read' | 'write';
  parse: (input: unknown) => unknown;
  run: (input: unknown) => Promise<unknown>;
};
type Context = { actorId: string; tenantId: string };

async function execute(
  call: ToolCall, context: Context, allowlist: Map<string, Tool>,
  authorize: (context: Context, tool: Tool, args: unknown) => Promise<void>,
  consumeApproval: (context: Context, tool: Tool, args: unknown) => Promise<void>,
) {
  const tool = allowlist.get(call.name);
  if (!tool) throw new Error('TOOL_NOT_ALLOWED');
  const args = tool.parse(call.arguments);
  await authorize(context, tool, args);
  if (tool.effect === 'write') {
    await consumeApproval(context, tool, args);
  }
  return tool.run(args);
}

parse 必須在執行時驗證參數，不能只用 TypeScript 型別斷言。authorize 要檢查登入者、租戶與實際目標；寫入核准則應綁定這次工具、目標與參數，原子地檢查並消耗，避免重複使用。OWASP 將這種授權放在 agent 脈絡之外的執行元件，而不是相信一個模型傳來的確認旗標。AI Agent Security Cheat Sheet

這段省略了核准儲存、時效與資源競爭處理，沒有因此取得交易原子性。參數驗證和授權後若目標狀態改變，底層寫入仍需要自己的條件檢查。JSON Schema 也可以拒絕不屬於契約的額外欄位，但 schema 合法不代表實際操作已授權。JSON Schema：Object

規劃執行順序與失敗處理

有依賴時，不能把所有工具一起送出

「個人化行程搜尋」可能依賴記憶檢索所得的偏好；一般天氣查詢則可以獨立執行。把兩者都放進 Promise.all，不會讓依賴資料提早出現。應先建出有向圖：記憶檢索指向個人化查詢，天氣與個人化查詢再指向最後彙整。

執行前檢查必要依賴是否存在與是否成環，再分出可以同時執行的群組。對於依賴失敗的下游，標示 blocked；獨立工具則可以繼續。Promise.allSettled 只幫忙取得每個結果的狀態，不會替你判斷「缺少天氣資料的行程」是否仍滿足原任務。

還要區分必要與可選。天氣失敗後，若只能給不依天氣調整的路線，應明說限制；建立事件失敗則不能顯示「已安排完成」。把部分成功包成全成功，會讓使用者在真實世界執行錯誤計畫。

工具逾時後，先確認副作用發生了沒

只讀查詢一般比較適合有限重試，但也會增加外部負載與等待時間。寫入工具不同：建立事件逾時，可能是回應未送達，事件其實已經建立。直接重試可能得到兩個事件，刪檔逾時也不能推斷原檔還在。

對寫入操作需要穩定操作識別碼、可查詢的執行狀態與明確冪等契約；缺少這些條件時，應停止自動重試並回報結果不確定。重試與備用工具同樣受限，不能換了工具就假設同一個寫入沒有發生。

呼叫端的逾時設定結束等待，也不等於遠端執行被取消。執行器要把取消訊號傳到支援它的底層，並對無法取消或晚到結果定義處理方式。工具結果本身也可能含不可信指令，送回模型時仍要標示來源，不能升級成新的系統規則。

驗證計畫與動作，而不是只看選中名稱

固定幾個請求，檢查最新資訊需求是否選擇可提供近期資料的工具，知識解釋是否避免不必要的查詢，缺地點時是否先澄清。再把門檻提高到無候選，確認服務回報能力不足，不是假造工具結果。

執行端另測未知工具、額外參數、跨租戶目標、核准過期與重複核准。對依賴失敗確認下游未執行，對寫入逾時確認沒有盲目重送。選對工具只是計畫的一部分；能夠重現每個動作的參數來源、授權依據與執行結果，才知道這次請求實際做了什麼。

延伸閱讀

SDK 文件核對日期：2026-10-07。

• OpenAI Agents SDK：工具與核准
• Claude Agent SDK：自訂 MCP 工具
• Claude Agent SDK：工具搜尋與適用限制
• OWASP：Agent 安全檢查

本篇屬於「在產品裡打造 Agentic 功能」系列。可以先看產品架構與 Agent 迴圈。

上一篇：多家 LLM 怎麼切換。下一篇：語意分群怎麼解讀。