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 encaixa em cargas de trabalho agênticas de longo horizonte (agentes de codificação, uso de computador, pipelines de pesquisa de múltiplas etapas) onde 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 usá-la

O advisor se encaixa nestas configurações:

• Você atualmente usa Sonnet em tarefas complexas: Adicione Opus como advisor para um ganho de qualidade a um custo total semelhante ou menor.
• Você atualmente usa Haiku e quer um salto em inteligência: Adicione Opus como advisor. 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 em sua própria carga de trabalho.

O advisor é uma opção mais fraca para perguntas e respostas de turno único (nada para planejar), seletores de modelo de simples repasse onde seus usuários já escolhem seu próprio equilíbrio entre custo e qualidade, ou cargas de trabalho onde cada turno genuinamente requer a capacidade total do modelo advisor.



Compatibilidade de modelos

O modelo executor (o campo model de nível superior) e o modelo advisor (o campo model dentro da definição da ferramenta) devem formar um par válido. O advisor deve ser Claude Sonnet 4.6 ou um modelo mais capaz, e deve ser pelo menos tão capaz quanto o executor. Modelos de capacidade igual (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 nomeando a combinação não suportada.



Disponibilidade por plataforma

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



Início rápido

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    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.",
        }
    ],
)

print(response)



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 invoca 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 do 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 acontece dentro de uma única requisição /v1/messages, sem viagens de ida e volta 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 sua semântica.



Estrutura da resposta



Chamada bem-sucedida ao advisor

Quando o advisor é invocado, um bloco server_tool_use é seguido por um bloco advisor_tool_result no conteúdo do assistente:

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

Os advisors 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 Messages API.

Com advisor_result, o campo text contém conselhos legíveis 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 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 falha a requisição inteira com HTTP 429.



Conversas de múltiplos turnos

Passe o conteúdo completo do assistente, incluindo os blocos advisor_tool_result, de volta para a API nos turnos subsequentes:

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-4-6",
    max_tokens=4096,
    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-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

Se você omitir a ferramenta advisor de tools em um turno de acompanhamento enquanto o histórico de mensagens ainda contém blocos advisor_tool_result, a API retorna um 400 invalid_request_error.



Retomando um turno pausado

Uma resposta pode terminar com stop_reason: "pause_turn" enquanto uma chamada ao advisor ainda está pendente. Quando isso acontece, a resposta contém o bloco server_tool_use do advisor sem um advisor_tool_result para ele. 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. Se, em vez disso, o executor chamou uma de 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 Misturando 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 lembrete curto como uma mensagem de usuário adicional antes do segundo turno de assistente. Na avaliação comportamental interna da Anthropic, isso elevou 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 sobre o momento da chamada que seguem 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 tipicamente 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-4-8"},
    # ... 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(
        b.type == "server_tool_use" and b.name == "advisor" for b 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 o seu prompt do sistema já instruir 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 das 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 da ferramenta.

Compensações: 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 por cento (Sonnet) a 98 por cento (Haiku) das tentativas com lembrete nos testes da Anthropic chamaram o advisor imediatamente no turno 2. Se isso acontecer antes que seu executor tenha lido o problema ou reunido contexto, a chamada ao advisor resultante tem pouco contexto e pode deslocar uma chamada posterior com melhor momento. Meça o turno da primeira chamada de referência do seu executor antes de adicionar o lembrete. Se o executor já chama o advisor de forma confiável e sua primeira chamada tipicamente 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 de referência 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 chamadas de referência era de 86 por cento, o mesmo lembrete aumentou o engajamento sem custo no 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: a API retorna um 400 invalid_request_error se você habilitar ambos.



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 pelos keepalives ping padrão de SSE 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

As chamadas ao advisor são executadas como uma sub-inferência separada cobrada às taxas do modelo advisor. O uso é relatado no array 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-8",
        "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 os tokens do executor. Os tokens do advisor não são incorporados aos 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.

As regras de agregação diferem por campo. O output_tokens de nível superior é a soma de todas as iterações do executor. Os input_tokens e cache_read_input_tokens de nível superior refletem apenas a primeira iteração do executor. As entradas das iterações subsequentes do executor não são somadas novamente porque incluem tokens de saída anteriores. Use usage.iterations para uma divisão completa 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 o 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 os tokens da 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. As chamadas ao advisor são executadas em 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 é armazenável em cache como qualquer outro bloco de conteúdo. Um ponto de interrupção cache_control colocado após ele em um turno subsequente é atingido. 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 o 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-4-8",
        "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 se tornar diferente de zero na segunda iteração advisor_message e nas posteriores.

Quando habilitá-lo: A gravação do 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 a consistência: Defina caching uma vez e deixe-o para toda a conversa. Alterná-lo entre desligado e ligado no meio da conversa causa falhas de cache.



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-4-8",
    },
    {
        "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 de agente

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

Em tarefas de codificação e de agente, 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 semelhantes a planejadores (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 necessário em alguns domínios, particularmente tarefas de codificação. Para tarefas de codificação onde você quer um momento consistente para o advisor e cerca de duas a três chamadas para cada tarefa, adicione os seguintes blocos ao início do seu prompt do sistema do executor, antes de quaisquer outras frases que mencionem o advisor.

Orientação de momento:

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 momento):

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 abre mão de qualidade em cargas de trabalho de codificação, onde uma consulta antecipada ao advisor se paga de forma confiável. Em um benchmark interno de codificação, uma variante próxima do bloco a seguir (a exceção para somente leitura na regra Hard foi adicionada após a medição) elevou as taxas de aprovação do Haiku em aproximadamente 7,5 pontos percentuais em relação ao padrão embutido.

Use este bloco no lugar dos blocos anteriores de momento e conselho quando seu executor Haiku executa predominantemente cargas de trabalho de codificação ou de 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 embutido. Se sua carga de trabalho mistura codificação com consulta ou recuperação substancial, permaneça com 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 necessário em sua carga de trabalho, adicione o seguinte ponto de verificação 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 para somente leitura na regra Hard foi adicionada após a medição) elevou as taxas de aprovação em tarefas com poucas chamadas em aproximadamente 7 a 10 pontos percentuais, mas fez com que o Opus chamasse 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 diretamente ao advisor 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 por cento do seu teto real.

Combine essa abordagem com a orientação de momento em Prompt do sistema sugerido para tarefas de codificação (ou o bloco alternativo para Haiku se você o substituiu) para o melhor equilíbrio entre custo e 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 indefinido, com truncamento próximo de zero e nenhuma degradação de qualidade detectável. O valor mínimo de 1024 reduziu a saída em aproximadamente 10x, mas truncou cerca de 10 por cento das chamadas. As diferenças de precisão entre todas as configurações estavam dentro do ruído neste tamanho de amostra. Valide em sua própria carga de trabalho.

Tarefas de raciocínio difíceis provocam uma 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 uma referência universal para a 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 conselhos truncados 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 o quão perto cada chamada chegou do seu limite.

Em comparação com a abordagem baseada em prompt, max_tokens é um teto rígido em vez de uma solicitação suave. Use max_tokens quando você precisa de um limite garantido para custo ou latência. Use a abordagem baseada em prompt (ou ambas juntas) quando você quer tender à brevidade sem arriscar um corte no meio do raciocínio.



Combinando com configurações de esforço

Para tarefas de codificação, combinar um executor Sonnet com esforço médio com 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 em nível de conversa, conte as chamadas ao advisor do lado do cliente. Quando você atingir seu limite, remova a ferramenta advisor de tools e remova todos os blocos advisor_tool_result do seu histórico de mensagens para evitar um 400 invalid_request_error (consulte a nota em Conversas de múltiplos turnos).
• Habilite caching apenas para conversas onde você espera três ou mais chamadas ao advisor.



Próximos passos