伺服器工具

伺服器執行的工具共享以下機制：server_tool_use 區塊、pause_turn 接續、混合伺服器與用戶端工具的回合、「Zero Data Retention」（零資料保留），即 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 回應。工具的結果區塊（例如網頁搜尋的 web_search_tool_result）會在同一個助理回合中緊接在 server_tool_use 區塊之後，並透過 tool_use_id 配對。如果 Claude 同時呼叫您的其中一個用戶端工具，server_tool_use 區塊會在沒有其結果的情況下出現，且回應會以 stop_reason: "tool_use" 結束。當您在下一個請求中回傳用戶端 tool_result 區塊時，API 才會執行該工具。



伺服器端迴圈與 pause_turn

使用網頁搜尋等伺服器工具時，API 會在伺服器端的代理迴圈中執行工具呼叫。在長時間運行的回合中，API 可能會暫停該迴圈並回傳 pause_turn 停止原因。

以下是處理 pause_turn 停止原因的方式：

client = anthropic.Anthropic()

# 使用網頁搜尋的初始請求
response = client.messages.create(
    model="claude-opus-4-8",
    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}],
)

# 檢查回應的 stop_reason 是否為 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-8",
        max_tokens=1024,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
    )

    print(continuation)
else:
    print(response)

處理 pause_turn 時：

• **接續對話：**將暫停的回應原封不動地傳回後續請求中，讓 Claude 繼續其回合。
• **保留工具狀態：**在接續請求中包含相同的工具。暫停的回合可能以尚未執行的 server_tool_use 區塊結束，如果接續請求中缺少該工具，API 會回傳驗證錯誤。
• **視需要重複：**接續的回合可能再次暫停。請檢查每個回應的 stop_reason，並持續接續直到獲得不同的停止原因為止，同時像處理任何重試迴圈一樣限制接續次數的上限。

關於其他 stop_reason 值和一般處理模式，請參閱停止原因與備援。



在單一回合中混合伺服器工具與用戶端工具

Claude 可以在同一組平行工具呼叫中同時呼叫伺服器工具和用戶端工具，例如 web_fetch 搭配使用者定義的工具。用戶端工具是指任何由您的程式碼執行並產生 tool_use 區塊的工具，無論是使用者定義的工具，還是 Anthropic 結構描述的用戶端工具，例如 Bash 工具。發生這種情況時，API 不會執行伺服器工具，而是立即回傳，讓您先執行用戶端工具：

• stop_reason 為 "tool_use"，而非 "pause_turn"。
• content 包含 server_tool_use 區塊和用戶端 tool_use 區塊，但沒有伺服器工具的結果區塊：該呼叫尚未完成。
• 沒有其他標記。請透過尋找回應中 id 沒有對應結果區塊的 server_tool_use 區塊來偵測此狀態。來自 MCP 連接器的 mcp_tool_use 區塊行為相同。在同一回應中已有結果區塊的伺服器工具呼叫則已完成，您無需進行任何處理。

{
  "stop_reason": "tool_use",
  "content": [
    {
      "type": "text",
      "text": "I'll fetch the article and check your system at the same time."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
      "name": "web_fetch",
      "input": { "url": "https://example.com/article" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "name": "run_command",
      "input": { "command": "uname -a" }
    }
  ]
}

若要接續回合，請執行用戶端工具並傳送一則使用者訊息，其內容僅包含 tool_result 區塊，每個對應該回應中的一個 tool_use 區塊。請保持相同的 tools 陣列：若恢復請求不再定義等待中的伺服器工具，會以 400 錯誤失敗，其訊息結尾為 but no `web_fetch` tool was provided。

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux"
    }
  ]
}

API 會將您的結果附加到仍開啟的助理回合，執行延遲的伺服器工具（對於暫停的程式碼執行，則恢復執行），然後讓 Claude 繼續。對於 Claude 直接呼叫的伺服器工具，下一個回應會以回答前一個回應中 server_tool_use id 的結果區塊開始，接著是新生成的內容和新的 stop_reason：

{
  "stop_reason": "end_turn",
  "content": [
    {
      "type": "web_fetch_tool_result",
      "tool_use_id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
      "content": {
        "type": "web_fetch_result",
        "url": "https://example.com/article",
        "content": {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "Full text content of the article..."
          }
        }
      }
    },
    {
      "type": "text",
      "text": "The article argues that... and your machine is running Linux..."
    }
  ]
}

server_tool_use 區塊及其結果區塊是透過 tool_use_id 配對，而非透過位置：在此流程中，它們會在兩個不同的回應中送達，且 server_tool_use 區塊不會在第二個回應中重複出現。在後續請求中，請依序將整個交換保留在您的 messages 陣列中：第一個回應作為 assistant 訊息、tool_result 使用者訊息，然後下一個回應作為另一個 assistant 訊息，就像您累積任何其他工具使用交換一樣。

`web_fetch` tool use with id `srvtoolu_01HxbWnMRmbWyMfUtJKC45rA` was found without a corresponding `web_fetch_tool_result` block

`tool_use` ids were found without `tool_result` blocks immediately after: toolu_01PjgRJLbXrXEMZwDNYLnBqk. Each `tool_use` block must have a corresponding `tool_result` block in the next message.

這與 pause_turn 的差異：pause_turn 回應也可能以尚未執行的 server_tool_use 區塊結束，但它絕不會留下等待您處理的用戶端 tool_use 區塊，因此您可以透過原封不動地重新傳送助理內容來接續它。留下等待您處理的用戶端 tool_use 區塊的回應，其 stop_reason 絕不會是 pause_turn：當 Claude 停下來呼叫您的工具時，stop_reason 為 tool_use，您需要透過傳送用戶端 tool_result 區塊來接續，而非重新傳送回應。在這兩種情況下，API 都會在下一個請求開始時執行待處理的伺服器工具。

以下範例啟用網頁擷取並搭配使用者定義的 run_command 工具，並處理混合回應：

client = anthropic.Anthropic()

tools = [
    {"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5},
    {
        "name": "run_command",
        "description": "Run a shell command on this computer and return its output.",
        "input_schema": {
            "type": "object",
            "properties": {
                "command": {"type": "string", "description": "The command to run"}
            },
            "required": ["command"],
        },
    },
]
messages = [
    {
        "role": "user",
        "content": "Summarize https://example.com/article and run uname -a to tell me what system this is on.",
    }
]

response = client.messages.create(
    model="claude-opus-4-8", max_tokens=1024, tools=tools, messages=messages
)

tool_results = [
    {
        "type": "tool_result",
        "tool_use_id": block.id,
        # 在此執行您的工具。此範例回傳固定字串。
        "content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux",
    }
    for block in response.content
    if block.type == "tool_use"
]

if response.stop_reason == "tool_use" and tool_results:
    # 若 server_tool_use 區塊在此回應中沒有對應的結果區塊，表示尚未完成；其結果會在後續回應中送達。
    # 僅回傳用戶端的 tool_result 區塊，並附上相同的 tools。
    continuation = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        tools=tools,
        messages=[
            *messages,
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": tool_results},
        ],
    )
    # 若 web_fetch 被延後，它會在此請求中執行，且其
    # web_fetch_tool_result 會是 continuation.content 的第一個區塊。
    print(continuation)
else:
    print(response)

當 Claude 未混合這兩種呼叫時，此程式碼同樣正確。僅包含用戶端 tool_use 區塊的回合會採用相同的接續路徑，而僅包含伺服器工具呼叫的回合則不需要您提供用戶端 tool_result 區塊：其結果區塊通常已經存在，而以暫停狀態回傳的回合（例如 pause_turn 回應）則改為原封不動地重新傳送。



ZDR 與 allowed_callers

網頁搜尋（web_search_20250305）和網頁擷取（web_fetch_20250910）的基本版本符合「Zero Data Retention」（零資料保留，ZDR）的資格。

_20260209 及更新版本具有動態過濾功能，預設不符合 ZDR 資格，因為動態過濾在內部依賴程式碼執行。

若要在 ZDR 下使用 _20260209 或更新版本的伺服器工具，請在工具上設定 "allowed_callers": ["direct"] 以停用動態過濾：

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

這會將工具限制為僅能直接調用，繞過內部的程式碼執行步驟。

allowed_callers 控制工具的調用方式：由 Claude 直接調用（"direct"）、從程式碼執行容器內部調用（例如 "code_execution_20260120"），或兩者皆可。網頁工具的 _20260209 版本預設僅允許程式碼執行呼叫者；較早的版本預設為 ["direct"]。在不支援程式化工具呼叫的模型上，這些版本需要 allowed_callers: ["direct"]；若未設定，API 會回傳驗證錯誤，指示您進行設定。



網域過濾

存取網路的伺服器工具接受 allowed_domains 和 blocked_domains 參數，以控制 Claude 可以存取的網域。兩者都是工具物件上的欄位：

{
  "type": "web_search_20250305",
  "name": "web_search",
  "allowed_domains": ["example.com", "docs.python.org"]
}

使用網域過濾器時：

• 網域不應包含 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）。
• 網頁擷取僅比對網域：包含路徑的項目永遠不會比對網頁擷取的 URL。
• 您可以使用 allowed_domains 或 blocked_domains，但不能在同一請求中同時使用兩者。

萬用字元支援：

• 網域本身不允許使用萬用字元（*），僅允許在其後的路徑中使用。
• 有效：example.com/*、example.com/*/articles
• 無效：*.example.com、ex*.com

無效的網域格式會在請求時以 400 invalid_request_error 被拒絕。



使用程式碼執行的動態過濾

網頁搜尋和網頁擷取的 _20260209 及更新版本在內部使用程式碼執行，對搜尋結果套用動態過濾器。



串流伺服器工具事件

伺服器工具事件會作為正常「server-sent events」（伺服器傳送事件），即 SSE 流程的一部分進行串流。Claude 直接呼叫的 server_tool_use 區塊的串流方式與用戶端 tool_use 區塊相同：一個 content_block_start 事件，後接 input_json_delta 事件。結果區塊會在單一 content_block_start 事件中完整送達，沒有增量。

請參閱串流以取得完整的事件參考。個別工具頁面會記錄工具特定的事件名稱（如有不同）。



批次請求

所有伺服器工具都支援批次處理。在批次中，代理迴圈的運作方式與同步請求相同，但每回合的迭代限制較高。如果迴圈達到該限制，回應會以 stop_reason: "pause_turn" 結束；您可以透過提交包含回傳內容的後續請求來接續。詳情請參閱伺服器工具與代理迴圈。

常見的批次工作負載包括使用網路資訊豐富資料集、根據目前來源檢查大量文件，以及對許多檔案執行分析程式碼。



後續步驟