顾问工具

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

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



何时使用

顾问适用于以下配置：

• 您目前在复杂任务上使用 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、Claude Fable 5 或 Claude Mythos 5 作为顾问时，该块的 content 字段是 advisor_redacted_result 变体（已加密；执行器在服务器端读取，但您的客户端无法读取）。如需在响应中直接查看建议文本，请改用 claude-opus-4-8 作为顾问模型，它会返回明文的 advisor_result 变体。有关这两种形式，请参阅结果变体；有关有效配对的完整列表，请参阅模型兼容性。



工作原理

当您将顾问工具添加到 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 块。以下示例展示了由 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 字段是一个可辨识联合类型。对于成功的调用，变体取决于顾问模型：

Claude Opus 5、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。此示例使用 claude-opus-4-8 作为顾问，以便在 response.content 中可以看到明文建议；对于任何顾问模型，机制都是相同的。

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-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 测试版标头，以便这些历史块被接受。



恢复暂停的轮次

当顾问调用仍处于待处理状态时，响应可能以 stop_reason: "pause_turn" 结束。发生这种情况时，响应包含顾问的 server_tool_use 块，但没有对应的 advisor_tool_result。要恢复，请将该助手消息原封不动地追加到 messages 中（保留 server_tool_use 块），并使用相同的顾问工具和测试版标头再次发送请求。您无需添加用户消息或 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"}，但需遵守强制工具使用中的约束。强制工具使用不能与手动扩展思考（thinking: {type: "enabled"}）结合使用：如果同时启用两者，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": 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 后，每次顾问调用都会写入一个缓存条目，下一次调用会读取到该点，只需为增量部分付费。您会看到在第二次及之后的 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 对默认顾问指导的应用较为保守。这使其在研究和查询工作负载上的调用率保持在适当的低水平，但在编码工作负载上会牺牲质量，因为在编码工作负载中，早期的顾问咨询通常能可靠地收回成本。在内部编码基准测试中，以下块的一个近似变体（硬性规则中的只读豁免是在测量后添加的）使 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 的测试中，此块的一个近似变体（硬性规则中的只读豁免是在测量后添加的）使调用不足任务的通过率提高了约 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 块（请参阅多轮对话中的说明）。
• 仅对预期有三次或更多顾问调用的对话启用 caching。



模型兼容性

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

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



平台可用性

顾问工具目前在 Claude API 和 AWS 上的 Claude Platform 中以测试版形式提供。目前尚不支持 Amazon Bedrock、Google Cloud 或 Microsoft Foundry。



Claude 托管智能体中的顾问

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



后续步骤