# 服务器工具

使用 Anthropic 执行的工具：server_tool_use 块、pause_turn 续接和域名过滤。

---

本页介绍服务器执行工具的共享机制：`server_tool_use` 块、`pause_turn` 续接、ZDR 注意事项和域名过滤。有关各个工具，请参见[工具参考](/docs/en/agents-and-tools/tool-use/tool-reference)。

## server_tool_use 块

`server_tool_use` 块在服务器执行的工具运行时出现在 Claude 的响应中。其 `id` 字段使用 `srvtoolu_` 前缀，以区别于客户端工具调用：

```json
{
  "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

使用 web search 等服务器工具时，API 可能返回 `pause_turn` 停止原因，表示 API 已暂停一个长时间运行的轮次。

以下是处理 `pause_turn` 停止原因的方法：

<CodeGroup>
```python Python hidelines={1..4}
import anthropic

client = anthropic.Anthropic()

# 使用 web search 的初始请求
response = client.messages.create(
    model="claude-opus-4-7",
    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-4-7",
        max_tokens=1024,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
    )

    print(continuation)
else:
    print(response)
```

```typescript TypeScript hidelines={1..4}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

async function main() {
  // 使用 web search 的初始请求
  const response = await client.messages.create({
    model: "claude-opus-4-7",
    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") {
    // 使用暂停的内容继续对话
    const messages: Anthropic.MessageParam[] = [
      {
        role: "user",
        content:
          "Search for comprehensive information about quantum computing breakthroughs in 2025"
      },
      { role: "assistant", content: response.content }
    ];

    // 发送续接请求
    const continuation = await client.messages.create({
      model: "claude-opus-4-7",
      max_tokens: 1024,
      messages: messages,
      tools: [
        {
          type: "web_search_20250305",
          name: "web_search",
          max_uses: 10
        }
      ]
    });

    console.log(continuation);
  } else {
    console.log(response);
  }
}

main().catch(console.error);
```

```csharp C#
using Anthropic;
using Anthropic.Models.Messages;
using System;
using System.Linq;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        AnthropicClient client = new();

        var parameters = new MessageCreateParams
        {
            Model = "claude-opus-4-7",
            MaxTokens = 1024,
            Messages = [
                new() {
                    Role = Role.User,
                    Content = "Search for comprehensive information about quantum computing breakthroughs in 2025"
                }
            ],
            Tools = [new ToolUnion(new WebSearchTool20250305() { MaxUses = 10 })]
        };

        var response = await client.Messages.Create(parameters);

        if (response.StopReason == "pause_turn")
        {
            var continuationParams = new MessageCreateParams
            {
                Model = "claude-opus-4-7",
                MaxTokens = 1024,
                Messages = [
                    new() {
                        Role = Role.User,
                        Content = "Search for comprehensive information about quantum computing breakthroughs in 2025"
                    },
                    new() {
                        Role = Role.Assistant,
                        Content = response.Content.Select(block => new ContentBlockParam(block.Json)).ToList()
                    }
                ],
                Tools = [new ToolUnion(new WebSearchTool20250305() { MaxUses = 10 })]
            };

            var continuation = await client.Messages.Create(continuationParams);
            Console.WriteLine(continuation);
        }
        else
        {
            Console.WriteLine(response);
        }
    }
}
```

```go Go hidelines={1..13,-1}
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/anthropics/anthropic-sdk-go"
)

func main() {
	client := anthropic.NewClient()

	webSearchTool := []anthropic.ToolUnionParam{
		{OfWebSearchTool20250305: &anthropic.WebSearchTool20250305Param{
			MaxUses: anthropic.Int(10),
		}},
	}

	response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
		Model:     anthropic.ModelClaudeOpus4_7,
		MaxTokens: 1024,
		Messages: []anthropic.MessageParam{
			anthropic.NewUserMessage(anthropic.NewTextBlock("Search for comprehensive information about quantum computing breakthroughs in 2025")),
		},
		Tools: webSearchTool,
	})
	if err != nil {
		log.Fatal(err)
	}

	if response.StopReason == "pause_turn" {
		// 将响应内容转换为助手消息的参数类型
		var contentParams []anthropic.ContentBlockParamUnion
		for _, block := range response.Content {
			contentParams = append(contentParams, block.ToParam())
		}

		continuation, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
			Model:     anthropic.ModelClaudeOpus4_7,
			MaxTokens: 1024,
			Messages: []anthropic.MessageParam{
				anthropic.NewUserMessage(anthropic.NewTextBlock("Search for comprehensive information about quantum computing breakthroughs in 2025")),
				anthropic.NewAssistantMessage(contentParams...),
			},
			Tools: webSearchTool,
		})
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(continuation)
	} else {
		fmt.Println(response)
	}
}
```

```java Java hidelines={1..4,7..8,-1..}
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.StopReason;
import com.anthropic.models.messages.WebSearchTool20250305;

void main() {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    MessageCreateParams params = MessageCreateParams.builder()
        .model("claude-opus-4-7")
        .maxTokens(1024L)
        .addUserMessage("Search for comprehensive information about quantum computing breakthroughs in 2025")
        .addTool(WebSearchTool20250305.builder()
            .maxUses(10L)
            .build())
        .build();

    Message response = client.messages().create(params);

    if (response.stopReason().isPresent()
            && response.stopReason().get().equals(StopReason.PAUSE_TURN)) {
        MessageCreateParams continuationParams = MessageCreateParams.builder()
            .model("claude-opus-4-7")
            .maxTokens(1024L)
            .addUserMessage("Search for comprehensive information about quantum computing breakthroughs in 2025")
            .addMessage(response)
            .addTool(WebSearchTool20250305.builder()
                .maxUses(10L)
                .build())
            .build();

        Message continuation = client.messages().create(continuationParams);
        IO.println(continuation);
    } else {
        IO.println(response);
    }
}
```

```php PHP hidelines={1..6}
<?php

use Anthropic\Client;

$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));

$response = $client->messages->create(
    maxTokens: 1024,
    messages: [
        [
            'role' => 'user',
            'content' => 'Search for comprehensive information about quantum computing breakthroughs in 2025'
        ]
    ],
    model: 'claude-opus-4-7',
    tools: [
        [
            'type' => 'web_search_20250305',
            'name' => 'web_search',
            'max_uses' => 10
        ]
    ],
);

if ($response->stopReason === '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(
        maxTokens: 1024,
        messages: $messages,
        model: 'claude-opus-4-7',
        tools: [
            [
                'type' => 'web_search_20250305',
                'name' => 'web_search',
                'max_uses' => 10
            ]
        ],
    );

    echo $continuation;
} else {
    echo $response;
}
```

```ruby Ruby
require "anthropic"

client = Anthropic::Client.new

response = client.messages.create(
  model: "claude-opus-4-7",
  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
    }
  ]
)

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-7",
    max_tokens: 1024,
    messages: messages,
    tools: [
      {
        type: "web_search_20250305",
        name: "web_search",
        max_uses: 10
      }
    ]
  )

  puts continuation
else
  puts response
end
```
</CodeGroup>

处理 `pause_turn` 时：
- **继续对话：** 在后续请求中原样传回暂停的响应，让 Claude 继续其轮次
- **按需修改：** 你可以选择在继续之前修改内容，以中断或重定向对话
- **保留工具状态：** 在续接请求中包含相同的工具以维持功能

## ZDR 和 allowed_callers

Web search（`web_search_20250305`）和 web fetch（`web_fetch_20250910`）的基本版本符合[零数据留存 (ZDR)](/docs/en/manage-claude/api-and-data-retention) 条件。

带动态过滤的 `_20260209` 版本**默认**不符合 ZDR 条件，因为动态过滤内部依赖代码执行。

要在 ZDR 下使用 `_20260209` 服务器工具，请通过在工具上设置 `"allowed_callers": ["direct"]` 来禁用动态过滤：

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

这将工具限制为仅直接调用，绕过内部代码执行步骤。

<Note>
即使 web fetch 在符合 ZDR 的配置中使用，网站发布者仍可能保留 Claude 从其网站获取内容时传递给 URL 的任何参数。
</Note>

## 域名过滤

访问网络的服务器工具接受 `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` 工具错误。

<Note>
请求级域名限制必须与 Claude Console 中配置的组织级域名限制兼容。请求级域名只能进一步限制域名，不能覆盖或扩展超出组织级列表。如果你的请求包含与组织设置冲突的域名，API 会返回验证错误。
</Note>

<Warning>
请注意，域名中的 Unicode 字符可能通过同形攻击创建安全漏洞，其中来自不同脚本的视觉相似字符可以绕过域名过滤器。例如，`аmazon.com`（使用西里尔字母 'а'）可能看起来与 `amazon.com` 完全相同，但代表不同的域名。

配置域名允许/阻止列表时：
- 尽可能使用纯 ASCII 域名
- 考虑 URL 解析器可能以不同方式处理 Unicode 规范化
- 用潜在的同形变体测试你的域名过滤器
- 定期审计你的域名配置以查找可疑的 Unicode 字符
</Warning>

## 使用代码执行进行动态过滤

Web search 和 web fetch 的 `_20260209` 版本内部使用代码执行来对搜索结果应用动态过滤器。

<Warning>
将独立的 `code_execution` 工具与 `_20260209` 版本的 web 工具一起使用会创建两个执行环境，这可能会使模型困惑。使用其中一种，或将两者都固定到同一版本。
</Warning>

## 流式传输服务器工具事件

服务器工具事件作为正常 SSE 流的一部分进行流式传输。`server_tool_use` 块及其结果以 `content_block_start` 和 `content_block_delta` 事件到达，与文本和客户端工具调用的流式传输方式相同。

完整的事件参考参见[流式传输](/docs/en/build-with-claude/streaming)。各个工具页面记录了不同的工具特定事件名称。

## 批量请求

所有服务器工具都支持批处理。参见[批处理](/docs/en/build-with-claude/batch-processing)。

## 下一步

<CardGroup cols={2}>
  <Card title="Web search" icon="magnifying-glass" href="/docs/en/agents-and-tools/tool-use/web-search-tool">
    搜索网络并引用结果。
  </Card>
  <Card title="Web fetch" icon="globe" href="/docs/en/agents-and-tools/tool-use/web-fetch-tool">
    从特定 URL 检索内容。
  </Card>
  <Card title="Code execution" icon="terminal" href="/docs/en/agents-and-tools/tool-use/code-execution-tool">
    在沙箱容器中运行 Python。
  </Card>
  <Card title="Tool search" icon="list-magnifying-glass" href="/docs/en/agents-and-tools/tool-use/tool-search-tool">
    按需发现和加载工具。
  </Card>
</CardGroup>