Advisor 工具

Advisor 工具讓較快速、成本較低的**執行器模型（executor model）在生成過程中諮詢更高智慧的顧問模型（advisor model）**以獲取策略性指引。顧問會讀取完整對話內容，產出計畫或修正方向，然後執行器繼續執行任務。

此模式適合長時程的代理型工作負載（程式碼代理、電腦操作、多步驟研究管線），其中大多數回合是機械性的，但擁有出色的計畫至關重要。您可以獲得接近顧問單獨運作的品質，同時大部分的 token 生成以執行器模型的費率進行。



使用時機

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、Claude Fable 5 或 Claude Mythos 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 欄位是一個判別聯集（discriminated union）。對於成功的呼叫，變體取決於顧問模型：

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 工具，即使訊息歷史記錄中仍包含 advisor_tool_result 區塊。請求會被接受且歷史區塊會被保留；模型在該回合無法呼叫顧問。您仍必須傳送 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。自適應思考支援強制工具使用。



串流

顧問子推論不會串流。執行器的串流會在顧問運作時暫停；然後完整結果會在單一事件中到達。

帶有 name: "advisor" 的 server_tool_use 區塊表示顧問呼叫正在開始。暫停從該區塊關閉（content_block_stop）時開始。在暫停期間，串流除了大約每 30 秒發出的標準 SSE ping 保持連線訊號外是靜默的。短暫的顧問呼叫可能不會顯示任何 ping。

當顧問完成時，advisor_tool_result 會在單一 content_block_start 事件中完整到達（沒有增量）。執行器輸出隨後恢復串流。

接著會有一個 message_delta 事件，其中更新的 usage.iterations 陣列反映顧問的 token 計數。



用量與計費

顧問呼叫作為獨立的子推論執行，以顧問模型的費率計費。用量在 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 欄位僅反映執行器的 token。顧問 token 不會計入頂層總計，因為它們以不同的費率計費。type: "advisor_message" 的迭代以顧問模型的費率計費，type: "message" 的迭代以執行器模型的費率計費。

每個頂層 usage 欄位是該欄位在所有執行器迭代中的總和，包括 input_tokens、output_tokens 和 cache_read_input_tokens。由於每個執行器迭代都會重新傳送不斷增長的對話，後續迭代的輸入包含先前迭代的輸出，因此加總的 input_tokens 會超過任何單一提示的大小。在建立成本追蹤邏輯時，請使用 usage.iterations 取得完整的每迭代明細。

顧問輸出通常為 400 到 700 個文字 token，或包含思考在內總計 1,400 到 1,800 個 token。成本節省來自於顧問不生成您的完整最終輸出。執行器以其較低的費率完成該工作。

頂層 max_tokens 僅適用於執行器輸出。它不限制顧問子推論的 token。若要直接限制顧問輸出，請在工具定義上設定 max_tokens。顧問的 token 也不會從套用於執行器的任何任務預算中扣除。

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 一次後，在整個對話中保持不變。在對話中途切換開關會導致快取未命中。



與其他工具結合

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 會保守地套用預設的顧問指引。這使其在研究和查詢工作負載上的呼叫率保持適當的低水準，但在程式碼工作負載上會犧牲品質，因為早期的顧問諮詢在這類工作負載上可靠地物有所值。在內部程式碼基準測試中，以下區塊的近似變體（硬性規則中的唯讀排除條款是在測量後新增的）使 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 錯誤。此上限獨立套用於每次顧問呼叫，不會在同一請求中的各次呼叫間共用。

這不僅僅是硬性截斷。伺服器也會將剩餘 token 預算傳遞給顧問，因此顧問會調整其回應以符合限制。

建議起始點：max_tokens: 2048。在 Anthropic 對困難推理基準測試（每個配置 n = 40）的測試中，與未設定上限相比，這使平均顧問輸出減少了約 7 倍，幾乎沒有截斷且沒有可偵測的品質劣化。最小值 1024 使輸出減少約 10 倍，但約 10% 的呼叫被截斷。在此樣本大小下，所有配置的準確率差異都在雜訊範圍內。請在您自己的工作負載上驗證。

困難推理任務引發的顧問輸出明顯長於前述針對較輕工作負載引用的典型 1,400 到 1,800 個 token。請使用此表格來估算節省比率，而非作為顧問輸出的通用基準。

當顧問確實達到上限時，結果區塊會帶有 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 工具；您不需要從訊息歷史記錄中移除 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 以測試版形式提供。目前尚未在 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 區塊形式傳遞。請參閱為工作階段提供顧問。



後續步驟