Skip to content

Claude 工具调用（Tools）

Claude 系列模型在本平台通过 Anthropic Messages 接口 (POST /v1/messages) 和 OpenAI 兼容接口 (POST /v1/chat/completions) 支持工具调用。常见能力包括：

  • 联网搜索（Web Search）：让 Claude 直接访问实时网页内容，回答时效性问题并自动引用来源。
  • 自定义函数（Function Calling）：让模型调用你的业务接口（查天气、查订单等）。

本文重点介绍 在 New-API 平台下，如何为 Claude 启用联网搜索工具。

官方参考

Web Search 工具 让 Claude 直接使用实时网络内容，从而： - 回答最新信息：不受模型知识截止日期限制，可回答近期事件、股价、天气等。 - 自动引用来源：回答中会包含对搜索结果的引用（citations），便于用户核实。

1. 使用 OpenAI 兼容接口（推荐）

如果你使用 OpenAI 格式的库（如 openai-python）或者直接调用 /v1/chat/completions，可以通过顶级参数 web_search_options 或在 tools 数组中使用 web_search_preview 启用联网搜索。这是在 New-API 平台触发 Claude 联网搜索最简便且通用的方式。

方式 A：顶级参数 (推荐)

curl https://api-cs-al.naci-tech.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "claude-3-5-sonnet",
    "messages": [
      { "role": "user", "content": "纽约现在天气怎么样？" }
    ],
    "web_search_options": {
      "search_context_size": "medium"
    }
  }'

方式 B：OpenAI 风格 Tools 数组

{
  "model": "claude-3-5-sonnet",
  "messages": [...],
  "tools": [{ "type": "web_search_preview" }],
  "tool_choice": "auto"
}

关键参数说明： - web_search_options: 包含搜索配置的对象。 - search_context_size: 可选，控制搜索结果注入上下文的大小（low, medium, high）。默认为 medium。 - web_search_preview: OpenAI 风格的内置搜索工具类型名。

2. 使用 Anthropic 原生接口 (/v1/messages)

如果你直接使用 Anthropic 风格的接口，需在 tools 数组中显式定义 web_search 工具。

请求示例 (curl)：推荐使用 web_search_20250305

curl https://api-cs-al.naci-tech.com/v1/messages \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "纽约现在天气怎么样？"
      }
    ],
    "tools": [
      {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 5
      }
    ]
  }'

💡 常见调用失败排查： 1. 必须包含 max_uses: Anthropic 接口要求显式提供此参数（如 5），否则可能报错。 2. 工具名称固定: name 必须严格设置为 "web_search"。 3. 版本选择: 本平台经 Bedrock 转发时，请优先使用 web_search_20250305。若使用 web_search_20260209，部分后端（如 Bedrock）会要求工具带 input_schema，可能报错 custom.input_schema: Field required。 4. 若仍报 input_schema: Field required：说明请求被转发到 Bedrock，且该后端要求工具定义中包含 input_schema。可尝试为 web_search 工具补充以下字段后再请求：

"tools": [
  {
    "type": "web_search_20250305",
    "name": "web_search",
    "max_uses": 5,
    "input_schema": {
      "type": "object",
      "properties": {
        "query": { "type": "string", "description": "Search query" }
      }
    }
  }
]

若问题依旧，建议改用 OpenAI 兼容接口（见上文「使用 OpenAI 兼容接口」）通过 web_search_options 或 tools: [{ "type": "web_search_preview" }] 启用联网搜索，可避免后端差异。

3. 支持的模型

联网搜索适用于多款 Claude 模型（以平台实际支持为准）：

  • Claude 3.5 / 3.7: claude-3-5-sonnet, claude-3-7-sonnet 等。
  • Claude 4.x (Opus/Sonnet/Haiku): claude-opus-4-6, claude-sonnet-4.5 等。

4. 工具版本说明

  • web_search_20250305: 基础联网搜索，常用且稳定；经 Bedrock 转发时推荐使用此版本，避免 input_schema 相关校验错误。
  • web_search_20260209: 支持**动态过滤**（需同时启用 Code Execution 工具），适合技术文档检索等。仅适用于 Claude 4.6 系列模型。注意：本平台若将请求转发至 AWS Bedrock，该版本可能因缺少 input_schema 报错，此时请改用 web_search_20250305 或使用 OpenAI 兼容接口的 web_search_preview。

5. 高级工具参数（仅原生接口）

参数 类型 说明
max_uses 整数 单次请求内最多执行几次搜索，例如 5；超限会返回 max_uses_exceeded 错误
allowed_domains 数组 仅允许从这些域名返回结果，如 ["wikipedia.org"]，不要带 https://
blocked_domains 数组 排除这些域名的结果；与 allowed_domains 不能同时使用
user_location 对象 用于本地化结果，可包含 city, region, country, timezone

6. 响应结构与引用 (Citations)

启用联网搜索后，Claude 的回答中会包含 citations 数组。展示给用户时，应保留或适当呈现这些来源，以符合官方标注要求。

响应示例 (原生接口):

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "根据查询结果，纽约今天……",
      "citations": [
        {
          "type": "web_search_result_location",
          "url": "https://weather.com/...",
          "title": "New York Weather",
          "cited_text": "..."
        }
      ]
    }
  ]
}

🧩 自定义函数（Function Calling）

若需要 Claude 调用你自己的接口（数据库、订单系统等），请在 tools 中定义 input_schema。完整流程见：Anthropic 对话格式（Messages） 中的「工具调用」章节。

🔗 相关文档