伺服器工具

由伺服器執行的工具共用以下機制：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 會在伺服器端的代理迴圈（agentic loop）中執行工具呼叫。在長時間運行的回合中，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}],
)

# 檢查回應是否具有 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 流程的一部分進行串流（streaming）。Claude 直接呼叫的 server_tool_use 區塊的串流方式與用戶端 tool_use 區塊相同：一個 content_block_start 事件，接著是 input_json_delta 事件。結果區塊會在單一 content_block_start 事件中完整送達，沒有增量（deltas）。

完整的事件參考請參閱串流。個別工具頁面會記載與此不同的工具專屬事件名稱。



批次請求

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

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



後續步驟