服务器工具

本页面涵盖服务器执行工具的共享机制：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": "搜索有关 2025 年量子计算突破的全面信息",
        }
    ],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
)

# 检查响应是否具有 pause_turn 停止原因
if response.stop_reason == "pause_turn":
    # 继续与暂停的内容进行对话
    messages = [
        {
            "role": "user",
            "content": "搜索有关 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 事件到达，与文本和客户端工具调用流式传输的方式相同。

有关完整的事件参考，请参阅流式传输。各个工具页面在不同的地方记录工具特定的事件名称。

批处理请求

所有服务器工具都支持批处理。请参阅批处理。

后续步骤