跳到主要内容

Anthropic Server-side Tools

Claude 独有的「服务端工具」机制 —— 工具在 Anthropic 后端执行,响应里直接返回结果 block 与引用,客户端无需自己编排工具调用 → 工具结果 → 模型再调用的循环。其他厂商的工具调用都需要客户端执行后回传 tool_result。

当前可用 Server-side Tools​

工具类型字段用途
web_search_20250305tools[*].typeAnthropic 后端自动联网搜索并把结果作为引用注入

平台后续接入新增的 server-side tool 会同样在此列出。

适用接口与模型​

  • 接口:v1/messages(Anthropic 原生协议,推荐)/ v1/chat/completions(透传)
  • 适用模型:以 模型目录 → Claude 中的 Server-side Tools / Web Search 标记为准。

触发参数​

tools  数组,每项形如:
       {
         "type": "web_search_20250305",
         "name": "web_search",
         "max_uses": <int, 单次请求最多调用次数>
       }

响应结构(v1/messages)​

服务端工具命中后,响应的 content[] 数组里会按顺序出现以下 block:

  1. server_tool_use —— 平台代为发起的工具调用记录
  2. web_search_tool_result —— 工具返回的结果(含搜索结果列表)
  3. 带 citations 字段的 text block —— 模型基于结果合成的最终答案,每段引用都可追溯到 web_search_tool_result 中的具体来源
{
  "content": [
    {
      "type": "server_tool_use",
      "id": "srvtoolu_xxx",
      "name": "web_search",
      "input": {"query": "今日上证指数收盘价"}
    },
    {
      "type": "web_search_tool_result",
      "tool_use_id": "srvtoolu_xxx",
      "content": [
        {"type": "web_search_result", "url": "...", "title": "...", "encrypted_content": "..."}
      ]
    },
    {
      "type": "text",
      "text": "根据 ... 报道,...",
      "citations": [
        {"type": "web_search_result_location", "url": "...", "title": "...", "cited_text": "..."}
      ]
    }
  ]
}

示例​

curl $TURING_BASE_URL/messages \
  -H "Authorization: Bearer $TURING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "turing/claude-sonnet-5",
    "max_tokens": 4096,
    "messages": [{"role": "user", "content": "今日上证指数收盘价?"}],
    "tools": [{
      "type": "web_search_20250305",
      "name": "web_search",
      "max_uses": 3
    }]
  }'

计费​

  • web_search_20250305 调用次数计入 usage.server_tool_use.web_search_requests,平台按 $10 / 1K requests 计费
  • 响应里的 text block(模型合成答案)按标准 output token 计费
  • web_search_tool_result 中的搜索结果计入 input token(下一轮如果保留这些 block 在 messages 中,会重复计费)

与客户端工具(client-side tool use)的对比​

维度Client-side(tools + function)Server-side(tools[*].type: web_search_20250305)
谁执行工具客户端代码Anthropic 后端
多轮编排客户端必须收 tool_use → 回传 tool_result单次请求内完成,无需多轮
工具范围任意自定义 function仅 Anthropic 提供的内置 server tool
引用 / Citations自定义自动 citations 字段
接口两个协议都行同样两个协议都行,但 v1/messages 字段更原生

注意事项​

  • 多轮中保留 server tool block:把 server_tool_use / web_search_tool_result 保留在后续轮次的 messages 里,模型可以回顾上次搜索结果;但这些 block 会计入 input tokens。
  • max_uses 控费:同一请求内最大搜索次数硬上限,超出会停止调用并返回当前已有结果。
  • 协议差异:v1/chat/completions 协议下 server tool 字段同样透传,但响应里 content block 结构会被压扁为 string,citations 信息可能丢失。需要完整 citations 体验请走 v1/messages。

相关文档​