【翻译】介绍下在 Claude 开发者平台上最新的3个功能

本文是我对英文原版文章的翻译，一是为了看最新的技术，二是提高自己的英文水平。

原文地址：www.anthropic.com/engineering...

以下是翻译内容：

我们添加了三个新的beta功能，让Claude可以动态地发现、学习和执行工具。这是他们的工作方式。

人工智能代理的未来是模型在数百或数千种工具中无缝工作的一个阶段。集成了git操作、文件操作、包管理器、测试框架和部署管道的IDE助手。运营协调员，可同时连接Slack、GitHub、Google Drive、Jira、公司数据库和数十个MCP服务器。

至构建有效的代理,他们需要使用无限的工具库，而无需预先将每个定义填充到上下文中。我们的博客文章使用使用MCP执行代码讨论了在代理读取请求之前，工具结果和定义有时如何消耗50，000多个令牌。代理应按需发现和加载工具，仅保留与当前任务相关的内容。

代理还需要能够从代码中调用工具。当使用自然语言工具调用时，每个调用都需要一个完整的推理传递，并且中间结果在上下文中堆积，无论它们是否有用。代码非常适合编排逻辑，例如循环、条件和数据转换。代理需要根据手头的任务灵活地在代码执行和推理之间进行选择。

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

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

• 工具搜索工具，它允许Claude使用搜索工具访问成千上万的工具，而无需使用其上下文窗口
• 编程工具调用,这允许Claude在代码执行环境中调用工具，从而减少对模型上下文窗口的影响
• 工具使用示例,它提供了一个通用标准，用于演示如何有效地使用给定的工具

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

根据我们的经验，我们相信这些功能为您可以使用Claude构建的内容开辟了新的可能性。

可通过视频查看：youtu.be/2MJDdzSXL74

第一个特性：工具搜索工具

挑战

MCP工具定义提供了重要的上下文，但随着更多的服务器连接，这些令牌可以加起来。考虑五个服务器的设置:

• GitHub: 35个工具 (约26k令牌)
• Slack: 11个工具 (约21k令牌)
• Sentry: 5个工具 (~ 3k令牌)
• Grafana: 5个工具 (〜3k令牌)
• Splunk: 2个工具 (~ 2k令牌)

在对话开始之前，有58个工具消耗了大约55k个令牌。添加更多像Jira这样的服务器 (仅使用〜17k令牌)，您很快就会接近100k + 令牌开销。在Anthropic，我们已经看到工具定义在优化之前消耗了134k令牌。

但代币成本并不是唯一的问题。最常见的故障是错误的工具选择和不正确的参数，尤其是当工具具有类似的名称时notification-send-uservs。notification-send-channel。

我们的解决方案

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

工具搜索工具保留了191，300个上下文令牌，而克劳德的传统方法为122，800个。

传统方法:

• 前期加载的所有工具定义 (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的上下文中。克劳德只看到工具搜索工具本身以及任何具有defer_loading: false(您最重要的，经常使用的工具)。

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

例如，如果Claude需要与GitHub交互，它会搜索 "github"，并且只github.createPullRequest和github.listIssues获取加载-不是你的其他50 + 工具从Slack，Jira和谷歌驱动器。

这样，克劳德可以访问您的完整工具库，而只支付实际需要的工具的令牌成本。

提示缓存备注:工具搜索工具不会中断提示缓存，因为延迟的工具完全从初始提示中排除。它们仅在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-based搜索工具，但您也可以使用嵌入或其他策略实现自定义搜索工具。

何时使用工具搜索工具

与任何架构决策一样，启用工具搜索工具也需要权衡。该功能在工具调用之前添加了一个搜索步骤，因此当上下文节省和准确性改进超过额外的延迟时，它可以提供最佳的ROI。

使用它时:

• 消耗> 10k令牌的工具定义
• 遇到工具选择准确性问题
• 构建具有多个服务器的MCP供电系统
• 10 + 可用工具

在以下情况下不太有利:

• 小型工具库 (<10个工具)

• 在每个会话中经常使用的所有工具

• 工具定义紧凑

第二个：编程工具调用

挑战

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

• 来自中间结果的上下文污染: 当Claude分析10MB日志文件的错误模式时，整个文件会进入其上下文窗口，尽管Claude只需要错误频率的摘要。在多个表中获取客户数据时，无论相关性如何，每个记录都会在上下文中累积。这些中间结果消耗大量令牌预算，并且可以将重要信息完全推出上下文窗口。
• 推理开销和手动合成: 每次工具调用都需要完整的模型推理传递。收到结果后，克劳德必须 "关注" 数据以提取相关信息，推理出各个部分如何组合在一起，并决定下一步要做什么-所有这些都是通过自然语言处理完成的。五个工具工作流意味着五个推理过程加上Claude解析每个结果，比较值和合成结论。这既慢又容易出错。

我们的解决方案

编程工具调用使Claude能够通过代码而不是通过单个API往返来编排工具。克劳德不是一次请求一个工具，每个结果都返回到它的上下文，而是编写调用多个工具的代码，处理它们的输出，并控制哪些信息实际进入它的上下文窗口。

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

示例: 预算合规性检查

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

您有三个可用的工具:

• get_team_members(department)-返回具有id和级别的团队成员列表
• get_expenses(user_id, quarter)-返回用户的费用行项目
• get_budget_by_level(level)-返回员工级别的预算限制

传统方法:

• 获取团队成员 → 20人
• 对于每个人，获取他们的Q3费用 → 20个工具电话，每个返回50-100行项目 (航班，酒店，膳食，收据)
• 按员工级别提取预算限制
• 所有这些都进入了克劳德的上下文: 2，000 + 费用线项目 (50 KB +)
• 克劳德手动计算每个人的费用，查找他们的预算，将费用与预算限制进行比较
• 更多的往返模型，大量的上下文消耗

使用编程工具调用:

而不是每个工具的结果返回给克劳德，克劳德写了一个Python脚本，协调整个工作流程。脚本在代码执行工具 (沙盒环境) 中运行，在需要工具的结果时暂停。当您通过API返回工具结果时，它们将由脚本处理，而不是由模型使用。脚本继续执行，Claude只看到最终输出。

编程工具调用使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))

克劳德的上下文只收到最终结果: 超出预算的两到三个人。2，000多个行项目，中间金额和预算查找不会影响Claude的上下文，从而将消耗从200KB的原始费用数据减少到仅1KB的结果。

效率的提高是巨大的:

• 代币储蓄: 通过将中间结果排除在Claude的上下文之外，PTC大大减少了令牌消耗。平均使用量从43，588个下降到27，297个，复杂的研究任务减少了37%。
• 减少延迟: 每个API往返需要模型推理 (数百毫秒到秒)。当Claude在单个代码块中协调20 + 个工具调用时，您可以消除19 + 个推理过程。API处理工具执行，每次都不返回模型。
• 提高精度通过编写显式的编排逻辑，克劳德比在自然语言中处理多个工具结果时犯的错误更少。内部知识检索从25.6% 提高到28.5%；GIA基准从46.5% 到51.2%。

生产工作流程涉及杂乱的数据、条件逻辑和需要扩展的操作。编程工具调用使Claude能够以编程方式处理这种复杂性，同时将重点放在可操作的结果而不是原始数据处理上。

编程工具调用的工作原理

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

将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函数。

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. 工具执行没有击中克劳德的上下文

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

{
  "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的上下文中处理的。对于代码中的每个工具调用，都会重复此请求-响应循环。

只有最终输出进入上下文

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

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

这就是克劳德所看到的，而不是沿途处理的2000多个费用线项目。

何时使用编程工具调用

编程工具调用将代码执行步骤添加到您的工作流。当令牌节省，延迟改进和准确性提高很大时，这种额外的开销会得到回报。

最有益的时候:

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

在以下情况下不太有利:

• 制作简单的单工具调用

• 处理克劳德应该看到和推理所有中间结果的任务

• 运行带有小响应的快速查找

第三个：工具使用示例

挑战

JSON模式擅长定义结构-类型，必填字段，允许的枚举-但它不能表达使用模式: 何时包含可选参数，哪些组合有意义，或者你的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" 、 "2024年11月6日" 或 "2024-11-06 t00: 00:00Z"？
• ID约定:是reporter.idUUID，"USR-12345"，或只是 "12345"？
• 嵌套结构用法:克劳德什么时候应该填充reporter.contact?
• 参数相关性:如何做escalation.level和escalation.sla_hours与优先级有关？

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

我们的解决方案

工具使用示例允许您直接在工具定义中提供示例工具调用。而不是单独依赖模式，你展示克劳德具体的使用模式:

{
    "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"
      }
    ]
  }

从这三个例子中，克劳德学到:

• 格式约定: 日期使用yyyy-mm-dd，用户id遵循usr-xxxxx，标签使用kebab-case
• 嵌套结构模式: 如何构造reporter对象及其嵌套的contact对象
• 可选参数相关性: 关键bug具有完整的联系信息 + 具有严格的sla的上报; 功能请求具有报告者，但没有联系人/上报; 内部任务仅具有标题

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

何时使用工具使用示例

工具使用示例将令牌添加到您的工具定义中，因此当准确性改进超过额外成本时，它们最有价值。

最有益的时候:

• 复杂的嵌套结构，其中有效的JSON并不意味着正确的用法
• 具有许多可选参数和包含模式的工具很重要
• 具有未在架构中捕获的域特定约定的api
• 类似的工具，其中示例阐明使用哪一个 (例如，create_ticketvscreate_incident)

在以下情况下不太有利:

• 具有明显用法的简单单参数工具
• Claude已经理解的标准格式，如url或电子邮件
• 验证问题通过JSON模式约束更好地处理

最佳实践

构建采取实际行动的代理意味着同时处理规模、复杂性和精确性。这三个功能共同解决了工具使用工作流中的不同瓶颈。以下是如何有效地结合它们。

分层、按需的使用功能

并非每个代理都需要使用给定任务的所有三个功能。从你最大的瓶颈开始:

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

这种集中的方法使您可以解决限制代理性能的特定约束，而不是预先增加复杂性。

然后根据需要分层附加特征。它们是互补的: 工具搜索工具确保找到正确的工具，编程工具调用确保高效执行，工具使用示例确保正确调用。

设置工具搜索工具以更好地发现

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

// 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"
}

有关受益于程序化编排的选择加入工具，请参见下文:

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

设置参数精度的工具使用示例

行为清晰的工艺示例:

• 使用真实的数据 (真实的城市名称，合理的价格，而不是 "字符串" 或 "价值")
• 显示具有最小，部分和完整规格模式的品种
• 保持简洁: 每个工具1-5个示例
• 专注于歧义 (仅添加正确用法从模式中不明显的示例)

入门

这些功能在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示例，请参阅我们的:

• 文档和食谱用于工具搜索工具
• 文档和食谱用于编程工具调用
• 文档对于工具使用示例

这些功能将工具的使用从简单的函数调用转移到智能编排。随着代理处理跨越数十种工具和大型数据集的更复杂的工作流，动态发现，高效执行和可靠的调用成为基础。

我们很高兴看到你创造了什么。

致谢

作者: Bin Wu，Adam Jones，Artur Renault，Henry Tay，Jake Noble，Nathan McCandlish，Noah Picard，Sam Jiang和Claude开发平台团队。这项工作建立在Chris Gorgolewski，Daniel Jiang，Jeremy Fox和Mike Lambert的基础研究之上。我们还从整个AI生态系统中汲取了灵感，包括Joel Pobar的LLMVM,Cloudflare的代码模式和作为MCP执行代码。特别感谢安迪·舒迈斯特、哈米什·克尔、基尔·布拉德韦尔、马特·布莱弗和莫莉·沃沃尔克的支持。