Advisor 工具

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

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

何时使用

advisor 适用于以下配置：

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

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

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

快速开始

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 变体。请参阅结果变体以并排查看两种形状以及哪些顾问模型返回哪种，并参阅模型兼容性以获取有效配对的完整列表。

工作原理

当您将 advisor 工具添加到 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 不同，这不是断点标记。它是一个开/关开关。服务器决定缓存边界的位置。

advisor 工具还接受任何工具定义上可用的通用属性：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"
  }
}

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

顾问速率限制从与直接调用顾问模型相同的每模型桶中提取。顾问上的速率限制在工具结果内显示为 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,
)

当消息历史记录仍然包含 advisor_tool_result 块时，您可以在后续回合中从 tools 中删除 advisor 工具。请求会被接受，历史块会被保留；模型无法在该回合调用顾问。您仍然必须发送 advisor-tool-2026-03-01 测试版标头，以便接受这些历史块。

恢复暂停的回合

响应可能以 stop_reason: "pause_turn" 结束，而顾问调用仍在等待中。发生这种情况时，响应包含顾问的 server_tool_use 块，但没有对应的 advisor_tool_result。要恢复，请将该助手消息附加到 messages，其内容保持不变，保留 server_tool_use 块，并使用相同的 advisor 工具和测试版标头再次发送请求。您无需添加用户消息或 tool_result 块。API 运行待处理的顾问调用，并在新响应中继续执行器的回合。恢复的回合可能会再次暂停。如果发生这种情况，请重复相同的步骤。从恢复请求中省略 advisor 工具会返回 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"}，受强制工具使用中的约束限制。强制工具使用不能与手动扩展思考（thinking: {type: "enabled"}）结合使用：如果您同时启用两者，API 将返回 400 invalid_request_error。自适应思考支持强制工具使用。Claude Fable 5.1 和 Claude Mythos 5.1 执行器拒绝 tool_choice 类型 tool 和 any，因此请在这些模型上改用提示提醒。

流式传输

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

带有 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。顾问的令牌也不会从应用于执行器的任何任务预算中提取。

优先级层级独立应用于每个模型。执行器模型上的优先级层级承诺不会扩展到顾问。只有当您的组织也持有顾问模型的承诺时，顾问调用才会以优先级层级运行。

顾问提示缓存

有两个独立的缓存层。

执行器端缓存

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 后，每次顾问调用都会写入一个缓存条目，下一次调用读取到该点并仅为增量付费。您将看到 cache_read_input_tokens 在第二次及以后的 advisor_message 迭代中变为非零。

何时启用： 当每个对话调用顾问两次或更少时，缓存写入的成本超过读取节省的成本。缓存在大约三次顾问调用时达到收支平衡，并从那里开始改善。为长智能体循环启用它，并为短任务保持关闭。

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

与其他工具结合

advisor 工具可与其他服务器端和客户端工具组合。将它们全部添加到同一个 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"}},
        },
    },
]

执行器可以在同一回合中搜索网络、调用顾问并使用您的自定义工具。顾问的计划可以告知执行器接下来使用哪些工具。

最佳实践

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

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

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

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-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。

模型兼容性

执行器模型（顶层 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 上以 beta 形式提供。目前在 Amazon Bedrock、Google Cloud 或 Microsoft Foundry 上尚不可用。

Claude Managed Agents 上的顾问

Claude Managed Agents 会话也支持顾问，它作为代理的一部分进行配置，而不是作为工具定义：在代理的多代理名册中添加一个 {"type": "advisor", "model": ...} 条目，会话的主线程就可以在回合中途咨询该模型。名册条目不接受 max_uses、max_tokens 或 caching 选项，并且建议会作为会话事件流上的线程事件传递，而不是作为响应中的 advisor_tool_result 块。请参阅为会话提供顾问。

后续步骤