Claude Advisor Tool：将快速执行器与更智能的计划器配对

您有一个运行 Sonnet 的编码代理。 它可以毫不费力地处理 90% 的转弯：读取文件、 运行测试，编写样板文件。 但是当遇到棘手的架构决策或微妙的并发时 bug，你希望它可以给朋友打电话。

这就是顾问工具。 Anthropic 的新 Beta API 功能可提供更快的执行器模型（Sonnet 或 Haiku） 将更高智能的顾问模型（Opus）称为中代。 顾问阅读完整的成绩单， 制定一个简短的计划或路线修正，然后执行者继续执行任务。 一个 API 请求， 两种型号，以 Sonnet 的价格提供接近 Opus 的品质。

顾问工具的工作原理

当您将顾问工具添加到您的 tools 数组，执行器决定何时调用它， 就像任何其他工具一样。 流程：

1. 执行者发出一个 server_tool_use 块与 name: "advisor" 和一个空的 input。
2. Anthropic 在顾问模型服务器端运行单独的推理过程，传递执行者的完整记录（系统提示、工具定义、所有先前的回合和结果）。
3. 顾问的响应返回为 advisor_tool_result 块（通常为 400 到 700 个文本标记）。
4. 执行者根据建议继续生成。

所有这一切都发生在一个单一的 /v1/messages 要求。 您无需额外往返。 Advisor 无需工具即可运行，也无需上下文管理； 它的思维障碍被抛弃了，只有 建议文本到达执行者。

您的第一个顾问电话：curl、Python 和 TypeScript

顾问工具处于测试阶段。 包括 advisor-tool-2026-03-01 您的请求中的 beta 标头。 这是最简单的调用：

卷曲

curl https://api.anthropic.com/v1/messages \\
  --header "x-api-key: \$ANTHROPIC_API_KEY" \\
  --header "anthropic-version: 2023-06-01" \\
  --header "anthropic-beta: advisor-tool-2026-03-01" \\
  --header "content-type: application/json" \\
  --data '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 4096,
    "tools": [
      {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-6"
      }
    ],
    "messages": [{
      "role": "user",
      "content": "Build a concurrent worker pool in Go with graceful shutdown."
    }]
  }'

Python

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=[
        {
            "type": "advisor_20260301",
            "name": "advisor",
            "model": "claude-opus-4-6",
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Build a concurrent worker pool in Go with graceful shutdown.",
        }
    ],
)

print(response)

打字稿

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.beta.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 4096,
  betas: ["advisor-tool-2026-03-01"],
  tools: [
    {
      type: "advisor_20260301",
      name: "advisor",
      model: "claude-opus-4-6",
    },
  ],
  messages: [
    {
      role: "user",
      content: "Build a concurrent worker pool in Go with graceful shutdown.",
    },
  ],
});

console.log(response);

响应是什么样的

成功的顾问调用会产生四个内容块：执行者的初始文本、 server_tool_use 块， advisor_tool_result 块，以及执行者的 最终输出由建议通知。

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Let me consult the advisor on this."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_abc123",
      "name": "advisor",
      "input": {}
    },
    {
      "type": "advisor_tool_result",
      "tool_use_id": "srvtoolu_abc123",
      "content": {
        "type": "advisor_result",
        "text": "Use a channel-based coordination pattern. Close the input channel first, then wait on a WaitGroup..."
      }
    },
    {
      "type": "text",
      "text": "Here's the implementation using a channel-based coordination pattern..."
    }
  ]
}

这 advisor_tool_result 内容有两种变体： advisor_result 带有明文 建议，以及 advisor_redacted_result 具有加密内容。 在这两种情况下，往返 后续回合中逐字逐句的内容。

有效模型对

顾问必须至少与执行人一样有能力。 无效对返回 400 错误。

大多数工作负载的最佳选择：Sonnet 作为执行者，Opus 作为顾问。 您可以在以下地点获得优质电梯： 与为每个代币运行 Opus 相比，总成本相似或更低。

多轮对话

传递完整的助手内容，包括 advisor_tool_result 块，回到 API 随后的回合。 如果您省略顾问工具 tools 在后续转弯时 消息历史记录仍包含 advisor_tool_result 块，API 返回一个 400。

import anthropic

client = anthropic.Anthropic()

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-6",
    }
]

messages = [
    {
        "role": "user",
        "content": "Build a concurrent worker pool in Go with graceful shutdown.",
    }
]

# First turn: executor calls advisor, builds the worker pool
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

# Pass back the full response content (including advisor_tool_result blocks)
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": "Now add a max-in-flight limit of 10."})

# Second turn: executor has context from first advisor call
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

编码剂的快速工程设计

顾问工具附带了一个内置描述，可以促使执行器在开始时调用它 的复杂任务。 对于编码和代理工作负载，您可以通过系统提示来改进结果： 强化了两个时间安排：

• 在对笔录中的一些探索性阅读之后，早期的第一次顾问电话
• 文件写入和测试输出后的最终顾问调用位于记录中

这是 Anthropic 推荐的用于编码任务的系统提示模式。 它产生了最高 内部评估中的情报成本接近十四行诗：

You have access to an \`advisor\` tool backed by a stronger reviewer model.
It takes NO parameters. When you call advisor(), your entire conversation
history is automatically forwarded.

Call advisor BEFORE substantive work: before writing, before committing
to an interpretation, before building on an assumption.

Also call advisor:
- When you believe the task is complete (save your deliverable first)
- When stuck: errors recurring, approach not converging
- When considering a change of approach

The advisor should respond in under 100 words and use enumerated steps,
not explanations.

与其他工具结合

该顾问工具将 Web 搜索、代码执行和您的自定义工具组合在同一目录中 tools 大批。 执行者可以搜索网络、致电顾问并使用您的工具 同一个回合。 顾问的计划可以告知执行者接下来使用哪些工具。

tools = [
    {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 5,
    },
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-6",
    },
    {
        "name": "run_bash",
        "description": "Run a bash command",
        "input_schema": {
            "type": "object",
            "properties": {"command": {"type": "string"}},
        },
    },
]

Advisor 提示缓存

有两个独立的缓存层可用。 执行器端缓存的工作方式与任何内容块相同： 放置一个 cache_control 断点后 advisor_tool_result 它击中了。

顾问端缓存可在同一对话中的各个呼叫之间缓存顾问的记录。 启用它与 caching 工具定义中的字段：

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-6",
        "caching": {"type": "ephemeral", "ttl": "5m"},
    }
]

当顾问程序被调用两次或更少次数时，缓存写入的成本高于读取节省的成本。 缓存在大约 3 个顾问调用后就达到平衡，并从此开始改进。 长期启用 代理循环； 对于短期任务，请将其关闭。

使用情况和计费明细

Advisor 调用作为单独的子推理运行，按 Advisor 模型的费率计费。 这 usage.iterations array 为您提供每次迭代的细分：

{
  "usage": {
    "input_tokens": 412,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "output_tokens": 531,
    "iterations": [
      {
        "type": "message",
        "input_tokens": 412,
        "output_tokens": 89
      },
      {
        "type": "advisor_message",
        "model": "claude-opus-4-6",
        "input_tokens": 823,
        "output_tokens": 1612
      },
      {
        "type": "message",
        "input_tokens": 1348,
        "cache_read_input_tokens": 412,
        "output_tokens": 442
      }
    ]
  }
}

顶级 usage 字段仅反映执行者令牌。 迭代与 type: "advisor_message" 按顾问模型的费率计费。 使用 iterations 构建成本跟踪逻辑时的数组。

成本控制：限制顾问电话

顾问工具没有内置的对话级别上限。 使用 max_uses 在工具上 每个请求限制的定义。 对于对话级别限制，计算客户端调用次数和 当你达到上限时剥夺顾问的帮助：

# Track advisor calls client-side
advisor_count = 0
MAX_ADVISOR_CALLS = 5

for turn in conversation:
    response = client.beta.messages.create(...)

    # Count advisor calls in response
    for block in response.content:
        if block.type == "server_tool_use" and block.name == "advisor":
            advisor_count += 1

    if advisor_count >= MAX_ADVISOR_CALLS:
        # Remove advisor tool and strip advisor_tool_result blocks
        tools = [t for t in tools if t.get("name") != "advisor"]
        for msg in messages:
            if msg["role"] == "assistant":
                msg["content"] = [
                    b for b in msg["content"]
                    if b.get("type") not in ("server_tool_use", "advisor_tool_result")
                    or b.get("name") != "advisor"
                ]

错误处理

如果 Advisor 调用失败，结果会带有 advisor_tool_result_error 与一个 error_code。 执行者看到错误并在没有建议的情况下继续； 请求 本身并没有失败。

流媒体行为

Advisor 子推理不进行流式传输。 当顾问运行时，执行者的流暂停， 然后完整的 advisor_tool_result 到达单一 content_block_start 事件。 暂停期间，SSE ping keepalive 每 30 秒触发一次。 计划 2 到 5 秒 每次顾问通话时保持沉默，具体取决于文字记录长度。

当顾问提供帮助时（以及当没有帮助时）

需要了解的限制

• Advisor 输出不流式传输。 预计子推理期间会有暂停。
• 顾问呼叫没有内置对话级别上限。 在客户端跟踪并限制它们。
• max_tokens 仅适用于执行程序输出。 它不绑定顾问代币。
• 执行人的优先级不延伸至顾问； 两种型号都需要它。
• 该功能处于测试阶段。 包括 anthropic-beta: advisor-tool-2026-03-01 在每一个请求中。