2026 Claude Sonnet 5 API 部署：工具呼叫怎麼配？

症狀：Agent 能產生工具呼叫，卻在執行失敗、重試或輸出格式錯誤時無法追查。
最快解法：先用少量高品質工具建立可觀測的閉環，再開啟嚴格工具參數與結構化最終輸出；不要一開始就接入大量 MCP 工具，正式上線前補齊權限、逾時、幂等與人工接管。

這套方法適合目前要確認 Claude Sonnet 5 API 可用性、模型支援範圍與介面限制的團隊；截至 2026 年 8 月 18 日，相關能力仍應以 Anthropic Claude Sonnet 5 官方公告、Claude 模型頁及 API 更新紀錄為準。

首次使用 Claude Sonnet 5 API 的開發者，應從最小工具集開始。已有 Claude Tool Use 專案的團隊，要重新檢查嚴格模式和輸出格式。準備在遠端執行 Agent 的工程師，則要把進程、環境變數、網路與日誌列為部署條件，而不是事後補救。

先界定工具邊界

部署的第一個決定不是選哪個模型參數，而是決定模型可以要求應用程式做什麼。建議先選一個只讀工具，例如查詢工單或讀取檔案狀態，再選一個低風險動作，例如建立草稿；不要直接把刪除資料、發送正式訊息或修改生產環境的工具暴露給模型。

工具名稱要能表達動作和對象，描述則要寫清楚使用時機、不可處理的情況及權限邊界。輸入 Schema 不應只列出欄位名稱，還要約束型別、必要欄位、列舉值與字串格式。這一步解決的是「模型想呼叫什麼」的問題，不是「工具實際能否執行」的問題。

你還需要在應用程式端保留以下資料：

• 每次請求使用的模型識別與版本。
• 工具名稱、輸入內容及呼叫識別碼。
• 執行開始、結束、逾時或拒絕的時間點。
• 工具回傳內容、錯誤類型及操作者決策。
• 使用者要求、系統指令與最後輸出之間的關聯。

官方 Tool Use 文件將工具定義、模型產生的 tool_use 區塊與應用程式回傳的 tool_result 視為同一個呼叫流程；因此，日誌不能只保存最後一段文字回覆。Tool Use 概覽文件可作為欄位與訊息結構的核對依據。

Claude Sonnet 5 API 工具呼叫流程

一個可驗證的 Claude Tool Use 閉環，應依照以下時間線執行：

• 應用程式送出使用者訊息與工具定義。
• 模型回應文字，或提出 tool_use 呼叫；此時模型只是在提出請求，尚未替你執行工具。
• 應用程式驗證工具名稱、輸入 Schema、使用者權限與風險等級。
• 執行器在隔離環境執行工具，並保存呼叫識別碼與結果。
• 應用程式以對應的 tool_result 回傳成功資料或明確錯誤。
• 模型根據工具結果繼續回答，或提出下一個合法工具呼叫。
• 達到完成條件後，才把最終結果交給使用者或下游系統。

「Claude Sonnet 5 怎麼呼叫外部工具」的答案是：模型產生結構化的工具請求，真正的外部副作用必須由你的應用程式控制。官方工具結果處理說明也特別適合用來檢查回傳順序與工具結果的關聯。

最小閉環範例

以下是概念化的伺服器端流程，重點是控制權，而不是複製一份固定 SDK 程式碼：

response = client.messages.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": user_request}],
    tools=[read_ticket_tool, create_draft_tool]
)

for block in response.content:
    if block.type == "tool_use":
        validate_name(block.name)
        validate_input_schema(block.input)
        authorize(user, block.name, block.input)

        result = executor.run(
            name=block.name,
            arguments=block.input,
            idempotency_key=block.id
        )

        messages.append({"role": "assistant", "content": response.content})
        messages.append({
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result
            }]
        })

正式實作時，不要假定每次回應都只有一個工具區塊，也不要把模型輸入直接拼成 Shell 指令。name、input 與工具呼叫識別碼必須分別驗證；工具結果則要限制長度、敏感資料與可再次執行的內容。

嚴格工具參數與結構化輸出

Claude strict tool use 應該怎麼配置，取決於你要約束的是「工具輸入」還是「最終回應」。這兩者不能混為一談：

嚴格工具參數只能降低錯誤輸入進入工具的機會，不能取代權限控制。Structured Outputs 則是約束模型最後交付的結構，例如欄位是否存在、型別是否一致，以及下游是否能按 Schema 解析。Anthropic Structured Outputs 文件應在部署前重新核對，因為支援模型、預覽功能和參數名稱可能隨 API 更新而變更。

若遇到拒絕、長度中斷、Schema 過於複雜或輸出無法解析，不要用字串替換硬修 JSON。應記錄原始回應，判斷是輸入不合規、輸出被截斷、工具失敗，還是模型沒有足夠資訊，再選擇重試、補充資料或人工接管。

可靠執行與錯誤分支

Claude 工具呼叫後如何返回結果，關鍵在於每個結果都要能對應到原來的呼叫識別碼。成功結果應包含執行所需的最少資料；失敗結果則要讓模型知道是權限不足、參數錯誤、資源不存在、逾時，還是暫時性服務錯誤。

你可以按以下順序建立執行器：

• 先檢查呼叫者身份、租戶和工具權限。
• 以 Schema 驗證輸入，再檢查商業規則，例如檔案路徑是否在允許目錄。
• 為每個工具設定獨立逾時，不要讓單一外部服務拖住整個 Agent。
• 只對明確的暫時性錯誤重試；參數錯誤與權限錯誤不應重試。
• 使用呼叫識別碼或業務幂等鍵偵測重複動作。
• 發送訊息、修改資料、執行部署等高風險動作，加入人工批准。
• 把重試次數、逾時原因與最終狀態寫入可查詢日誌。

這裡至少有三項可直接驗收的介面資料：工具呼叫的 name、輸入的 input、以及結果所引用的 tool_use_id。它們不是裝飾欄位，而是把「模型要求」「應用程式執行」「模型收到結果」串起來的最小追蹤鍵，欄位意義應以官方 Tool Use 結果處理文件為準。

場景案例：搜尋後建立業務草稿

假設你的 Agent 先查詢客戶紀錄，再建立一封未寄出的回覆草稿。查詢工具可以自動執行，但建立草稿前仍要確認客戶識別、資料範圍與操作者權限。若搜尋服務逾時，應回傳「資料未取得」而不是空結果，否則模型可能誤以為查無紀錄並生成錯誤草稿。

這個流程的優點是每一步都能回放，且低風險工具與高風險工具的權限可以分離。缺點是你必須維護狀態、錯誤分類和人工隊列；若團隊只想靠提示詞保證安全，部署後通常很難判斷重複呼叫究竟來自模型、網路重試還是執行器。

MCP 擴展條件

Claude API 和 MCP 應該一起使用嗎？不必預設一起使用。當只有一個後端服務、工具清單穩定，而且你可以直接控制工具註冊時，直接使用 API Tool Use 會比較容易除錯。當多個 Agent、客戶端或團隊需要發現和重用同一批工具時，才值得增加 MCP 層。

接入 MCP 前，先確認：

• 遠端連線失敗時，Agent 是否能安全停止。
• 授權範圍是否按使用者、工作區和工具拆分。
• 工具清單或 Schema 改變時，是否會觸發重新驗證。
• 第三方資料是否包含個人資料、機密內容或跨租戶資訊。
• MCP 連接器的限制、支援模型與預覽狀態是否符合當日文件。

Anthropic MCP Connector 說明可用來核對連接方式與支援邊界。不要把 MCP 當成權限系統，也不要因為工具可以被發現，就讓所有工具自動可執行；授權、審批、日誌和回滾仍應留在你的服務端。

遠端 Mac 上線驗收

Claude Agent 部署需要哪些日誌，答案不是只記錄模型文字。遠端 Mac 環境至少要能查到進程狀態、啟動時間、目前版本、環境變數是否載入、工具呼叫識別碼、逾時事件、重試原因和人工批准結果。密鑰本身不能寫進日誌，但密鑰版本與輪換事件應可追蹤。

上線前可照以下順序驗收：

• 以非管理員身份啟動 Agent，確認不必要的檔案和系統權限已移除。
• 重啟進程，確認守護機制能恢復服務，且不會重複執行上一個未完成動作。
• 分別測試可用網路、DNS 失敗、外部 API 逾時與 MCP 連線中斷。
• 檢查環境變數、密鑰輪換、日誌權限及敏感資料遮罩。
• 用真實但低風險的任務記錄完整呼叫鏈，不引用無法重現的效能結論。
• 故意送入錯誤參數、重複請求和超出權限的動作，確認系統會拒絕而不是猜測。
• 準備回滾版本與人工接管路徑，並在小規模任務完成後才擴大工具範圍。

你可以把Macstripe 幫助中心作為遠端環境操作資料的入口；若團隊需要先確認配置與租用條件，再查看Mac 遠端配置訂單頁。若涉及帳戶、資料處理或權限責任，則應同步閱讀服務法律資訊。

上線判斷與方案取捨

如果你的 Agent 仍在確認工具輸入、Structured Outputs 解析或 MCP 工具清單變更，先不要追求一次接入完整業務系統。最小閉環雖然需要額外寫執行器、狀態保存和日誌，但它能讓你在低風險條件下定位問題；直接接入大量工具，則容易把權限錯誤、Schema 變更和網路故障混成同一個模型問題。

本地 Mac 適合需要實體介面、固定硬體周邊或長期持續重負載的團隊；但自行維護通常會遇到機器閒置仍持續產生成本、遠端開機與網路入口需要自行處理，以及密鑰和進程故障缺少集中交接等缺點。若你只是要按任務週期驗證 Claude Agent、執行 Claude Code 類型的遠端開發，或先觀察真實工具呼叫日誌，租用 Macstripe 的遠端 Mac 環境通常比臨時購置硬體更容易控制啟用範圍；先用小規模真實任務驗收，確認穩定性與權限邊界後，再決定是否長期使用。