顾问工具

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

这种模式适合长周期的智能体工作负载（编码智能体、计算机使用、多步骤研究流水线），其中大多数轮次是机械性的，但拥有出色的计划至关重要。您可以获得接近仅使用顾问模型的质量，同时大部分令牌生成以执行器模型的费率进行。



何时使用

顾问适合以下配置：

• 您目前在复杂任务上使用 Sonnet： 添加 Opus 作为顾问，以相近或更低的总成本获得质量提升。
• 您目前使用 Haiku 并希望提升智能水平： 添加 Opus 作为顾问。预期成本高于单独使用 Haiku，但低于将执行器切换为更大的模型。

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

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



模型兼容性

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

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



平台可用性

顾问工具在 Claude API 和 Claude Platform on AWS 上以测试版提供。目前在 Amazon Bedrock、Google Cloud 或 Microsoft Foundry 上不可用。



快速开始

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

print(response)



工作原理

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

1. 执行器发出一个 server_tool_use 块，其中 name: "advisor" 且 input 为空。执行器发出时机信号，服务器提供上下文。
2. Anthropic 在服务器端对顾问模型运行一次独立的推理。顾问在其自己的由 Anthropic 提供的系统提示下运行，并在其输入中以引用上下文的形式接收执行器的完整对话记录。该对话记录包括您的系统提示、工具定义、先前的轮次和工具结果，以及执行器在本轮中到目前为止生成的文本。
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 块：

{
  "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 字段是一个可区分联合类型。对于成功的调用，变体取决于顾问模型：

Claude Fable 5 和 Claude Mythos 5 顾问返回 advisor_redacted_result。兼容性表中的其他顾问模型返回 advisor_result。

当您在工具定义上设置了 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"
  }
}

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

顾问的速率限制与直接调用顾问模型使用同一个按模型划分的配额桶。顾问上的速率限制会在工具结果中显示为 too_many_requests。执行器上的速率限制会使整个请求以 HTTP 429 失败。



多轮对话

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

client = anthropic.Anthropic()

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

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_result 块，API 会返回 400 invalid_request_error。



恢复暂停的轮次

响应可能以 stop_reason: "pause_turn" 结束，而此时顾问调用仍处于待处理状态。发生这种情况时，响应包含顾问的 server_tool_use 块，但没有对应的 advisor_tool_result。要恢复，请将该助手消息原封不动地追加到 messages 中，保留 server_tool_use 块，然后使用相同的顾问工具和测试版标头再次发送请求。您不需要添加用户消息或 tool_result 块。API 会运行待处理的顾问调用，并在新响应中继续执行器的轮次。恢复的轮次可能再次暂停。如果发生这种情况，请重复相同的步骤。在恢复请求中省略顾问工具会返回 400 invalid_request_error。如果执行器在同一轮中还调用了您的某个工具，则响应会以 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-4-8"},
    # ... 您的其他工具
]
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(
        b.type == "server_tool_use" and b.name == "advisor" for b 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"}，但需遵守强制工具使用中的约束。强制工具使用不能与扩展思考结合使用：如果同时启用两者，API 会返回 400 invalid_request_error。



流式传输

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

带有 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": 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-8",
        "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" 的迭代按执行器模型的费率计费。

聚合规则因字段而异。顶层 output_tokens 是所有执行器迭代的总和。顶层 input_tokens 和 cache_read_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-4-8",
        "caching": {"type": "ephemeral", "ttl": "5m"},
    }
]

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

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

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



与其他工具组合

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

tools = [
    {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 5,
    },
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-8",
    },
    {
        "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 规则中的只读豁免是在测量之后添加的）使 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 规则中的只读豁免是在测量之后添加的）使调用不足的任务的通过率提高了大约 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-4-8",
        "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"。API 还会在建议文本后追加 [Advisor output truncated at max_tokens=2048.]（标明您的上限），以便执行器在其自身上下文中看到截断。使用 stop_reason 来检测被截断的建议，并决定是提高上限还是让执行器在部分指导下继续。只有当您在工具定义上设置了 max_tokens 时，这两个信号才会出现。

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_result",
    "text": "Use a channel-based coordination pattern. The tricky part is\n\n[Advisor output truncated at max_tokens=2048.]",
    "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 块，以避免 400 invalid_request_error（参见多轮对话中的注释）。
• 仅对预期有三次或更多顾问调用的对话启用 caching。



后续步骤