顧問工具

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

此模式適合長時程的代理式工作負載（程式碼代理、電腦操作、多步驟研究管線），這類工作中大多數輪次都是機械性的，但擁有一個優秀的計畫至關重要。您可以獲得接近單獨使用顧問模型的品質，而大部分的 token 生成則以執行者模型的費率進行。如需實測結果，包括當執行者本身的能力接近顧問時效益如何縮減，請參閱針對成本與智慧進行最佳化。



何時使用

顧問適合以下配置：

• 您目前在複雜任務上使用 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 提供的系統提示下運作，並在其輸入中以引用上下文的形式接收執行者的完整對話記錄。該對話記錄包含您的系統提示、工具定義、先前的輪次與工具結果，以及執行者在本輪中迄今已產出的文字。
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 欄位是一個可辨識聯集（discriminated union）。對於成功的呼叫，變體取決於顧問模型：

以下是同一個請求發送兩次，除了工具定義中的顧問 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,
)

您可以在後續輪次中從 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"}，並受強制工具使用中的限制約束。強制工具使用無法與手動擴展思考（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 事件中到達（沒有 delta）。執行者輸出隨後恢復串流。

接著會有一個 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 後，每次顧問呼叫都會寫入一個快取項目，下一次呼叫會讀取到該點為止，只需支付差異部分的費用。您會看到 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-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 錯誤。此上限獨立適用於每次顧問呼叫，不在同一請求中的多次呼叫之間共用。

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

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

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

當顧問確實達到上限時，無論您使用哪個顧問模型，結果區塊在兩種結果變體上都會帶有 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 以及 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 區塊形式傳遞。請參閱為工作階段指定顧問。



後續步驟