顾问工具

"Advisor tool"（顾问工具）允许速度更快、成本更低的执行者模型（executor model）在生成过程中咨询智能更高的顾问模型（advisor model）以获取战略性指导。顾问会阅读完整的对话，生成计划或纠正方向，然后执行者继续完成任务。

这种模式适合长周期的智能体工作负载（编码智能体、计算机使用、多步骤研究流水线），在这些场景中大多数轮次都是机械性的，但拥有一个出色的计划至关重要。您可以获得接近顾问模型单独运行的质量，而大部分令牌生成则按执行者模型的费率进行。有关实测结果，包括随着执行者自身能力接近顾问能力时收益如何缩小，请参阅针对成本和智能进行优化。



何时使用

顾问工具适合以下配置：

• 您目前在复杂任务上使用 Sonnet： 添加一个更高层级的顾问。Opus 可使总成本保持相近或更低；Claude Fable 5 可最大化质量提升。
• 您目前使用 Haiku 并希望提升智能水平： 添加一个 Opus 或 Fable 顾问。预计成本会高于单独使用 Haiku，但低于将执行者切换为更大的模型。

结果因任务而异。请在您自己的工作负载上进行评估。

顾问工具不太适合单轮问答（没有什么需要规划的）、纯透传式的模型选择器（您的用户已经自行选择成本与质量的权衡），或每一轮都确实需要顾问模型全部能力的工作负载。



快速开始

client = anthropic.Anthropic()

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

print(response)

响应的 content 中包含一个携带顾问指导的 advisor_tool_result 块。如本快速开始中那样使用 claude-opus-5 作为顾问时，该块的 content 字段是 advisor_redacted_result 变体（已加密；执行者在服务器端读取它，但您的客户端无法读取）。若要在响应中直接看到建议文本，请改用 claude-opus-4-8 作为顾问模型，它会返回明文的 advisor_result 变体。请参阅结果变体以并排查看两种形态以及哪些顾问模型返回哪种变体，并参阅模型兼容性获取有效配对的完整列表。



工作原理

当您将顾问工具添加到 tools 数组中时，执行者模型会像对待任何其他工具一样决定何时调用它。当执行者调用顾问时：

1. 执行者发出一个 server_tool_use 块，其中 name: "advisor" 且 input 为空。执行者负责发出时机信号，服务器负责提供上下文。
2. Anthropic 在服务器端对顾问模型运行一次单独的推理。顾问在其自己的、由 Anthropic 提供的 system prompt（系统提示）下运行，并在其输入中以引用上下文的形式接收执行者的完整对话记录。该对话记录包括您的系统提示、工具定义、先前的轮次和工具结果，以及执行者在本轮中迄今为止生成的文本。
3. 顾问的响应以 advisor_tool_result 块的形式返回给执行者。
4. 执行者在建议的指引下继续生成。

所有这些都发生在单个 /v1/messages 请求内部，您这一侧无需额外的往返。例外情况是在调用中途暂停的轮次，您需要通过后续请求来恢复它（请参阅恢复暂停的轮次）。

顾问本身在没有工具、没有上下文管理的情况下运行。其思考块会在结果返回之前被丢弃。只有建议文本会到达执行者。



工具参数

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

顾问工具还接受任何工具定义上可用的通用属性：cache_control、allowed_callers、defer_loading 和 strict（在结构化输出中介绍）。有关其语义，请参阅工具参考。



响应结构



成功的顾问调用

当顾问被调用时，助手的内容中会出现一个 server_tool_use 块，后跟一个 advisor_tool_result 块。以下示例展示了由 Claude Opus 4.8 顾问返回的明文 advisor_result 变体。快速开始使用的是 Claude Opus 5，它返回的是加密的 advisor_redacted_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 始终为空。服务器会自动根据完整对话记录构建顾问的视图。执行者放入 input 中的任何内容都不会到达顾问。



结果变体

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

以下是同一请求发送两次的结果，除工具定义中的顾问 model 外完全相同，展示了两种变体。

使用 "model": "claude-opus-4-8" 时，建议为明文：

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

使用 "model": "claude-opus-5" 时，建议为加密内容：

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_redacted_result",
    "encrypted_content": "EqQBCkYIBRgCIiQ5ZjE0N2M2OC0yYWIxLTRkZTktYjA3ZC1hZTUyMzkxYjhkMmU..."
  }
}

当您在工具定义上设置了 max_tokens 时，两种结果变体都会携带 stop_reason 字段；未设置时则省略该字段。它保存顾问子调用的停止原因，通常为 "end_turn"，或在达到上限时为 "max_tokens"。这些值与顶层 Messages API 的 stop_reason 一致。

对于 advisor_result，text 字段包含人类可读的建议。对于 advisor_redacted_result，encrypted_content 字段包含一个您无法读取的不透明数据块。在下一轮中，服务器会将其解密并将明文渲染到执行者的提示中。

在这两种情况下，请在后续轮次中原样回传该内容。如果您在对话中途切换顾问模型，请根据 content.type 进行分支以处理两种形态。



错误结果

如果顾问调用失败，结果会携带一个错误：

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

执行者会看到该错误并在没有进一步建议的情况下继续。请求本身不会失败。

顾问的 rate limit（速率限制）与直接调用顾问模型共用同一个按模型划分的配额桶。顾问上的速率限制会在工具结果中以 too_many_requests 的形式出现。执行者上的速率限制则会使整个请求以 HTTP 429 失败。



多轮对话

在后续轮次中，将完整的助手内容（包括 advisor_tool_result 块）传回 API。请原样回传结果块：使用 Claude Opus 5 顾问时，结果块的 content 是加密的 advisor_redacted_result 变体，服务器会在下一轮将其解密并将建议渲染到执行者的提示中（请参阅结果变体）。对于任何顾问模型，其机制都是相同的。

client = anthropic.Anthropic()

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

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

response = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    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-5",
    max_tokens=1024,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

您可以在后续轮次中从 tools 中移除顾问工具，即使消息历史中仍包含 advisor_tool_result 块。请求会被接受，历史块会被保留；模型在该轮中无法调用顾问。您仍必须发送 advisor-tool-2026-03-01 beta 头，这些历史块才会被接受。



恢复暂停的轮次

当顾问调用仍处于待处理状态时，响应可能以 stop_reason: "pause_turn" 结束。发生这种情况时，响应中包含顾问的 server_tool_use 块，但没有对应的 advisor_tool_result。若要恢复，请将该助手消息原样追加到 messages 中（保留 server_tool_use 块），然后使用相同的顾问工具和 beta 头再次发送请求。您无需添加用户消息或 tool_result 块。API 会运行待处理的顾问调用，并在新的响应中继续执行者的轮次。恢复后的轮次可能再次暂停。如果发生这种情况，请重复相同的步骤。在恢复请求中省略顾问工具会返回 400 invalid_request_error，因为待处理的 server_tool_use 块没有可供运行的工具定义；只要有调用处于待处理状态，就请包含该工具。如果执行者在同一轮中调用了您的某个工具，则响应会在顾问调用仍处于待处理状态时以 stop_reason: "tool_use" 结束。照常发送 tool_result 块，待处理的顾问调用会在下一个请求开始时运行。请参阅在一轮中混合使用服务器工具和客户端工具。



针对调用不足的执行者的对话中途提醒

如果 Haiku 执行者在其第一个助手轮次中没有调用顾问，请在第二个助手轮次之前追加一条简短的提醒作为额外的用户消息。在 Anthropic 的内部行为评估中，这使 Haiku 执行者的任务通过率提高了约 7 个百分点。在 Sonnet 执行者上，纯文本提醒在 Anthropic 的测试中没有可测量的效果。下文的调用时机考量对 Sonnet 尤为相关。不要对 Opus 执行者应用该提醒：在 Opus 上它会略微降低通过率。

使用默认的 NUDGE_TURN 值 2 时，提醒通常会在模型已对任务有所了解但尚未确定方法之前到达。

client = anthropic.Anthropic()

NUDGE_TURN = 2  # inject before this assistant turn if no advisor call yet
NUDGE_TEXT = (
    "You have not consulted the advisor yet. If the task has a non-obvious "
    "design decision or a failure mode you haven't ruled out, call advisor "
    "now before committing to an approach."
)
MAX_TURNS = 10  # agent loop cap


def run_your_tools(content):
    # 替换为您的工具分发逻辑。每个 tool_use 块返回一个 tool_result 块。
    return [
        {
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": "Replace with your tool output.",
        }
        for block in content
        if block.type == "tool_use"
    ]


tools = [
    {"type": "advisor_20260301", "name": "advisor", "model": "claude-opus-5"},
    # ... 您的其他工具
]
task = "Build a concurrent worker pool in Go with graceful shutdown."
messages = [{"role": "user", "content": task}]
advisor_called = False

for turn in range(1, MAX_TURNS + 1):
    response = client.beta.messages.create(
        model="claude-haiku-4-5",
        max_tokens=4096,
        betas=["advisor-tool-2026-03-01"],
        tools=tools,
        messages=messages,
    )
    messages.append({"role": "assistant", "content": response.content})
    advisor_called = advisor_called or any(
        block.type == "server_tool_use" and block.name == "advisor"
        for block in response.content
    )
    if response.stop_reason == "end_turn":
        break
    if response.stop_reason == "pause_turn":
        continue  # server tool pending; re-send to let the API complete it

    results = run_your_tools(response.content)  # list of tool_result blocks
    if results:
        messages.append({"role": "user", "content": results})
    # 如果您的系统提示已告知模型谨慎调用，可跳过此项。
    if turn == NUDGE_TURN - 1 and not advisor_called:
        messages.append({"role": "user", "content": NUDGE_TEXT})

请将提醒作为独立的用户消息追加在工具结果之后，而不是作为同一消息中的同级块。连续的用户消息是有效的。在 Anthropic 对 Haiku 和 Sonnet 执行者的测试中，它们的行为与同级块等效。独立消息的形态还能使提醒与工具输出清晰区分。

权衡： 提醒会提高调用率，这可能会使极其简单的任务进行不必要的咨询。如果您的工作负载混合了简单和复杂的任务，请考虑将 NUDGE_TURN 提高到 3，以便两轮任务在提醒触发之前完成，或者根据您已经计算的任务复杂度信号来控制提醒。如果您的系统提示中已经包含克制性语言（"将顾问留给真正不确定的情况"），请完全跳过提醒，因为这两条指令相互冲突。

纯文本提醒在 Haiku 和 Sonnet 执行者上非常显著：在 Anthropic 的测试中，74%（Sonnet）到 98%（Haiku）的被提醒尝试在第 2 轮立即调用了顾问。如果这发生在您的执行者阅读问题或收集上下文之前，所产生的顾问调用上下文不足，并可能取代一个时机更好的后续调用。在添加提醒之前，请先测量您的执行者的基线首次调用轮次。如果执行者已经可靠地调用顾问，且其首次调用通常发生在第 N 轮，请将 NUDGE_TURN 设置为大于 N。在 Anthropic 的测试中，在基线首次调用为第 7 轮或更晚的工作负载上使用第 2 轮提醒，与任务性能下降 3 到 4 个百分点相关。在基线调用率为 86% 的浏览工作负载上，同样的提醒提高了参与度且没有任务性能损失。

若要在特定请求上强制咨询而不是提醒，请将 tool_choice 设置为 {"type": "tool", "name": "advisor"}，并受强制工具使用中的约束限制。强制工具使用不能与手动 extended thinking（扩展思考）（thinking: {type: "enabled"}）结合使用：如果您同时启用两者，API 会返回 400 invalid_request_error。自适应思考支持强制工具使用。



流式传输

顾问子推理不进行 streaming（流式传输）。执行者的流在顾问运行时暂停；然后完整结果在单个事件中到达。

带有 name: "advisor" 的 server_tool_use 块表示顾问调用正在开始。暂停从该块关闭（content_block_stop）时开始。在暂停期间，流是安静的，只有大约每 30 秒发出一次的标准 SSE ping 保活信号。较短的顾问调用可能不会显示任何 ping。

当顾问完成时，advisor_tool_result 会在单个 content_block_start 事件中完整到达（没有增量）。然后执行者输出恢复流式传输。

随后是一个 message_delta 事件，其中包含更新后的 usage.iterations 数组，反映顾问的令牌计数。



用量与计费

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

{
  "usage": {
    "input_tokens": 1760,
    "cache_read_input_tokens": 412,
    "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-5",
        "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 字段仅反映执行者的令牌。顾问令牌不会汇总到顶层总计中，因为它们按不同的费率计费。type: "advisor_message" 的迭代按顾问模型的费率计费，type: "message" 的迭代按执行者模型的费率计费。

每个顶层 usage 字段都是该字段在所有执行者迭代中的总和，包括 input_tokens、output_tokens 和 cache_read_input_tokens。由于每次执行者迭代都会重新发送不断增长的对话，后续迭代的输入包含先前迭代的输出，因此汇总的 input_tokens 会超过任何单个提示的大小。在构建成本跟踪逻辑时，请使用 usage.iterations 获取完整的逐迭代明细。

顾问输出通常为 400 到 700 个文本令牌，或包括思考在内总计 1,400 到 1,800 个令牌。成本节省来自于顾问不生成您的完整最终输出。这由执行者以其较低的费率完成。

顶层 max_tokens 仅适用于执行者输出。它不限制顾问子推理的令牌。若要直接限制顾问输出，请在工具定义上设置 max_tokens。顾问的令牌也不会从应用于执行者的任何任务预算中扣除。

Priority Tier 独立适用于每个模型。执行者模型上的 Priority Tier 承诺不会延伸到顾问。只有当您的组织也持有顾问模型的承诺时，顾问调用才会以 Priority Tier 运行。



顾问提示缓存

有两个独立的缓存层。



执行者侧缓存

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



顾问侧缓存

在工具定义上设置 caching，为同一对话内多次调用之间顾问自身的对话记录启用提示缓存：

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

顾问在第 N 次调用时的提示是第 (N-1) 次调用的提示再追加一个片段，因此前缀在各次调用之间是稳定的。启用 caching 后，每次顾问调用都会写入一个缓存条目，下一次调用会读取到该点并仅为增量付费。您会看到在第二次及之后的 advisor_message 迭代中 cache_read_input_tokens 变为非零。

何时启用： 当每个对话中顾问被调用两次或更少时，缓存写入的成本高于读取所节省的成本。缓存在大约三次顾问调用时达到收支平衡，之后收益递增。对于长智能体循环请启用它，对于短任务请保持关闭。

保持一致： 设置一次 caching 并在整个对话中保持不变。在对话中途关闭再打开会导致缓存未命中。



与其他工具结合使用

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

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

执行者可以在同一轮中搜索网络、调用顾问并使用您的自定义工具。顾问的计划可以指导执行者接下来使用哪些工具。



最佳实践



针对编码和智能体任务的提示

顾问工具附带一个内置描述，引导执行者在复杂任务开始时以及遇到困难时调用它。对于研究任务，通常不需要额外的提示。

在编码和智能体任务上，当顾问减少了总工具调用次数和对话长度时，它能以相近的成本产生更高的智能。两个时机推动了这一改进：

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

如果您的智能体暴露了其他类似规划器的工具（例如待办事项列表工具），请提示模型在这些工具之前调用顾问，以便顾问的计划汇入其中。建议的系统提示强化了早期调用模式。请添加您自己的汇入语句，指向您的智能体所暴露的任何规划器工具。



针对编码任务的建议系统提示

在没有系统提示引导的情况下，执行者在某些领域（尤其是编码任务）往往会调用顾问不足。对于您希望顾问调用时机一致且每个任务大约调用两到三次的编码任务，请将以下块添加到执行者系统提示的开头，放在任何其他提及顾问的句子之前。

时机指导：

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.

执行者应如何对待建议（直接放在时机块之后）：

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.



针对编码工作负载上 Haiku 的替代系统提示

Claude Haiku 4.5 会保守地应用默认的顾问指导。这使其在研究和查找工作负载上的调用率保持在适当的低水平，但在编码工作负载上会牺牲质量，而在编码工作负载上早期的顾问咨询总能可靠地带来回报。在一个内部编码基准测试中，以下块的一个近似变体（Hard rule 中的只读例外是在测量之后添加的）使 Haiku 的通过率比内置默认值提高了约 7.5 个百分点。

当您的 Haiku 执行者主要运行编码或写入任务工作负载时，请使用此块替代前面的时机块和建议块：

Consult a stronger reviewer who sees your full conversation transcript.

No parameters. When you call advisor(), your entire history -- task, every tool call and result, your reasoning -- is automatically forwarded. The advisor sees exactly what you've done.

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.

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.

Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first -- that judgment call is exactly where a second opinion is highest-value.

Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.

注意事项： 在一个内部浏览理解基准测试（n = 1,266）中，此块的一个近似变体相对于内置默认值损失了约 4 个百分点的准确率。如果您的工作负载将编码与大量查找或检索混合在一起，请继续使用建议的块，或根据您已经计算的工作负载类型信号来控制替换。



增加 Opus 执行者上的顾问调用

Opus 执行者通常无需额外提示即可以适当的频率调用顾问。如果您的 Opus 执行者在您的工作负载上调用不足，请将以下检查点添加到您的系统提示中：

Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first. That judgment call is exactly where a second opinion is highest-value. (This does not apply to simple factual lookups or arithmetic; those you answer directly.)

Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.

注意事项： 在 Anthropic 的测试中，此块的一个近似变体（Hard rule 中的只读例外是在测量之后添加的）使调用不足任务的通过率提高了约 7 到 10 个百分点，但导致 Opus 在首个操作无需规划的任务上过度调用。在混合工作负载上的净效果大致持平。仅当您观察到 Opus 在咨询本会有帮助的任务上跳过了顾问时才添加它。不要将其作为默认值添加。



缩减顾问输出长度

顾问输出是顾问最大的成本驱动因素，而顶层 max_tokens 并不限制它。顾问将您的系统提示和用户消息都视为关于执行者任务的引用上下文，因此直接针对顾问的指令比第三人称描述被遵循得可靠得多。Anthropic 测试过的最有效的放置位置是用户消息中的一行：

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

这一行可以由您的智能体框架在发送请求之前以编程方式添加为前缀。该限制是一个软约束。顾问偶尔会超出它，因此请要求大约为您真实上限的 80%。

将此方法与针对编码任务的建议系统提示中的时机指导（或者如果您已替换，则使用替代 Haiku 块）配合使用，以获得最强的成本与质量权衡。若需要硬上限而非软请求，请参阅限制顾问输出。



限制顾问输出

在工具定义上设置 max_tokens 以限制顾问每次调用的总输出（思考加文本）：

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
        "max_tokens": 2048,
    }
]

最小值为 1024。将 max_tokens 设置为高于顾问模型自身的输出上限会返回 400 错误。该上限独立适用于每次顾问调用，不在同一请求中的多次调用之间共享。

这不仅仅是硬截断。服务器还会将剩余令牌预算传递给顾问，因此顾问会调整其响应以适应预算。

建议的起点： max_tokens: 2048。在 Anthropic 对一个困难推理基准测试（每种配置 n = 40）的测试中，与不设置上限相比，这将顾问的平均输出减少了约 7 倍，截断率接近零，且没有可检测到的质量下降。最小值 1024 将输出减少了约 10 倍，但截断了约 10% 的调用。在此样本量下，所有配置之间的准确率差异均在噪声范围内。请在您自己的工作负载上进行验证。

困难推理任务引出的顾问输出明显长于前面针对较轻工作负载引用的典型 1,400 到 1,800 个令牌。请使用此表来估算节省比例，而不是将其作为顾问输出的通用基线。

当顾问确实达到上限时，无论您使用哪种顾问模型，结果块在两种结果变体上都会携带 stop_reason: "max_tokens"。使用 stop_reason 来检测被截断的建议，并决定是提高上限还是让执行者在部分指导下继续。API 还会在建议文本后追加 [Advisor output truncated at max_tokens=2048.]（标明您的上限），以便执行者在其自身上下文中看到截断；对于明文 advisor_result 顾问，该标记对您的客户端也可见。这两个信号仅在您在工具定义上设置了 max_tokens 时出现。

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_redacted_result",
    "encrypted_content": "EqQBCkYIBRgCIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
    "stop_reason": "max_tokens"
  }
}

检查 usage.iterations 中对应 advisor_message 条目的 output_tokens，以查看每次调用距离其上限有多近。

与基于提示的方法相比，max_tokens 是硬上限而非软请求。当您需要对成本或延迟有保证的界限时，请使用 max_tokens。当您希望偏向简洁而不冒思路中途被截断的风险时，请使用基于提示的方法（或两者结合）。



与 effort 设置配合

对于编码任务，将中等 effort 的 Sonnet 执行者与 Opus 顾问配对，可以以更低的成本实现与默认 effort 下的 Sonnet 相当的智能。若要获得最高智能，请将执行者保持在默认 effort。



成本控制

• 对于对话级别的预算，请在客户端统计顾问调用次数。当达到上限时，从 tools 中移除顾问工具；您无需从消息历史中剥离 advisor_tool_result 块（请参阅多轮对话中的说明）。
• 仅对预计会有三次或更多顾问调用的对话启用 caching。



模型兼容性

"Executor model"（执行者模型，即顶层的 model 字段）与 "advisor model"（顾问模型，即工具定义内部的 model 字段）必须构成有效的配对。顾问模型必须是 Claude Sonnet 4.6 或能力更强的模型，并且其能力必须至少与执行者模型相当。能力相当的模型（例如 Claude Opus 4.7 和 Claude Opus 4.8）可以互相担任顾问。

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



平台可用性

顾问工具目前在 Claude API 和 AWS 上的 Claude Platform 上以 beta 形式提供。目前尚未在 Amazon Bedrock、Google Cloud 或 Microsoft Foundry 上提供。



Claude Managed Agents 上的顾问

Claude Managed Agents 会话同样支持顾问，但它是作为智能体配置的一部分而非作为工具定义来配置的：在智能体的多智能体名册（multiagent roster）中添加一个 {"type": "advisor", "model": ...} 条目，会话的主线程即可在回合中途咨询该模型。该名册条目不接受 max_uses、max_tokens 或 caching 选项，并且建议会以会话事件流上的线程事件形式传递，而不是以响应中的 advisor_tool_result 块形式传递。请参阅为会话配置顾问。



后续步骤