跳到正文

Claude 开发者平台推出高级工具使用功能

Anthropic Engineering作者：Anthropic
阅读 0—
打开原文
本文目录文章开头

AI 智能体的未来在于模型能够无缝地跨数百或数千个工具协同工作。一个集成了 git 操作、文件操作、包管理器、测试框架和部署流水线的 IDE 助手。一个同时连接 Slack、GitHub、Google Drive、Jira、公司数据库以及数十个 MCP 服务器的运营协调器。

要构建高效的智能体，它们需要能够使用无限的工具库，而不必将每个定义都预先塞入上下文。我们关于在 MCP 中使用代码执行的博客文章讨论了工具结果和定义如何有时会在智能体读取请求之前就消耗 50,000 多个 token。智能体应按需发现和加载工具，仅保留与当前任务相关的内容。

智能体还需要从代码中调用工具的能力。使用自然语言工具调用时，每次调用都需要一次完整的推理过程，而中间结果无论是否有用都会堆积在上下文中。代码天然适合编排逻辑，例如循环、条件判断和数据转换。智能体需要根据手头的任务灵活选择代码执行或推理。

智能体还需要从示例中学习正确的工具用法，而不仅仅是 schema 定义。JSON schema 定义了什么是结构上有效的，但无法表达使用模式：何时包含可选参数、哪些组合是合理的，或者你的 API 期望遵循什么约定。

今天，我们发布了三个使这成为可能的功能：

  • 工具搜索工具（Tool Search Tool），它允许 Claude 使用搜索工具访问数千个工具，而无需消耗其上下文窗口
  • 程序化工具调用（Programmatic Tool Calling），它允许 Claude 在代码执行环境中调用工具，从而减少对模型上下文窗口的影响
  • 工具使用示例（Tool Use Examples），它提供了一个通用标准，用于演示如何有效地使用给定工具

在内部测试中，我们发现这些功能帮助我们构建了使用传统工具使用模式无法实现的东西。例如，Claude for Excel 使用程序化工具调用来读取和修改拥有数千行的电子表格，而不会使模型的上下文窗口过载。

根据我们的经验，我们相信这些功能为你可以用 Claude 构建的东西开辟了新的可能性。

Video thumbnail

工具搜索工具

挑战

MCP 工具定义提供了重要的上下文，但随着更多服务器的连接，这些 token 会不断累积。考虑一个五服务器的配置：

  • GitHub：35 个工具（约 26K token）
  • Slack：11 个工具（约 21K token）
  • Sentry：5 个工具（约 3K token）
  • Grafana：5 个工具（约 3K token）
  • Splunk：2 个工具（约 2K token）

这意味着在对话甚至开始之前，58 个工具就消耗了大约 55K token。再添加更多服务器，比如 Jira（仅它就使用约 17K token），你很快就会接近 100K+ 的 token 开销。在 Anthropic，我们看到工具定义在优化前消耗了 134K token。

但 token 成本并不是唯一的问题。最常见的失败是工具选择错误和参数不正确，尤其是当工具名称相似时，比如 notification-send-user 与 notification-send-channel。

我们的解决方案

工具搜索工具不是预先加载所有工具定义，而是按需发现工具。Claude 只会看到当前任务实际需要的工具。

Tool Search Tool diagram

与 Claude 的传统方法相比，工具搜索工具保留了 191,300 个 token 的上下文，而传统方法仅保留 122,800 个 token。

传统方法：

  • 所有工具定义预先加载（50 多个 MCP 工具约 72K 令牌）
  • 对话历史和系统提示词争夺剩余空间
  • 总上下文消耗：在开始任何工作之前约 77K 令牌

使用工具搜索工具时：

  • 仅预先加载工具搜索工具（约 500 令牌）
  • 按需发现工具（3-5 个相关工具，约 3K 令牌）
  • 总上下文消耗：约 8.7K 令牌，保留了 95% 的上下文窗口

这代表了 85% 的令牌使用量减少，同时保持对完整工具库的访问。内部测试显示，在处理大型工具库时，启用工具搜索工具后 MCP 评估的准确性有显著提升。Opus 4 从 49% 提升到 74%，Opus 4.5 从 79.5% 提升到 88.1%。

工具搜索工具的工作原理

工具搜索工具让 Claude 动态发现工具，而不是预先加载所有定义。你将所有工具定义提供给 API，但用 defer_loading: true 标记工具以使其可按需发现。延迟加载的工具最初不会加载到 Claude 的上下文中。Claude 只能看到工具搜索工具本身以及带有 defer_loading: false 的工具（你最关键、最常用的工具）。

当 Claude 需要特定功能时，它会搜索相关工具。工具搜索工具返回匹配工具的引用，这些引用会在 Claude 的上下文中展开为完整定义。

例如，如果 Claude 需要与 GitHub 交互，它会搜索 "github"，然后只有 github.createPullRequest 和 github.listIssues 被加载——而不是你来自 Slack、Jira 和 Google Drive 的其他 50 多个工具。

这样，Claude 可以访问你的完整工具库，同时只为它实际需要的工具支付令牌成本。

提示词缓存说明：工具搜索工具不会破坏提示词缓存，因为延迟加载的工具完全被排除在初始提示词之外。它们只在 Claude 搜索之后才添加到上下文中，因此你的系统提示词和核心工具定义保持可缓存状态。

实现方式：

{
  "tools": [
    // Include a tool search tool (regex, BM25, or custom)
    {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},

    // Mark tools for on-demand discovery
    {
      "name": "github.createPullRequest",
      "description": "Create a pull request",
      "input_schema": {...},
      "defer_loading": true
    }
    // ... hundreds more deferred tools with defer_loading: true
  ]
}

对于 MCP 服务器，你可以延迟加载整个服务器，同时保持特定的高使用率工具处于加载状态：

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-drive",
  "default_config": {"defer_loading": true}, # defer loading the entire server
  "configs": {
    "search_files": {
"defer_loading": false
    }  // Keep most used tool loaded
  }
}

Claude 开发者平台开箱即用地提供了基于正则表达式和基于 BM25 的搜索工具，但你也可以使用嵌入或其他策略实现自定义搜索工具。

何时使用工具搜索工具

与任何架构决策一样，启用工具搜索工具涉及权衡。该功能在工具调用之前增加了一个搜索步骤，因此当上下文节省和准确性提升超过额外延迟时，它能带来最佳的投资回报。

适用场景：

  • 工具定义消耗 >10K 令牌
  • 遇到工具选择准确性问题
  • 构建具有多个服务器的 MCP 驱动系统
  • 可用工具 10 个以上

收益较低的场景：

  • 小型工具库（<10 个工具）
  • 所有工具在每个会话中都频繁使用
  • 工具定义很紧凑

程序化工具调用

挑战

随着工作流变得越来越复杂，传统工具调用会产生两个根本性问题：

  • 中间结果导致的上下文污染：当 Claude 分析一个 10MB 的日志文件以查找错误模式时，整个文件都会进入其上下文窗口，即使 Claude 只需要错误频率的摘要。当跨多个表获取客户数据时，每条记录都会累积在上下文中，无论其相关性如何。这些中间结果会消耗大量的令牌预算，并可能将重要信息完全挤出上下文窗口。
  • 推理开销与人工综合：每次工具调用都需要完整的模型推理过程。收到结果后，Claude 必须“肉眼”查看数据以提取相关信息，推理各部分如何关联，并决定下一步做什么——全部通过自然语言处理完成。一个五步工具工作流意味着五次推理过程，外加 Claude 解析每个结果、比较数值并综合结论。这既缓慢又容易出错。

我们的解决方案

程序化工具调用（Programmatic Tool Calling）使 Claude 能够通过代码而非单独的 API 往返来编排工具。Claude 不再逐个请求工具并将每个结果返回到其上下文中，而是编写代码来调用多个工具、处理它们的输出，并控制哪些信息实际进入其上下文窗口。

Claude 擅长编写代码，通过让它用 Python 而非自然语言工具调用来表达编排逻辑，你可以获得更可靠、更精确的控制流。循环、条件、数据转换和错误处理在代码中都是显式的，而不是隐含在 Claude 的推理中。

示例：预算合规检查

考虑一个常见的业务任务：“哪些团队成员超出了他们的第三季度差旅预算？”

你有三个可用工具：

  • get_team_members(department) - 返回包含 ID 和级别的团队成员列表
  • get_expenses(user_id, quarter) - 返回某个用户的费用明细行
  • get_budget_by_level(level) - 返回某个员工级别的预算限额

传统方法：

  • 获取团队成员 → 20 人
  • 为每个人获取其第三季度费用 → 20 次工具调用，每次返回 50-100 行明细（机票、酒店、餐饮、收据）
  • 按员工级别获取预算限额
  • 所有这些都进入 Claude 的上下文：2,000 多条费用明细行（50 KB 以上）
  • Claude 手动汇总每个人的费用，查找其预算，将费用与预算限额进行比较
  • 更多与模型的往返，大量上下文消耗

使用程序化工具调用：

Claude 不再接收每个工具结果，而是编写一个 Python 脚本来编排整个工作流。该脚本在代码执行工具（一个沙盒环境）中运行，当需要你的工具的结果时会暂停。当你通过 API 返回工具结果时，它们由脚本处理，而不是被模型消耗。脚本继续执行，Claude 只看到最终输出。

Programmatic tool calling flow

程序化工具调用使 Claude 能够通过代码而非单独的 API 往返来编排工具，从而允许并行工具执行。

以下是 Claude 为预算合规任务编排的代码示例：

team = await get_team_members("engineering")

# Fetch budgets for each unique level
levels = list(set(m["level"] for m in team))
budget_results = await asyncio.gather(*[
    get_budget_by_level(level) for level in levels
])

# Create a lookup dictionary: {"junior": budget1, "senior": budget2, ...}
budgets = {level: budget for level, budget in zip(levels, budget_results)}

# Fetch all expenses in parallel
expenses = await asyncio.gather(*[
    get_expenses(m["id"], "Q3") for m in team
])

# Find employees who exceeded their travel budget
exceeded = []
for member, exp in zip(team, expenses):
    budget = budgets[member["level"]]
    total = sum(e["amount"] for e in exp)
    if total > budget["travel_limit"]:
        exceeded.append({
            "name": member["name"],
            "spent": total,
            "limit": budget["travel_limit"]
        })

print(json.dumps(exceeded))

Claude 的上下文只接收最终结果：超出预算的两到三个人。2,000 多条明细行、中间汇总和预算查找不会影响 Claude 的上下文，将消耗从 200KB 的原始费用数据减少到仅 1KB 的结果。

效率提升是巨大的：

  • Token 节省：通过将中间结果排除在 Claude 的上下文之外，PTC 大幅减少了 token 消耗。在复杂研究任务中，平均使用量从 43,588 个 token 降至 27,297 个，减少了 37%。
  • 降低延迟：每次 API 往返都需要模型推理（数百毫秒到数秒）。当 Claude 在单个代码块中编排 20 多次工具调用时，你消除了 19 次以上的推理过程。API 处理工具执行，而无需每次都返回模型。
  • 准确性提升：通过编写显式的编排逻辑，Claude 在处理多个工具结果时出错更少，相比用自然语言处理要好。内部知识检索从 25.6% 提升到 28.5%；GIA 基准测试从 46.5% 提升到 51.2%。

生产工作流涉及杂乱的数据、条件逻辑以及需要扩展的操作。程序化工具调用让 Claude 以编程方式处理这些复杂性，同时将其重点放在可执行的结果上，而非原始数据处理上。

程序化工具调用的工作原理

1. 将工具标记为可从代码调用

在工具中添加 code_execution，并设置 allowed_callers 以选择启用程序化执行的工具：

{
  "tools": [
    {
      "type": "code_execution_20250825",
      "name": "code_execution"
    },
    {
      "name": "get_team_members",
      "description": "Get all members of a department...",
      "input_schema": {...},
      "allowed_callers": ["code_execution_20250825"] # opt-in to programmatic tool calling
    },
    {
      "name": "get_expenses",
 	...
    },
    {
      "name": "get_budget_by_level",
	...
    }
  ]
}

API 会将这些工具定义转换为 Claude 可以调用的 Python 函数。

2. Claude 编写编排代码

Claude 不再逐个请求工具，而是生成 Python 代码：

{
  "type": "server_tool_use",
  "id": "srvtoolu_abc",
  "name": "code_execution",
  "input": {
    "code": "team = get_team_members('engineering')\n..." # the code example above
  }
}

3. 工具执行时不占用 Claude 的上下文

当代码调用 get_expenses() 时，你会收到一个带有 caller 字段的工具请求：

{
  "type": "tool_use",
  "id": "toolu_xyz",
  "name": "get_expenses",
  "input": {"user_id": "emp_123", "quarter": "Q3"},
  "caller": {
    "type": "code_execution_20250825",
    "tool_id": "srvtoolu_abc"
  }
}

你提供结果，该结果在代码执行环境中处理，而不是在 Claude 的上下文中处理。这个请求-响应循环会在代码中的每次工具调用时重复。

4. 只有最终输出进入上下文

当代码运行完成时，只有代码的结果会返回给 Claude：

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_abc",
  "content": {
    "stdout": "[{\"name\": \"Alice\", \"spent\": 12500, \"limit\": 10000}...]"
  }
}

这就是 Claude 看到的全部内容，而不是沿途处理的 2000 多条费用明细。

何时使用程序化工具调用

程序化工具调用为你的工作流增加了一个代码执行步骤。当节省的 token、延迟的改善和准确性的提升足够显著时，这种额外开销是值得的。

在以下情况下最有益：

  • 处理大型数据集，而你只需要聚合结果或摘要
  • 运行包含三个或更多依赖工具调用的多步骤工作流
  • 在 Claude 看到之前对工具结果进行过滤、排序或转换
  • 处理中间数据不应影响 Claude 推理的任务
  • 跨多个项目运行并行操作（例如检查 50 个端点）

在以下情况下收益较小：

  • 进行简单的单工具调用
  • 在 Claude 需要查看并推理所有中间结果的任务上工作
  • 运行响应较小的快速查询

工具使用示例

挑战

JSON Schema 擅长定义结构——类型、必填字段、允许的枚举——但它无法表达使用模式：何时包含可选参数、哪些组合是合理的，或者你的 API 期望遵循什么约定。

以一个支持工单 API 为例：

{
  "name": "create_ticket",
  "input_schema": {
    "properties": {
      "title": {"type": "string"},
      "priority": {"enum": ["low", "medium", "high", "critical"]},
      "labels": {"type": "array", "items": {"type": "string"}},
      "reporter": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "name": {"type": "string"},
          "contact": {
            "type": "object",
            "properties": {
              "email": {"type": "string"},
              "phone": {"type": "string"}
            }
          }
        }
      },
      "due_date": {"type": "string"},
      "escalation": {
        "type": "object",
        "properties": {
          "level": {"type": "integer"},
          "notify_manager": {"type": "boolean"},
          "sla_hours": {"type": "integer"}
        }
      }
    },
    "required": ["title"]
  }
}

该模式定义了什么是有效的，但留下了关键问题未得到解答：

  • 格式歧义：due_date 应使用 "2024-11-06"、"Nov 6, 2024" 还是 "2024-11-06T00:00:00Z"？
  • ID 约定：reporter.id 是 UUID、"USR-12345" 还是仅 "12345"？
  • 嵌套结构用法：Claude 应何时填充 reporter.contact？
  • 参数关联：escalation.level 和 escalation.sla_hours 与优先级有何关系？

这些歧义可能导致格式错误的工具调用和不一致的参数使用。

我们的解决方案

工具使用示例让你可以直接在工具定义中提供示例工具调用。你不再仅依赖模式，而是向 Claude 展示具体的使用模式：

{
    "name": "create_ticket",
    "input_schema": { /* same schema as above */ },
    "input_examples": [
      {
        "title": "Login page returns 500 error",
        "priority": "critical",
        "labels": ["bug", "authentication", "production"],
        "reporter": {
          "id": "USR-12345",
          "name": "Jane Smith",
          "contact": {
            "email": "jane@acme.com",
            "phone": "+1-555-0123"
          }
        },
        "due_date": "2024-11-06",
        "escalation": {
          "level": 2,
          "notify_manager": true,
          "sla_hours": 4
        }
      },
      {
        "title": "Add dark mode support",
        "labels": ["feature-request", "ui"],
        "reporter": {
          "id": "USR-67890",
          "name": "Alex Chen"
        }
      },
      {
        "title": "Update API documentation"
      }
    ]
  }

通过这三个示例，Claude 学会了：

  • 格式约定：日期使用 YYYY-MM-DD，用户 ID 遵循 USR-XXXXX，标签使用 kebab-case
  • 嵌套结构模式：如何构建 reporter 对象及其嵌套的 contact 对象
  • 可选参数关联：严重错误包含完整联系信息和升级流程，并有严格的 SLA；功能请求包含报告人但没有联系/升级信息；内部任务只有标题

在我们自己的内部测试中，工具使用示例将复杂参数处理的准确率从 72% 提高到 90%。

何时使用工具使用示例

工具使用示例会为你的工具定义增加 token，因此当准确率的提升超过额外成本时，它们最有价值。

在以下情况下最有益：

  • 复杂的嵌套结构，其中有效的 JSON 并不意味着正确的使用方式
  • 具有许多可选参数且包含模式很重要的工具
  • 具有未在 schema 中体现的领域特定约定的 API
  • 相似的工具，示例可以澄清应使用哪一个（例如 create_ticket 与 create_incident）

在以下情况下收益较小：

  • 使用方式显而易见的简单单参数工具
  • Claude 已经理解的标准格式，如 URL 或电子邮件
  • 更适合通过 JSON Schema 约束处理的验证问题

最佳实践

构建执行真实世界操作的智能体意味着要同时处理规模、复杂性和精确性。这三个功能协同工作，以解决工具使用工作流中的不同瓶颈。以下是有效结合它们的方法。

分层使用功能

并非每个智能体在给定任务中都需要使用所有三个功能。从你最大的瓶颈开始：

  • 工具定义导致的上下文膨胀 → 工具搜索工具
  • 大型中间结果污染上下文 → 编程式工具调用
  • 参数错误和格式错误的调用 → 工具使用示例

这种有针对性的方法让你能够解决限制智能体性能的具体约束，而不是一开始就增加复杂性。

然后根据需要分层添加其他功能。它们是互补的：工具搜索工具确保找到正确的工具，编程式工具调用确保高效执行，工具使用示例确保正确调用。

设置工具搜索工具以获得更好的发现

工具搜索会匹配名称和描述，因此清晰、描述性的定义可提高发现准确性。

// Good
{
    "name": "search_customer_orders",
    "description": "Search for customer orders by date range, status, or total amount. Returns order details including items, shipping, and payment info."
}

// Bad
{
    "name": "query_db_orders",
    "description": "Execute order query"
}

添加系统提示指导，让 Claude 知道有哪些可用：

You have access to tools for Slack messaging, Google Drive file management, 
Jira ticket tracking, and GitHub repository operations. Use the tool search 
to find specific capabilities.

将你最常用的三到五个工具始终保持加载，其余的延迟加载。这在常见操作的即时访问与其他所有内容的按需发现之间取得了平衡。

设置编程式工具调用以实现正确执行

由于 Claude 编写代码来解析工具输出，因此请清晰地记录返回格式。这有助于 Claude 编写正确的解析逻辑：

{
    "name": "get_orders",
    "description": "Retrieve orders for a customer.
Returns:
    List of order objects, each containing:
    - id (str): Order identifier
    - total (float): Order total in USD
    - status (str): One of 'pending', 'shipped', 'delivered'
    - items (list): Array of {sku, quantity, price}
    - created_at (str): ISO 8601 timestamp"
}

参见下方可从编程式编排中受益的可选加入工具：

  • 可以并行运行的工具（独立操作）
  • 可以安全重试的操作（幂等）

设置工具使用示例以提高参数准确性

为行为清晰度精心设计示例：

  • 使用真实数据（真实的城市名称、合理的价格，而不是 "string" 或 "value"）
  • 展示多样性，包括最小、部分和完整规范模式
  • 保持简洁：每个工具 1-5 个示例
  • 聚焦于歧义（仅在从 schema 中无法明显看出正确使用方式时才添加示例）

入门

这些功能目前处于 beta 版。要启用它们，请添加 beta 标头并包含你需要的工具：

client.beta.messages.create(
    betas=["advanced-tool-use-2025-11-20"],
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    tools=[
        {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
        {"type": "code_execution_20250825", "name": "code_execution"},
        # Your tools with defer_loading, allowed_callers, and input_examples
    ]
)

有关详细的 API 文档和 SDK 示例，请参阅我们的：

这些特性使工具使用从简单的函数调用迈向智能编排。随着智能体处理跨越数十种工具和大型数据集的更复杂工作流，动态发现、高效执行和可靠调用成为基础能力。

我们很期待看到你构建的作品。

阅读显示设置

调整正文排版

当前浏览器记住选择，应用于文章正文。手机上正文宽度以屏幕可用空间为限。

图表完整性提示

普通文章遇到图表保存问题时显示提示。