Ferramenta advisor

A ferramenta advisor permite que um modelo executor mais rápido e de menor custo consulte um modelo advisor de maior inteligência durante a geração para obter orientação estratégica. O advisor lê a conversa completa, produz um plano ou correção de rumo, e o executor continua com a tarefa.

Esse padrão se adequa a cargas de trabalho agênticas de longo horizonte (agentes de codificação, uso de computador, pipelines de pesquisa com múltiplas etapas) em que a maioria dos turnos é mecânica, mas ter um plano excelente é crucial. Você obtém qualidade próxima à do advisor sozinho, enquanto a maior parte da geração de tokens acontece às taxas do modelo executor.



Quando usar

O advisor se adequa a estas configurações:

• Você atualmente usa Sonnet em tarefas complexas: Adicione um advisor de nível superior. Opus mantém o custo total semelhante ou menor; Claude Fable 5 maximiza o ganho de qualidade.
• Você atualmente usa Haiku e quer um salto de inteligência: Adicione um advisor Opus ou Fable. Espere um custo maior do que Haiku sozinho, mas menor do que trocar o executor por um modelo maior.

Os resultados dependem da tarefa. Avalie na sua própria carga de trabalho.

O advisor é menos adequado para perguntas e respostas de turno único (nada a planejar), seletores de modelo puramente pass-through em que seus usuários já escolhem sua própria relação custo-qualidade, ou cargas de trabalho em que cada turno genuinamente requer a capacidade total do modelo advisor.



Início rápido

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)

O content da resposta inclui um bloco advisor_tool_result contendo a orientação do advisor. Com Claude Opus 5, Claude Fable 5 ou Claude Mythos 5 como advisor, o campo content do bloco é uma variante advisor_redacted_result (criptografada; o executor a lê no lado do servidor, mas seu cliente não). Para ver o texto do conselho diretamente na sua resposta, use claude-opus-4-8 como modelo advisor, que retorna a variante advisor_result em texto simples. Consulte Variantes de resultado para ambos os formatos e Compatibilidade de modelos para a lista completa de pares válidos.



Como funciona

Quando você adiciona a ferramenta advisor ao seu array tools, o modelo executor determina quando chamá-la, como qualquer outra ferramenta. Quando o executor chama o advisor:

1. O executor emite um bloco server_tool_use com name: "advisor" e um input vazio. O executor sinaliza o momento, e o servidor fornece o contexto.
2. A Anthropic executa uma passagem de inferência separada no modelo advisor no lado do servidor. O advisor é executado sob seu próprio prompt do sistema fornecido pela Anthropic e recebe a transcrição completa do executor como contexto citado em sua entrada. Essa transcrição inclui seu prompt do sistema, as definições de ferramentas, os turnos anteriores e resultados de ferramentas, e o texto que o executor produziu até agora neste turno.
3. A resposta do advisor retorna ao executor como um bloco advisor_tool_result.
4. O executor continua gerando, informado pelo conselho.

Tudo isso ocorre dentro de uma única requisição /v1/messages, sem idas e voltas extras do seu lado. A exceção é um turno que pausa no meio da chamada, que você retoma com uma requisição de acompanhamento (consulte Retomando um turno pausado).

O próprio advisor é executado sem ferramentas e sem gerenciamento de contexto. Seus blocos de pensamento são descartados antes que o resultado retorne. Apenas o texto do conselho chega ao executor.



Parâmetros da ferramenta

O objeto caching tem o formato {"type": "ephemeral", "ttl": "5m" | "1h"}. Diferentemente de cache_control em blocos de conteúdo, este não é um marcador de ponto de interrupção. É um interruptor liga/desliga. O servidor determina onde ficam os limites do cache.

A ferramenta advisor também aceita as propriedades genéricas disponíveis em qualquer definição de ferramenta: cache_control, allowed_callers, defer_loading e strict (abordado em saídas estruturadas). Consulte a Referência de ferramentas para a semântica delas.



Estrutura da resposta



Chamada ao advisor bem-sucedida

Quando o advisor é chamado, um bloco server_tool_use é seguido por um bloco advisor_tool_result no conteúdo do assistente. O exemplo a seguir mostra a variante advisor_result em texto simples retornada por um advisor Claude Opus 4.8. O Início rápido usa Claude Opus 5, que retorna a variante criptografada advisor_redacted_result; consulte Variantes de resultado.

{
  "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..."
    }
  ]
}

O server_tool_use.input está sempre vazio. O servidor constrói a visão do advisor a partir da transcrição completa automaticamente. Nada que o executor coloque em input chega ao advisor.



Variantes de resultado

O campo advisor_tool_result.content é uma união discriminada. Para chamadas bem-sucedidas, a variante depende do modelo advisor:

Advisors Claude Opus 5, Claude Fable 5 e Claude Mythos 5 retornam advisor_redacted_result. Os outros modelos advisor na tabela de compatibilidade retornam advisor_result.

Ambas as variantes de resultado carregam um campo stop_reason quando você define max_tokens na definição da ferramenta, e o omitem quando você não define. Ele contém o motivo de parada da sub-chamada do advisor, tipicamente "end_turn", ou "max_tokens" quando o limite é atingido. Os valores correspondem ao stop_reason de nível superior da API Messages.

Com advisor_result, o campo text contém conselho legível por humanos. Com advisor_redacted_result, o campo encrypted_content contém um blob opaco que você não pode ler. No próximo turno, o servidor o descriptografa e renderiza o texto simples no prompt do executor.

Em ambos os casos, retransmita o conteúdo literalmente nos turnos subsequentes. Se você trocar de modelo advisor no meio da conversa, ramifique com base em content.type para lidar com ambos os formatos.



Resultados de erro

Se a chamada ao advisor falhar, o resultado carrega um erro:

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_tool_result_error",
    "error_code": "overloaded"
  }
}

O executor vê o erro e continua sem mais conselhos. A requisição em si não falha.

Os limites de taxa do advisor consomem do mesmo bucket por modelo que chamadas diretas ao modelo advisor. Um limite de taxa no advisor aparece como too_many_requests dentro do resultado da ferramenta. Um limite de taxa no executor faz a requisição inteira falhar com HTTP 429.



Conversas multi-turno

Passe o conteúdo completo do assistente, incluindo blocos advisor_tool_result, de volta para a API nos turnos subsequentes. Este exemplo usa claude-opus-4-8 como advisor para que o conselho em texto simples fique visível em response.content; a mecânica é idêntica para qualquer modelo advisor.

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

# Anexe o conteúdo completo da resposta, incluindo quaisquer blocos advisor_tool_result
messages.append({"role": "assistant", "content": response.content})

# Continue a conversa
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,
)

Você pode remover a ferramenta advisor de tools em um turno de acompanhamento enquanto o histórico de mensagens ainda contém blocos advisor_tool_result. A requisição é aceita e os blocos históricos são preservados; o modelo não pode chamar o advisor nesse turno. Você ainda deve enviar o cabeçalho beta advisor-tool-2026-03-01 para que esses blocos de histórico sejam aceitos.



Retomando um turno pausado

Uma resposta pode terminar com stop_reason: "pause_turn" enquanto uma chamada ao advisor ainda está pendente. Quando isso ocorre, a resposta contém o bloco server_tool_use do advisor sem um advisor_tool_result correspondente. Para retomar, anexe essa mensagem do assistente a messages com seu conteúdo inalterado, mantendo o bloco server_tool_use, e envie a requisição novamente com a mesma ferramenta advisor e cabeçalho beta. Você não precisa adicionar uma mensagem de usuário ou um bloco tool_result. A API executa a chamada pendente ao advisor e continua o turno do executor na nova resposta. Um turno retomado pode pausar novamente. Se isso acontecer, repita o mesmo passo. Omitir a ferramenta advisor da requisição de retomada retorna um 400 invalid_request_error, porque o bloco server_tool_use pendente não tem definição de ferramenta para executar; inclua a ferramenta sempre que uma chamada estiver pendente. Se, em vez disso, o executor chamou uma das suas ferramentas no mesmo turno, a resposta termina com stop_reason: "tool_use" enquanto a chamada ao advisor ainda está pendente. Envie os blocos tool_result como de costume, e a chamada pendente ao advisor é executada no início dessa próxima requisição. Consulte Combinando ferramentas de servidor e ferramentas de cliente em um turno.



Lembrete no meio da conversa para executores que chamam pouco

Se um executor Haiku não chamou o advisor em seu primeiro turno de assistente, anexe um breve lembrete como uma mensagem de usuário adicional antes do segundo turno de assistente. Na avaliação comportamental interna da Anthropic, isso aumentou as taxas de aprovação de tarefas em aproximadamente 7 pontos percentuais em executores Haiku. Em executores Sonnet, o lembrete em texto simples não teve efeito mensurável nos testes da Anthropic. As considerações de timing de chamada a seguir são especialmente relevantes para Sonnet. Não aplique o lembrete a executores Opus: no Opus, ele reduziu ligeiramente as taxas de aprovação.

Com o NUDGE_TURN padrão de 2, o lembrete normalmente chega depois que o modelo se orientou na tarefa, mas antes de se comprometer com uma abordagem.

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):
    # Substitua pelo seu despacho de ferramentas. Retorna um bloco tool_result por bloco tool_use.
    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"},
    # ... suas outras ferramentas
]
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})
    # Pule isto se seu prompt do sistema já instrui o modelo a chamar com moderação.
    if turn == NUDGE_TURN - 1 and not advisor_called:
        messages.append({"role": "user", "content": NUDGE_TEXT})

Anexe o lembrete como sua própria mensagem de usuário após os resultados de ferramentas, em vez de como um bloco irmão na mesma mensagem. Mensagens de usuário consecutivas são válidas. Nos testes da Anthropic em executores Haiku e Sonnet, elas se comportaram de forma equivalente a um bloco irmão. O formato de mensagem separada também mantém o lembrete claramente distinto da saída de ferramentas.

Trade-offs: O lembrete aumenta a taxa de chamadas, o que pode levar tarefas trivialmente simples a uma consulta desnecessária. Se sua carga de trabalho mistura tarefas simples e complexas, considere aumentar NUDGE_TURN para 3 para que tarefas de dois turnos sejam concluídas antes que o lembrete seja disparado, ou condicione o lembrete a um sinal de complexidade de tarefa que você já calcula. Se seu prompt do sistema já contém linguagem de contenção ("reserve o advisor para incerteza genuína"), pule o lembrete completamente, porque as duas instruções entram em conflito.

O lembrete em texto simples é altamente saliente em executores Haiku e Sonnet: 74% (Sonnet) a 98% (Haiku) das tentativas com lembrete nos testes da Anthropic chamaram o advisor imediatamente no turno 2. Se isso ocorrer antes de seu executor ter lido o problema ou coletado contexto, a chamada resultante ao advisor tem pouco contexto e pode substituir uma chamada posterior com melhor timing. Meça o turno de primeira chamada baseline do seu executor antes de adicionar o lembrete. Se o executor já chama o advisor de forma confiável e sua primeira chamada normalmente ocorre no turno N, defina NUDGE_TURN maior que N. Nos testes da Anthropic, um lembrete no turno 2 em cargas de trabalho onde a primeira chamada baseline era no turno 7 ou posterior correlacionou-se com uma queda de 3 a 4 pontos percentuais no desempenho da tarefa. Em uma carga de trabalho de navegação onde a taxa de chamada baseline era 86%, o mesmo lembrete aumentou o engajamento sem custo de desempenho da tarefa.

Para forçar uma consulta em uma requisição específica em vez de usar o lembrete, defina tool_choice como {"type": "tool", "name": "advisor"}, sujeito às restrições em Forçando o uso de ferramentas. Forçar o uso de ferramentas não pode ser combinado com pensamento estendido manual (thinking: {type: "enabled"}): a API retorna um 400 invalid_request_error se você habilitar ambos. O pensamento adaptativo suporta uso forçado de ferramentas.



Streaming

A sub-inferência do advisor não faz streaming. O stream do executor pausa enquanto o advisor é executado; então o resultado completo chega em um único evento.

O bloco server_tool_use com name: "advisor" sinaliza que uma chamada ao advisor está começando. A pausa começa quando esse bloco fecha (content_block_stop). Durante a pausa, o stream fica silencioso, exceto por keepalives ping SSE padrão emitidos aproximadamente a cada 30 segundos. Chamadas curtas ao advisor podem não mostrar pings.

Quando o advisor termina, o advisor_tool_result chega totalmente formado em um único evento content_block_start (sem deltas). A saída do executor então retoma o streaming.

Um evento message_delta segue com o array usage.iterations atualizado refletindo as contagens de tokens do advisor.



Uso e cobrança

Chamadas ao advisor são executadas como uma sub-inferência separada cobrada às taxas do modelo advisor. O uso é reportado no array 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
      }
    ]
  }
}

Os campos usage de nível superior refletem apenas tokens do executor. Tokens do advisor não são incluídos nos totais de nível superior porque são cobrados a uma taxa diferente. Iterações com type: "advisor_message" são cobradas às taxas do modelo advisor, e iterações com type: "message" são cobradas às taxas do modelo executor.

Cada campo usage de nível superior é a soma desse campo em todas as iterações do executor, incluindo input_tokens, output_tokens e cache_read_input_tokens. Como cada iteração do executor reenvia a conversa crescente, as entradas de iterações posteriores incluem a saída de iterações anteriores, então a soma de input_tokens excede o tamanho de qualquer prompt individual. Use usage.iterations para um detalhamento completo por iteração ao construir lógica de rastreamento de custos.

A saída do advisor é tipicamente de 400 a 700 tokens de texto, ou 1.400 a 1.800 tokens no total incluindo pensamento. A economia de custos vem do fato de o advisor não gerar sua saída final completa. O executor faz isso à sua taxa mais baixa.

O max_tokens de nível superior se aplica apenas à saída do executor. Ele não limita tokens de sub-inferência do advisor. Para limitar a saída do advisor diretamente, defina max_tokens na definição da ferramenta. Os tokens do advisor também não consomem de nenhum orçamento de tarefa aplicado ao executor.

O Priority Tier se aplica a cada modelo independentemente. Um compromisso de Priority Tier no modelo executor não se estende ao advisor. Chamadas ao advisor são executadas no Priority Tier apenas se sua organização também tiver um compromisso no modelo advisor.



Cache de prompt do advisor

Existem duas camadas de cache independentes.



Cache do lado do executor

O bloco advisor_tool_result é cacheável como qualquer outro bloco de conteúdo. Um ponto de interrupção cache_control colocado após ele em um turno subsequente é acertado. O prompt do executor sempre contém o conselho em texto simples, independentemente de seu cliente ter recebido text ou encrypted_content, então o comportamento de cache é idêntico para ambas as variantes de resultado.



Cache do lado do advisor

Defina caching na definição da ferramenta para habilitar cache de prompt para a própria transcrição do advisor entre chamadas dentro da mesma conversa:

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
        "caching": {"type": "ephemeral", "ttl": "5m"},
    }
]

O prompt do advisor na N-ésima chamada é o prompt da (N-1)-ésima chamada com mais um segmento anexado, então o prefixo é estável entre chamadas. Com caching habilitado, cada chamada ao advisor grava uma entrada de cache, e a próxima chamada lê até esse ponto e paga apenas pelo delta. Você verá cache_read_input_tokens tornar-se diferente de zero na segunda iteração advisor_message e nas posteriores.

Quando habilitar: A gravação de cache custa mais do que as leituras economizam quando o advisor é chamado duas vezes ou menos por conversa. O cache atinge o ponto de equilíbrio em aproximadamente três chamadas ao advisor e melhora a partir daí. Habilite-o para loops de agente longos e mantenha-o desativado para tarefas curtas.

Mantenha consistente: Defina caching uma vez e deixe-o para toda a conversa. Alternar entre desativado e ativado no meio da conversa causa cache misses.



Combinando com outras ferramentas

A ferramenta advisor se compõe com outras ferramentas do lado do servidor e do lado do cliente. Adicione todas ao mesmo array 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"}},
        },
    },
]

O executor pode pesquisar na web, chamar o advisor e usar suas ferramentas personalizadas no mesmo turno. O plano do advisor pode informar quais ferramentas o executor usará em seguida.



Melhores práticas



Prompting para tarefas de codificação e agentes

A ferramenta advisor vem com uma descrição integrada que incentiva o executor a chamá-la perto do início de tarefas complexas e quando encontra dificuldades. Para tarefas de pesquisa, nenhum prompting adicional é tipicamente necessário.

Em tarefas de codificação e agentes, o advisor produz maior inteligência a custo semelhante quando reduz o total de chamadas de ferramentas e o comprimento da conversa. Dois momentos impulsionam essa melhoria:

1. Uma primeira chamada ao advisor cedo, depois que algumas leituras exploratórias estão na transcrição.
2. Para tarefas difíceis, uma chamada final ao advisor depois que gravações de arquivos e saídas de testes estão na transcrição.

Se seu agente expõe outras ferramentas do tipo planejador (por exemplo, uma ferramenta de lista de tarefas), instrua o modelo a chamar o advisor antes dessas ferramentas para que o plano do advisor seja canalizado para elas. O prompt do sistema sugerido reforça o padrão de chamada antecipada. Adicione sua própria frase de canalização apontando para quaisquer ferramentas de planejamento que seu agente exponha.



Prompt do sistema sugerido para tarefas de codificação

Sem direcionamento no prompt do sistema, o executor tende a chamar o advisor menos do que o ideal em alguns domínios, particularmente tarefas de codificação. Para tarefas de codificação em que você deseja timing consistente do advisor e cerca de duas a três chamadas por tarefa, prefixe os seguintes blocos ao seu prompt do sistema do executor antes de quaisquer outras frases que mencionem o advisor.

Orientação de timing:

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.

Como o executor deve tratar o conselho (coloque diretamente após o bloco de timing):

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.



Prompt do sistema alternativo para Haiku em cargas de trabalho de codificação

Claude Haiku 4.5 aplica a orientação padrão do advisor de forma conservadora. Isso mantém sua taxa de chamadas apropriadamente baixa em cargas de trabalho de pesquisa e consulta, mas sacrifica qualidade em cargas de trabalho de codificação, onde uma consulta antecipada ao advisor compensa de forma confiável. Em um benchmark interno de codificação, uma variante próxima do bloco a seguir (a exceção de somente leitura na regra Hard foi adicionada após a medição) aumentou as taxas de aprovação do Haiku em aproximadamente 7,5 pontos percentuais em relação ao padrão integrado.

Use este bloco no lugar dos blocos anteriores de timing e conselho quando seu executor Haiku executa predominantemente cargas de trabalho de codificação ou tarefas de escrita:

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.

Ressalva: Em um benchmark interno de compreensão de navegação (n = 1.266), uma variante próxima deste bloco custou aproximadamente 4 pontos percentuais de precisão em relação ao padrão integrado. Se sua carga de trabalho mistura codificação com consulta ou recuperação substancial, mantenha os blocos sugeridos, ou condicione a troca a um sinal de tipo de carga de trabalho que você já calcula.



Aumentando chamadas ao advisor em executores Opus

Executores Opus tipicamente chamam o advisor a uma taxa apropriada sem prompting adicional. Se seu executor Opus está chamando menos do que o ideal na sua carga de trabalho, adicione o seguinte checkpoint ao seu prompt do sistema:

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.

Ressalva: Nos testes da Anthropic, uma variante próxima deste bloco (a exceção de somente leitura na regra Hard foi adicionada após a medição) aumentou as taxas de aprovação em tarefas com poucas chamadas em aproximadamente 7 a 10 pontos percentuais, mas fez o Opus chamar em excesso em tarefas cuja primeira ação não precisa de planejamento. O efeito líquido foi aproximadamente neutro em uma carga de trabalho mista. Adicione-o apenas se você observou o Opus pulando o advisor em tarefas onde uma consulta teria ajudado. Não o adicione como padrão.



Reduzindo o comprimento da saída do advisor

A saída do advisor é o maior fator de custo do advisor, e o max_tokens de nível superior não a limita. O advisor vê tanto seu prompt do sistema quanto suas mensagens de usuário como contexto citado sobre a tarefa do executor, então instruções que se dirigem ao advisor diretamente são seguidas de forma muito mais confiável do que descrições em terceira pessoa. O posicionamento mais eficaz que a Anthropic testou é uma linha na mensagem do usuário:

(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)

Esta linha pode ser prefixada programaticamente pelo seu framework de agente antes de enviar a requisição. O limite é uma restrição suave. O advisor ocasionalmente o excede, então peça aproximadamente 80% do seu teto real.

Combine esta abordagem com a orientação de timing em Prompt do sistema sugerido para tarefas de codificação (ou o bloco alternativo para Haiku se você o substituiu) para a melhor relação custo-qualidade. Para um teto rígido em vez de uma solicitação suave, consulte Limitando a saída do advisor.



Limitando a saída do advisor

Defina max_tokens na definição da ferramenta para limitar a saída total do advisor (pensamento mais texto) por chamada:

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

O valor mínimo é 1024. Definir max_tokens acima do próprio limite de saída do modelo advisor retorna um erro 400. O limite se aplica a cada chamada ao advisor independentemente e não é compartilhado entre chamadas na mesma requisição.

Isso não é apenas um truncamento rígido. O servidor também passa ao advisor seu orçamento de tokens restante, então o advisor molda sua resposta para caber.

Ponto de partida recomendado: max_tokens: 2048. Nos testes da Anthropic em um benchmark de raciocínio difícil (n = 40 por configuração), isso reduziu a saída média do advisor em aproximadamente 7x em comparação com deixar o limite não definido, com truncamento próximo de zero e sem degradação de qualidade detectável. O valor mínimo de 1024 reduziu a saída em aproximadamente 10x, mas truncou cerca de 10% das chamadas. As diferenças de precisão em todas as configurações ficaram dentro do ruído neste tamanho de amostra. Valide na sua própria carga de trabalho.

Tarefas de raciocínio difícil provocam saída do advisor substancialmente mais longa do que os típicos 1.400 a 1.800 tokens citados anteriormente para cargas de trabalho mais leves. Use esta tabela para dimensionar a proporção de economia, não como um baseline universal para saída do advisor.

Quando o advisor atinge o limite, o bloco de resultado carrega stop_reason: "max_tokens". A API também anexa [Advisor output truncated at max_tokens=2048.] (nomeando seu limite) ao texto do conselho, para que o executor veja o truncamento em seu próprio contexto. Use stop_reason para detectar conselho truncado e decidir se deve aumentar o limite ou deixar o executor prosseguir com orientação parcial. Ambos os sinais aparecem apenas quando você define max_tokens na definição da ferramenta.

{
  "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"
  }
}

Verifique output_tokens na entrada advisor_message correspondente em usage.iterations para ver quão perto cada chamada chegou do seu limite.

Comparado com a abordagem baseada em prompt, max_tokens é um teto rígido em vez de uma solicitação suave. Use max_tokens quando precisar de um limite garantido para custo ou latência. Use a abordagem baseada em prompt (ou ambas juntas) quando quiser favorecer a brevidade sem arriscar um corte no meio do pensamento.



Combinando com configurações de esforço

Para tarefas de codificação, combinar um executor Sonnet com esforço médio e um advisor Opus alcança inteligência comparável ao Sonnet com esforço padrão, a um custo menor. Para inteligência máxima, mantenha o executor no esforço padrão.



Controle de custos

• Para orçamentos no nível da conversa, conte chamadas ao advisor no lado do cliente. Quando atingir seu limite, remova a ferramenta advisor de tools; você não precisa remover blocos advisor_tool_result do seu histórico de mensagens (consulte a nota em Conversas multi-turno).
• Habilite caching apenas para conversas em que você espera três ou mais chamadas ao advisor.



Compatibilidade de modelos

O modelo executor (o campo model de nível superior) e o modelo consultor (o campo model dentro da definição da ferramenta) devem formar um par válido. O consultor deve ser o Claude Sonnet 4.6 ou um modelo mais capaz, e deve ser pelo menos tão capaz quanto o executor. Modelos de capacidade equivalente (por exemplo, Claude Opus 4.7 e Claude Opus 4.8) podem aconselhar um ao outro.

Se você solicitar um par inválido, a API retorna um 400 invalid_request_error indicando a combinação não suportada.



Disponibilidade por plataforma

A ferramenta de consultor está disponível em beta na API do Claude e no Claude Platform on AWS. Atualmente, não está disponível no Amazon Bedrock, Google Cloud ou Microsoft Foundry.



Consultor em Claude Managed Agents

As sessões de Claude Managed Agents também oferecem suporte a um consultor, configurado como parte do agente em vez de como uma definição de ferramenta: adicione uma entrada {"type": "advisor", "model": ...} à lista de multiagentes do agente, e a thread principal da sessão poderá consultar esse modelo no meio do turno. A entrada da lista não aceita as opções max_uses, max_tokens ou caching, e o aconselhamento é entregue como eventos de thread no fluxo de eventos da sessão, em vez de blocos advisor_tool_result na resposta. Consulte Dar um consultor à sessão.



Próximos passos