伺服器工具

本頁涵蓋伺服器執行工具的共享機制：server_tool_use 區塊、pause_turn 延續、ZDR 考量和網域篩選。如需個別工具，請參閱工具參考。

server_tool_use 區塊

當伺服器執行的工具運行時，server_tool_use 區塊會出現在 Claude 的回應中。其 id 欄位使用 srvtoolu_ 前綴來區別於用戶端工具呼叫：

{
  "type": "server_tool_use",
  "id": "srvtoolu_01A2B3C4D5E6F7G8H9",
  "name": "web_search",
  "input": { "query": "latest quantum computing breakthroughs" }
}

API 在內部執行工具。您可以在回應中看到呼叫及其結果，但您不需要處理執行。與用戶端 tool_use 區塊不同，您不需要使用 tool_result 進行回應。結果區塊會立即出現在同一助手回合中 server_tool_use 區塊之後。

伺服器端迴圈和 pause_turn

使用伺服器工具（如網路搜尋）時，API 可能會傳回 pause_turn 停止原因，表示 API 已暫停長時間執行的回合。

以下是如何處理 pause_turn 停止原因的方法：

# 使用網路搜尋的初始請求
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        }
    ],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
)

# 檢查回應是否有 pause_turn 停止原因
if response.stop_reason == "pause_turn":
    # 使用暫停的內容繼續對話
    messages = [
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        },
        {"role": "assistant", "content": response.content},
    ]

    # 傳送延續請求
    continuation = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=1024,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
    )

    print(continuation)
else:
    print(response)

處理 pause_turn 時：

• 繼續對話： 在後續請求中按原樣傳回暫停的回應，讓 Claude 繼續其回合
• 視需要修改： 如果您想中斷或重新導向對話，可以選擇在繼續前修改內容
• 保留工具狀態： 在延續請求中包含相同的工具以維持功能

ZDR 和 allowed_callers

網路搜尋的基本版本（web_search_20250305）和網路擷取（web_fetch_20250910）符合零資料保留 (ZDR) 的資格。

具有動態篩選的 _20260209 版本預設不符合 ZDR 資格，因為動態篩選依賴於內部程式碼執行。

若要使用 _20260209 伺服器工具搭配 ZDR，請透過在工具上設定 "allowed_callers": ["direct"] 來停用動態篩選：

{
  "type": "web_search_20260209",
  "name": "web_search",
  "allowed_callers": ["direct"]
}

這會限制工具僅供直接呼叫，繞過內部程式碼執行步驟。

網域篩選

存取網路的伺服器工具接受 allowed_domains 和 blocked_domains 參數來控制 Claude 可以到達哪些網域。

使用網域篩選時：

• 網域不應包含 HTTP/HTTPS 配置（使用 example.com 而不是 https://example.com）
• 子網域會自動包含（example.com 涵蓋 docs.example.com）
• 特定子網域會限制結果僅限於該子網域（docs.example.com 僅傳回該子網域的結果，不傳回 example.com 或 api.example.com 的結果）
• 支援子路徑並符合路徑後的任何內容（example.com/blog 符合 example.com/blog/post-1）
• 您可以使用 allowed_domains 或 blocked_domains，但不能在同一請求中同時使用兩者

萬用字元支援：

• 每個網域項目只允許一個萬用字元 (*)，且必須出現在網域部分之後（在路徑中）
• 有效：example.com/*、example.com/*/articles
• 無效：*.example.com、ex*.com、example.com/*/news/*

無效的網域格式會傳回 invalid_tool_input 工具錯誤。

使用程式碼執行的動態篩選

網路搜尋和網路擷取的 _20260209 版本在內部使用程式碼執行來對搜尋結果套用動態篩選。

串流伺服器工具事件

伺服器工具事件作為正常 SSE 流的一部分進行串流。server_tool_use 區塊及其結果以 content_block_start 和 content_block_delta 事件的形式到達，與文字和用戶端工具呼叫的串流方式相同。

如需完整的事件參考，請參閱串流。個別工具頁面會記錄工具特定的事件名稱（如有差異）。

批次請求

所有伺服器工具都支援批次處理。請參閱批次處理。

後續步驟