顧問工具

顧問工具讓更快、成本更低的執行器模型在生成過程中諮詢更高智能的顧問模型以獲得戰略指導。顧問讀取完整的對話，產生計畫或課程修正（通常 400 到 700 個文本令牌，包括思考的 1,400 到 1,800 個令牌），然後執行器繼續執行任務。

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

何時使用

早期基準測試顯示這些配置有顯著的改進：

• 您目前在複雜任務上使用 Sonnet： 添加 Opus 作為顧問，以獲得品質提升，成本相同或更低。
• 您目前使用 Haiku 並想要智能提升： 添加 Opus 作為顧問。預期成本高於單獨使用 Haiku，但低於將執行器切換到更大的模型。

結果取決於任務。在您自己的工作負載上進行評估。

顧問對於單轉 Q&A（沒有計畫）、純粹的傳遞模型選擇器（您的使用者已經選擇自己的成本和品質權衡）或每個轉向都真正需要顧問模型完整功能的工作負載來說不太適合。

模型相容性

執行器模型（頂級 model 欄位）和顧問模型（工具定義內的 model 欄位）必須形成有效的配對。顧問的能力必須至少與執行器相同。

如果您請求無效的配對，API 會返回 400 invalid_request_error，命名不支援的組合。

平台可用性

顧問工具在 Claude API (Anthropic) 上以測試版形式提供。

快速開始

運作方式

當您將顧問工具添加到 tools 陣列時，執行器模型決定何時呼叫它，就像任何其他工具一樣。當執行器呼叫顧問時：

1. 執行器發出一個 server_tool_use 區塊，其中 name: "advisor" 和空的 input。執行器發出時間信號；伺服器提供上下文。
2. Anthropic 在顧問模型伺服器端運行單獨的推理傳遞，傳遞執行器的完整記錄。顧問看到系統提示、所有工具定義、所有先前的轉向和所有先前的工具結果。
3. 顧問的回應作為 advisor_tool_result 區塊返回給執行器。
4. 執行器繼續生成，受到建議的啟發。

所有這一切都發生在單個 /v1/messages 請求內。您這邊沒有額外的往返。

顧問本身運行時沒有工具和沒有上下文管理。其思考區塊在結果返回前被丟棄；只有建議文本到達執行器。

工具參數

caching 物件的形狀為 {"type": "ephemeral", "ttl": "5m" | "1h"}。與內容區塊上的 cache_control 不同，這不是斷點標記；它是開/關開關。伺服器決定快取邊界的位置。

回應結構

成功的顧問呼叫

當顧問被呼叫時，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 欄位是一個判別聯合。您收到哪個變體取決於顧問模型：

使用 advisor_result 時，text 欄位包含人類可讀的建議。使用 advisor_redacted_result 時，encrypted_content 欄位包含您無法讀取的不透明 blob；在下一個轉向，伺服器解密它並將純文本呈現到執行器的提示中。

在兩種情況下，在後續轉向上逐字往返內容。如果您在對話中途切換顧問模型，請根據 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：

import anthropic

client = anthropic.Anthropic()

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

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,
)

# Append the full response content, including any advisor_tool_result blocks
messages.append({"role": "assistant", "content": response.content})

# Continue the conversation
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。

串流

顧問子推理不串流。執行器的串流在顧問運行時暫停，然後完整結果在單個事件中到達。

server_tool_use 區塊，其中 name: "advisor" 表示顧問呼叫正在開始。暫停在該區塊關閉時開始（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-7",
        "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 僅適用於執行器輸出。它不限制顧問子推理令牌。顧問的令牌也不會從應用於執行器的任何任務預算中提取。

顧問提示快取

有兩個獨立的快取層。

執行器端快取

advisor_tool_result 區塊像任何其他內容區塊一樣可快取。在後續轉向後放置的 cache_control 斷點將命中。執行器的提示始終包含純文本建議，無論您的客戶端是否收到 text 或 encrypted_content，因此兩個結果變體的快取行為相同。

顧問端快取

在工具定義上設置 caching 以為顧問在同一對話中跨呼叫的自己的記錄啟用提示快取：

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-7",
        "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-7",
    },
    {
        "name": "run_bash",
        "description": "Run a bash command",
        "input_schema": {
            "type": "object",
            "properties": {"command": {"type": "string"}},
        },
    },
]

執行器可以在同一轉向中搜尋網路、呼叫顧問並使用您的自訂工具。顧問的計畫可以告知執行器接下來要使用哪些工具。

最佳實踐

編碼和代理任務的提示

顧問工具附帶內建描述，推動執行器在複雜任務開始時和遇到困難時呼叫它。對於研究任務，通常不需要額外的提示。

在編碼和代理任務上，當顧問減少總工具呼叫和對話長度時，它以相似的成本產生更高的智能。兩個時機驅動此改進：

1. 早期第一個顧問呼叫，在記錄中進行了幾次探索性讀取之後。
2. 對於困難的任務，在檔案寫入和測試輸出在記錄中之後的最終顧問呼叫。

如果您的代理公開其他類似計畫的工具（例如，待辦事項清單工具），提示模型在這些工具之前呼叫顧問，以便顧問的計畫流入它們。下面建議的系統提示強化了早期呼叫模式；添加您自己的漏斗句子，指向您的代理公開的任何計畫工具。

編碼任務的建議系統提示

對於編碼任務，其中您想要一致的顧問時機和每個任務大約兩到三個呼叫，在任何其他提及顧問的句子之前，將以下區塊前置到您的執行器系統提示。在內部編碼評估中，此模式產生了最高的智能，成本接近 Sonnet。

時機指導：

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.

修剪顧問輸出長度

顧問輸出是顧問的最大成本驅動因素。若要減少該成本，在任何其他提及顧問的句子之前，將單個簡潔指令前置到系統提示。在內部測試中，以下行將總顧問輸出令牌減少了大約 35 到 45 百分比，而不改變呼叫頻率：

The advisor should respond in under 100 words and use enumerated steps, not explanations.

將此與上面的時機區塊配對，以獲得最強的成本與品質權衡。

與努力設置配對

對於編碼任務，將 Sonnet 執行器與中等努力配對，Opus 顧問實現與預設努力下 Sonnet 相當的智能，成本更低。為了獲得最高智能，保持執行器在預設努力。

成本控制

• 對於對話級別預算，在客戶端計數顧問呼叫。當您達到上限時，從 tools 中移除顧問工具並從訊息歷史記錄中移除所有 advisor_tool_result 區塊，以避免 400 invalid_request_error。
• 僅對您預期三個或更多顧問呼叫的對話啟用 caching。

限制

• 顧問輸出不串流。 預期在子推理運行時串流中暫停。
• 顧問呼叫上沒有內建對話級別上限。 在客戶端追蹤和限制它們。
• max_tokens 僅適用於執行器輸出。 它不限制顧問令牌。
• Anthropic 優先級層級按模型受尊重。執行器模型上的優先級層級不延伸到顧問；您需要在顧問模型上特別設置優先級層級。