伺服器工具

伺服器端執行的工具共享以下機制：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-5",
    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-5",
        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 訊息，就像您累積任何其他工具使用交換一樣。

這與 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 區塊，並使用相同的工具。
    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" 結束；您可以透過提交包含回傳內容的後續請求來接續它。詳情請參閱伺服器工具與代理式迴圈。

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



後續步驟