服务器工具

服务器端执行的工具共享以下机制：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 块，并附带相同的工具。
    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）的基础版本符合零数据保留（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" 结束；您可以通过提交包含返回内容的后续请求来继续它。有关详细信息，请参阅服务器工具与智能体循环。

常见的批量工作负载包括：使用来自网络的信息丰富数据集、根据当前来源检查大量文档，以及对许多文件运行分析代码。



后续步骤