Skip to content

claude-advanced-tool-use.md

Latest commit

 

History

History
420 lines (318 loc) · 13.1 KB

claude-advanced-tool-use.md

File metadata and controls

420 lines (318 loc) · 13.1 KB

Claude 高级工具使用模式

API 级特性（现已 GA）可减少 Token 消耗、延迟并提高工具准确性。随 Opus/Sonnet 4.6 发布。

← 返回 Claude Code 最佳实践 Claude

目录

  1. 概述
  2. 程序化工具调用 (PTC)
  3. 网页搜索/获取的动态过滤
  4. 工具搜索工具
  5. 工具使用示例
  6. Claude Code 的相关性

概述

特性 解决的问题 Token 节省 可用性
程序化工具调用 多步骤 Agent 循环在往返中消耗 Token ~37% 减少 API、Foundry (GA)
动态过滤 网页搜索/获取结果用无关内容膨胀上下文 ~24% 更少的输入 Token API、Foundry (GA)
工具搜索工具 过多的工具定义膨胀上下文 ~85% 减少 API、Foundry (GA)
工具使用示例 Schema 无法表达使用模式 72% → 90% 准确性 API、Foundry (GA)

所有特性自 2026年2月18日 起全面可用。

战略分层 —— 从最大的瓶颈开始：

  • 工具定义导致的上下文膨胀 → 工具搜索工具
  • 大型中间结果 → 程序化工具调用
  • 网页搜索噪音 → 动态过滤
  • 参数错误 → 工具使用示例

程序化工具调用 (PTC)

PTC 图表 —— 传统与程序化工具调用对比

范式转变

之前（传统工具调用）：

User prompt → Claude → Tool call 1 → Response 1 → Claude → Tool call 2 → Response 2 → Claude → Tool call 3 → Response 3 → Claude → 最终答案

每次工具调用都需要完整的模型往返。3 个工具 = 3 次推理。

之后（程序化工具调用）：

User prompt → Claude → 编写 Python 脚本 → 脚本内部调用 Tool 1、Tool 2、Tool 3 → stdout → Claude → 最终答案

Claude 编写编排所有工具的代码。只有最终的 stdout 进入上下文窗口。3 个工具 = 1 次推理。

工作原理

  1. 你用 allowed_callers: ["code_execution_20250825"] 定义工具
  2. Claude 在沙箱内编写将那些工具作为异步函数调用的 Python 代码
  3. 当调用工具函数时，沙箱暂停，API 返回 tool_use 块
  4. 你提供工具结果 —— 它进入运行中的代码，而不是 Claude 的上下文
  5. 代码恢复，处理结果，如有需要调用更多工具
  6. 只有最终执行的 stdout 到达 Claude

关键配置

{
  "tools": [
    {
      "type": "code_execution_20250825",
      "name": "code_execution"
    },
    {
      "name": "query_database",
      "description": "Execute a SQL query. Returns rows as JSON objects with fields: id (str), name (str), revenue (float).",
      "input_schema": {
        "type": "object",
        "properties": {
          "sql": { "type": "string", "description": "SQL query to execute" }
        },
        "required": ["sql"]
      },
      "allowed_callers": ["code_execution_20250825"]
    }
  ]
}

allowed_callers 字段

值 行为
["direct"] 仅传统工具调用（省略时默认）
["code_execution_20250825"] 仅从 Python 沙箱可调用
["direct", "code_execution_20250825"] 两种模式都可用

建议： 为每个工具选择一种模式，不要两者都用。这会给 Claude 更清晰的指导。

响应中的 caller 字段

每个工具使用块都包含 caller 字段，以便你知道它是如何被调用的：

// 直接（传统）
{ "caller": { "type": "direct" } }

// 程序化（来自代码执行）
{ "caller": { "type": "code_execution_20250825", "tool_id": "srvtoolu_abc123" } }

高级模式

批处理 —— 在 1 次推理中处理 N 个项目：

regions = ["West", "East", "Central", "North", "South"]
results = {}
for region in regions:
    data = await query_database(f"SELECT SUM(revenue) FROM sales WHERE region='{region}'")
    results[region] = data[0]["revenue"]

top = max(results.items(), key=lambda x: x[1])
print(f"Top region: {top[0]} with ${top[1]:,}")

提前终止 —— 一旦满足成功条件就停止：

endpoints = ["us-east", "eu-west", "apac"]
for endpoint in endpoints:
    status = await check_health(endpoint)
    if status == "healthy":
        print(f"Found healthy endpoint: {endpoint}")
        break

条件工具选择：

file_info = await get_file_info(path)
if file_info["size"] < 10000:
    content = await read_full_file(path)
else:
    content = await read_file_summary(path)
print(content)

数据过滤 —— 减少 Claude 看到的内容：

logs = await fetch_logs(server_id)
errors = [log for log in logs if "ERROR" in log]
print(f"Found {len(errors)} errors")
for error in errors[-10:]:
    print(error)

模型兼容性

模型 支持
Claude Opus 4.6 是
Claude Sonnet 4.6 是
Claude Sonnet 4.5 是
Claude Opus 4.5 是

限制

限制 详情
不在 Bedrock/Vertex 上 仅 API 和 Foundry
无 MCP 工具 MCP 连接器工具无法以程序化方式调用
无网页搜索/获取 PTC 不支持网页工具
无结构化输出 strict: true 工具不兼容
无强制工具选择 tool_choice 无法强制 PTC
容器生命周期 ~4.5 分钟后过期
ZDR 不受零数据保留覆盖
工具结果为字符串 验证外部结果以防代码注入风险

何时使用 PTC

好的使用场景 不太理想
处理需要聚合的大型数据集 具有简单响应的单个工具调用
序列中的 3+ 个依赖工具调用 需要立即用户反馈的工具
在 Claude 看到之前过滤/转换结果 非常快的操作（开销 > 收益）
跨多个项目的并行操作
基于中间结果的条件逻辑

Token 效率

  • 程序化调用的工具结果不会添加到 Claude 的上下文 —— 只有最终的 stdout
  • 中间处理发生在代码中，而不是模型 Token 中
  • 10 个程序化工具 ≈ 10 个直接调用的 1/10 Token

网页搜索/获取的动态过滤

问题

网页搜索和获取工具将完整的 HTML 页面转储到 Claude 的上下文窗口中。其中大部分内容是无关的 —— 导航、广告、样板内容。然后 Claude 基于所有内容推理，浪费 Token 并降低准确性。

解决方案

Claude 现在在进入上下文窗口之前编写并执行 Python 代码来过滤网页结果。Claude 不再基于原始 HTML 推理，而是在沙箱中过滤、解析和提取仅相关内容。

工作原理

之前：

查询 → 搜索结果 → 获取完整 HTML × N 页 → 所有内容进入上下文 → Claude 基于所有内容推理

之后：

查询 → 搜索结果 → Claude 编写过滤代码 → 代码仅提取相关内容 → 过滤后的结果进入上下文

API 配置

使用带有 beta header 的更新工具类型版本：

{
  "model": "claude-opus-4-6",
  "max_tokens": 4096,
  "tools": [
    {
      "type": "web_search_20260209",
      "name": "web_search"
    },
    {
      "type": "web_fetch_20260209",
      "name": "web_fetch"
    }
  ]
}

必需的 Header： anthropic-beta: code-execution-web-tools-2026-02-09

默认启用 当使用 Sonnet 4.6 和 Opus 4.6 的新工具类型版本时。

基准测试结果

BrowseComp（在网站上查找特定信息）：

模型 无过滤 有过滤 改进
Sonnet 4.6 33.3% 46.6% +13.3 pp
Opus 4.6 45.3% 61.6% +16.3 pp

DeepsearchQA（多步骤研究，F1 分数）：

模型 无过滤 有过滤 改进
Sonnet 4.6 52.6% 59.4% +6.8 pp
Opus 4.6 69.8% 77.3% +7.5 pp

Token 效率： 平均减少 24% 的输入 Token。Sonnet 4.6 看到成本降低；Opus 4.6 可能因更复杂的过滤代码而略有增加。

使用场景

  • 筛选技术文档
  • 跨多个来源验证引用
  • 交叉引用搜索结果
  • 多步骤研究查询
  • 在大型页面中查找特定数据点

工具搜索工具

问题

预先加载所有工具定义会浪费上下文。如果你有 50 个 MCP 工具，每个约 1.5K Token，那就是用户在提问之前的 75K Token。

解决方案

将不常用的工具标记为 defer_loading: true。它们被排除在初始上下文之外。Claude 通过工具搜索工具按需发现它们。

配置

{
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "google-drive",
      "default_config": { "defer_loading": true },
      "configs": {
        "search_files": { "defer_loading": false }
      }
    }
  ]
}

最佳实践

  • 保持 3-5 个最常用的工具始终加载，延迟加载其余的
  • 编写清晰、描述性的工具名称和描述（搜索依赖它们）
  • 在系统提示中记录可用功能

何时使用

  • 工具定义消耗 > 10K Token
  • 10+ 个可用工具
  • 多个 MCP 服务器
  • 选项过多导致的工具选择准确性问题

Token 节省

~85% 的工具定义 Token 减少（在 Anthropic 的基准测试中从 77K → 8.7K）。

Claude Code 等效功能

Claude Code 有 MCP 工具搜索自动模式（自 v2.1.7 起默认启用）。当 MCP 工具描述超过上下文的 10% 时，它们会被延迟并通过 MCPSearch 发现。使用 ENABLE_TOOL_SEARCH=auto:N 配置阈值，其中 N 是上下文百分比（0-100）。

工具使用示例

问题

JSON schema 定义了结构但无法表达：

  • 何时包含可选参数
  • 哪些参数组合有意义
  • 格式约定（日期格式、ID 模式）
  • 嵌套结构使用

解决方案

将 input_examples 添加到工具定义 —— 超出 schema 的具体使用模式。

配置

{
  "name": "create_ticket",
  "description": "Create a support ticket",
  "input_schema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
      "assignee": { "type": "string" },
      "labels": { "type": "array", "items": { "type": "string" } }
    },
    "required": ["title"]
  },
  "input_examples": [
    {
      "title": "Login page returns 500 error",
      "priority": "critical",
      "assignee": "oncall-team",
      "labels": ["bug", "auth", "production"]
    },
    {
      "title": "Add dark mode support",
      "priority": "low",
      "labels": ["feature-request", "ui"]
    },
    {
      "title": "Update API docs for v2 endpoints"
    }
  ]
}

最佳实践

  • 使用真实数据，而不是像 "example_value" 这样的占位符字符串
  • 展示多样性：最小、部分和完整规范
  • 保持简洁：每个工具1-5 个示例
  • 专注于解决歧义 —— 目标行为清晰度而非 schema 完整性
  • 展示参数相关性（例如，priority: "critical" 往往有 assignee）

结果

在 Anthropic 的基准测试中，复杂参数处理的准确性从 72% → 90%。

Claude Code 的相关性

对 Claude Code 用户直接适用的内容

特性 Claude Code 状态 操作
工具搜索 自 v2.1.7 起作为 MCPSearch 自动模式内置 如果你有很多 MCP 工具，调整 ENABLE_TOOL_SEARCH=auto:N
动态过滤 CLI 中不可用（API 级网页工具） 与使用 Agent SDK 进行网页研究的用户相关
PTC CLI 中不可用 与使用 Agent SDK 构建自定义 Agent 的用户相关
工具使用示例 CLI 中不可配置 与自定义 MCP 服务器作者相关

对于 Agent SDK 开发者

如果你使用 @anthropic-ai/claude-agent-sdk 构建 Agent，PTC 可以立即使用：

  1. 将 code_execution_20250825 添加到你的工具数组
  2. 在受益于批处理/过滤的工具上设置 allowed_callers
  3. 实现工具结果循环（暂停 → 提供结果 → 恢复）
  4. 从工具返回结构化数据（JSON）以便于程序化解析

对于 MCP 服务器作者

如果你正在构建自定义 MCP 服务器，工具使用示例可以改善 Claude 使用你工具的方式：

  • 将 input_examples 添加到工具 schema
  • 在描述中清楚地记录返回格式（PTC 需要解析它们）

来源
⚡