Advisor tool

将更快的 executor 模型与更高智能的 advisor 模型配对，在生成过程中提供战略指导。

Advisor tool 允许更快、更低成本的 executor 模型在生成过程中咨询更高智能的 advisor 模型以获取战略指导。Advisor 读取完整对话，生成计划或方向修正（通常 400 到 700 个文本 token，包括 thinking 在内总共 1,400 到 1,800 个 token），然后 executor 继续执行任务。

这种模式适合长时间跨度的 agent 工作负载（编码 agent、computer use、多步骤研究管道），其中大多数轮次是机械性的，但拥有出色的计划至关重要。你可以获得接近 advisor 单独使用时的质量，同时大部分 token 生成以 executor 模型的速率进行。

何时使用

早期基准测试显示以下配置有显著收益：

• 你目前在复杂任务上使用 Sonnet： 添加 Opus 作为 advisor，在相似或更低的总成本下提升质量。
• 你目前使用 Haiku 并希望在智能上更进一步： 添加 Opus 作为 advisor。预期成本高于单独使用 Haiku，但低于将 executor 切换到更大模型。

结果取决于任务。请在你自己的工作负载上进行评估。

Advisor 不太适合单轮问答（没有需要规划的内容）、用户已自行选择成本和质量权衡的纯透传模型选择器，或每轮都真正需要 advisor 模型全部能力的工作负载。

模型兼容性

Executor 模型（顶层 model 字段）和 advisor 模型（工具定义内的 model 字段）必须形成有效配对。Advisor 必须至少与 executor 同等能力。

如果你请求了无效配对，API 会返回 400 invalid_request_error，指出不支持的组合。

平台可用性

Advisor tool 在 Claude API 和 AWS 上的 Claude Platform 上以 beta 形式提供。目前不在 AWS Bedrock、Vertex AI 或 Microsoft Foundry 上提供。

快速开始

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-7"
            }
        ],
        "messages": [{
            "role": "user",
            "content": "Build a concurrent worker pool in Go with graceful shutdown."
        }]
    }'

ant beta:messages create --beta advisor-tool-2026-03-01 <<'YAML'
model: claude-sonnet-4-6
max_tokens: 4096
tools:
  - type: advisor_20260301
    name: advisor
    model: claude-opus-4-7
messages:
  - role: user
    content: Build a concurrent worker pool in Go with graceful shutdown.
YAML

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-7",
        }
    ],
    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();

async function main() {
  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-7"
      }
    ],
    messages: [
      {
        role: "user",
        content: "Build a concurrent worker pool in Go with graceful shutdown."
      }
    ]
  });

  console.log(response);
}

main().catch(console.error);

using Anthropic;
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;

var client = new AnthropicClient();

var parameters = new MessageCreateParams
{
    Model = Messages::Model.ClaudeSonnet4_6,
    MaxTokens = 4096,
    Tools = new BetaToolUnion[]
    {
        new BetaAdvisorTool20260301
        {
            Model = Messages::Model.ClaudeOpus4_7
        }
    },
    Messages =
    [
        new BetaMessageParam
        {
            Role = Role.User,
            Content = "Build a concurrent worker pool in Go with graceful shutdown."
        }
    ],
    Betas = ["advisor-tool-2026-03-01"]
};

var response = await client.Beta.Messages.Create(parameters);
Console.WriteLine(response);

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/anthropics/anthropic-sdk-go"
)

func main() {
	client := anthropic.NewClient()

	response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
		Model:     anthropic.ModelClaudeSonnet4_6,
		MaxTokens: 4096,
		Tools: []anthropic.BetaToolUnionParam{
			{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
				Model: anthropic.ModelClaudeOpus4_7,
			}},
		},
		Messages: []anthropic.BetaMessageParam{
			anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Build a concurrent worker pool in Go with graceful shutdown.")),
		},
		Betas: []anthropic.AnthropicBeta{
			anthropic.AnthropicBetaAdvisorTool2026_03_01,
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

<?php

use Anthropic\Client;

$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY"));

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

echo $response;

require "anthropic"

client = Anthropic::Client.new

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

puts response

工作原理

当你将 advisor tool 添加到 tools 数组时，executor 模型会像决定其他工具一样决定何时调用它。当 executor 调用 advisor 时：

1. Executor 发出一个 server_tool_use 块，name 为 "advisor"，input 为空。Executor 发出时序信号；服务器提供上下文。
2. Anthropic 在服务端对 advisor 模型运行单独的推理过程，传递 executor 的完整记录。Advisor 可以看到系统提示、所有工具定义、所有先前轮次和所有先前工具结果。
3. Advisor 的响应作为 advisor_tool_result 块返回给 executor。
4. Executor 根据建议继续生成。

所有这些都发生在单个 /v1/messages 请求中。你这边无需额外的往返。

Advisor 本身在没有工具和没有上下文管理的情况下运行。其 thinking 块在结果返回前被丢弃；只有建议文本到达 executor。

工具参数

caching 对象的格式为 {"type": "ephemeral", "ttl": "5m" | "1h"}。与内容块上的 cache_control 不同，这不是断点标记；而是开关。服务器决定缓存边界的位置。

响应结构

成功的 advisor 调用

当 advisor 被调用时，助手内容中会出现一个 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. The tricky part is draining in-flight work during shutdown: close the input channel first, then wait on a WaitGroup..."
      }
    },
    {
      "type": "text",
      "text": "Here's the implementation. I'm using a channel-based coordination pattern to avoid writer starvation..."
    }
  ]
}

server_tool_use.input 始终为空。服务器从完整记录中自动构建 advisor 的视图；executor 放入 input 中的任何内容都不会到达 advisor。

结果变体

advisor_tool_result.content 字段是一个可辨识联合体。对于成功的调用，变体取决于 advisor 模型：

对于 advisor_result，text 字段包含人类可读的建议。对于 advisor_redacted_result，encrypted_content 字段包含你无法读取的不透明数据；在下一轮中，服务器会解密它并将纯文本渲染到 executor 的提示中。

在两种情况下，请在后续轮次中原样传回内容。如果你在对话中途切换 advisor 模型，请根据 content.type 分支处理两种格式。

错误结果

如果 advisor 调用失败，结果会携带错误：

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_tool_result_error",
    "error_code": "overloaded"
  }
}

Executor 看到错误后继续执行，不再获取建议。请求本身不会失败。

Advisor 的速率限制与直接调用 advisor 模型共享同一个按模型分配的桶。Advisor 的速率限制在工具结果内显示为 too_many_requests；executor 的速率限制会以 HTTP 429 使整个请求失败。

多轮对话

在后续轮次中将完整的助手内容（包括 advisor_tool_result 块）传回 API：

import anthropic

client = anthropic.Anthropic()

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

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

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

# 将完整的响应内容（包括所有 advisor_tool_result 块）追加到消息中
messages.append({"role": "assistant", "content": response.content})

# 继续对话
messages.append({"role": "user", "content": "Now add a max-in-flight limit of 10."})

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

如果你在后续轮次的 tools 中省略了 advisor tool，而消息历史中仍包含 advisor_tool_result 块，API 会返回 400 invalid_request_error。

流式传输

Advisor 子推理不会流式传输。Advisor 运行时 executor 的流会暂停，然后完整结果在单个事件中到达。

name 为 "advisor" 的 server_tool_use 块表示 advisor 调用开始。暂停从该块关闭时（content_block_stop）开始。暂停期间，流除了大约每 30 秒发出一次的标准 SSE ping 保持连接外保持安静；较短的 advisor 调用可能不会显示 ping。

当 advisor 完成时，advisor_tool_result 以完整的单个 content_block_start 事件到达（无 delta）。然后 executor 输出恢复流式传输。

随后的 message_delta 事件包含更新的 usage.iterations 数组，反映 advisor 的 token 计数。

使用量和计费

Advisor 调用作为单独的子推理运行，按 advisor 模型的费率计费。使用量报告在 usage.iterations[] 数组中：

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

顶层 usage 字段仅反映 executor 的 token。Advisor 的 token 不计入顶层总计，因为它们以不同的费率计费。type: "advisor_message" 的迭代按 advisor 模型的费率计费；type: "message" 的迭代按 executor 模型的费率计费。

聚合规则因字段而异。顶层 output_tokens 是所有 executor 迭代的总和。顶层 input_tokens 和 cache_read_input_tokens 仅反映第一次 executor 迭代；后续 executor 迭代的输入不会重新求和，因为它们包含了先前的输出 token。构建成本跟踪逻辑时，请使用 usage.iterations 获取完整的逐迭代分解。

Advisor 输出通常为 400 到 700 个文本 token，包括 thinking 在内总共 1,400 到 1,800 个 token。成本节省来自 advisor 不生成你的完整最终输出；executor 以其较低的速率完成这项工作。

顶层 max_tokens 仅适用于 executor 输出。它不限制 advisor 子推理的 token。Advisor 的 token 也不从应用于 executor 的任何任务预算中提取。

Advisor prompt caching

有两个独立的缓存层。

Executor 端缓存

advisor_tool_result 块像其他内容块一样可缓存。在后续轮次中放在其后的 cache_control 断点会命中。Executor 的提示始终包含纯文本建议，无论你的客户端收到的是 text 还是 encrypted_content，因此两种结果变体的缓存行为相同。

Advisor 端缓存

在工具定义上设置 caching 以在同一对话内跨调用为 advisor 自身的记录启用 prompt caching：

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

第 N 次调用时 advisor 的提示是第 (N-1) 次调用的提示追加了一个新段，因此前缀在跨调用时是稳定的。启用 caching 后，每次 advisor 调用写入一个缓存条目；下一次调用读取到该点并只为增量付费。你会看到 cache_read_input_tokens 在第二次及之后的 advisor_message 迭代中变为非零。

何时启用： 当每个对话中 advisor 被调用两次或更少时，缓存写入的成本高于读取所节省的成本。缓存在大约三次 advisor 调用时达到盈亏平衡，之后会持续改善。为长时间运行的 agent 循环启用它；短任务保持关闭。

保持一致性： 设置一次 caching 并在整个对话中保持不变。在对话中途切换会导致缓存未命中。

与其他工具组合

Advisor tool 与其他服务端和客户端工具组合使用。将它们全部添加到同一个 tools 数组中：

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

Executor 可以在同一轮中搜索网页、调用 advisor 和使用你的自定义工具。Advisor 的计划可以影响 executor 接下来选择哪些工具。

最佳实践

编码和 agent 任务的提示

Advisor tool 附带内置描述，引导 executor 在复杂任务开始时和遇到困难时调用它。对于研究任务，通常不需要额外的提示。

对于编码和 agent 任务，当 advisor 减少总工具调用和对话长度时，它能以相似的成本产生更高的智能。两个时序驱动了这种改进：

1. 在记录中包含几次探索性读取后，尽早进行第一次 advisor 调用。
2. 对于困难任务，在文件写入和测试输出进入记录后进行最后一次 advisor 调用。

如果你的 agent 暴露了其他类似规划器的工具（例如待办事项列表工具），请提示模型在调用这些工具之前先调用 advisor，以便 advisor 的计划流入它们。下面建议的系统提示强化了早期调用模式；添加你自己的引导语句，指向你的 agent 暴露的规划器工具。

编码任务的建议系统提示

对于你希望 advisor 时序一致且每个任务大约调用两到三次的编码任务，请在 executor 系统提示中任何提到 advisor 的句子之前添加以下块。在内部编码评估中，这种模式以接近 Sonnet 的成本产生了最高的智能。

时序指导：

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. They see the task, every tool call you've made, every result you've seen.

Call advisor BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.

Also call advisor:
- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
- When stuck — errors recurring, approach not converging, results that don't fit.
- When considering a change of approach.

On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling — the advisor adds most of its value on the first call, before the approach crystallizes.

Executor 应如何对待建议（放在时序块之后）：

Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong — it's evidence your test doesn't check what the advice is checking.

If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call — "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.

修剪 advisor 输出长度

Advisor 输出是 advisor 最大的成本驱动因素，而 max_tokens 不限制它。Advisor 将你的系统提示和用户消息都视为关于 executor 任务的引用上下文，因此直接对 advisor 发出的指示比第三人称描述更可靠地被执行。Anthropic 测试过的最有效位置是在用户消息中的一行：

(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)

此行可以由你的 agent 框架在发送请求前以编程方式添加前缀。限制是软约束；advisor 会偶尔超出，因此请请求你实际上限的大约 80%。

将此方法与编码任务的建议系统提示中的时序指导配合使用，以获得最强的成本与质量权衡。

与 effort 设置配对

对于编码任务，将 medium effort 的 Sonnet executor 与 Opus advisor 配对，可以以更低的成本获得与默认 effort 的 Sonnet 相当的智能。要获得最高智能，请保持 executor 使用默认 effort。

成本控制

• 对于对话级预算，请在客户端计数 advisor 调用。达到上限时，从 tools 中移除 advisor tool 并从消息历史中删除所有 advisor_tool_result 块，以避免 400 invalid_request_error。
• 仅在你预期每个对话有三次或更多 advisor 调用时启用 caching。

限制

• Advisor 输出不会流式传输。 预期在子推理运行期间流会有暂停。
• 没有内置的对话级 advisor 调用上限。 请在客户端跟踪和限制。
• max_tokens 仅适用于 executor 输出。 它不限制 advisor 的 token。
• 优先层级 对每个模型分别遵守。Executor 模型上的优先层级不会延伸到 advisor；你需要专门在 advisor 模型上设置优先层级。