Ferramenta advisor

A "advisor tool" (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 uma correção de rumo, e o executor continua com a tarefa.

Esse padrão se adapta a cargas de trabalho agênticas de longo horizonte (agentes de codificação, uso de computador, pipelines de pesquisa em várias etapas), nas quais a maioria dos turnos é mecânica, mas ter um plano excelente é crucial. Você obtém uma qualidade próxima à do advisor sozinho, enquanto a maior parte da geração de tokens acontece às tarifas do modelo executor. Para resultados medidos, incluindo como o benefício diminui à medida que a capacidade do próprio executor se aproxima da do advisor, consulte Otimizando para custo e inteligência.

Quando usar

O advisor se encaixa nestas configurações:

• Você atualmente usa Sonnet em tarefas complexas: Adicione um advisor de nível superior. O Opus mantém o custo total semelhante ou menor; o Claude Fable 5.1 maximiza o ganho de qualidade.
• Você atualmente usa Haiku e quer um salto em inteligência: Adicione um advisor Opus ou Fable. Espere um custo maior do que o 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 de repasse em que seus usuários já escolhem seu próprio equilíbrio entre custo e qualidade, ou cargas de trabalho em que cada turno genuinamente exige 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 como advisor, como neste início rápido, 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 ver os dois formatos lado a lado e quais modelos advisor retornam qual, 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 roda 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é o momento 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 viagens de ida e volta extras do seu lado. A exceção é um turno que pausa no meio de uma chamada, que você retoma com uma requisição de acompanhamento (consulte Retomando um turno pausado).

O próprio advisor roda sem ferramentas e sem gerenciamento de contexto. Seus blocos de pensamento são descartados antes de o resultado retornar. 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, isto 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 (abordada em saídas estruturadas). Consulte a Referência de ferramentas para a semântica delas.

Estrutura da resposta

Chamada bem-sucedida ao advisor

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 para ver os dois formatos lado a lado.

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

Aqui está a mesma requisição enviada duas vezes, idêntica exceto pelo model do advisor na definição da ferramenta, mostrando as duas variantes.

Com "model": "claude-opus-4-8", o conselho está em texto simples:

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

Com "model": "claude-opus-5", o conselho está criptografado:

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_redacted_result",
    "encrypted_content": "EqQBCkYIBRgCIiQ5ZjE0N2M2OC0yYWIxLTRkZTktYjA3ZC1hZTUyMzkxYjhkMmU..."
  }
}

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 o define. Ele contém o motivo de parada da subchamada do advisor, normalmente "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 um conselho legível por humanos. Com advisor_redacted_result, o campo encrypted_content contém um blob opaco que você não consegue ler. No próximo turno, o servidor o descriptografa e renderiza o texto simples no prompt do executor.

Em ambos os casos, reenvie 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 os dois 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 as 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 de múltiplos turnos

Passe o conteúdo completo do assistente, incluindo os blocos advisor_tool_result, de volta à API nos turnos subsequentes. Reenvie os blocos de resultado sem alterações: com um advisor Claude Opus 5, o content do bloco de resultado é a variante criptografada advisor_redacted_result, e o servidor a descriptografa e renderiza o conselho no prompt do executor no próximo turno (consulte Variantes de resultado). A mecânica é idêntica para qualquer modelo advisor.

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

# 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 naquele turno. Você ainda deve enviar o cabeçalho beta advisor-tool-2026-03-01 para que esses blocos do 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 o mesmo cabeçalho beta. Você não precisa adicionar uma mensagem de usuário nem 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 contra a qual executar; inclua a ferramenta sempre que houver uma chamada 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 Misturando ferramentas de servidor e ferramentas de cliente em um turno.

Lembrete no meio da conversa para executores que chamam pouco o advisor

Se um executor Haiku não chamou o advisor em seu primeiro turno de assistente, anexe um breve lembrete como uma mensagem adicional do usuário antes do segundo turno de assistente. Na avaliação comportamental interna da Anthropic com executores Claude Haiku 4.5, isso aumentou as taxas de aprovação de tarefas em aproximadamente 7 pontos percentuais. Em executores Sonnet, o lembrete em texto simples não teve efeito mensurável nos testes da Anthropic. As considerações sobre o momento das chamadas a seguir são especialmente relevantes para o 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 sobre a 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-5-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 == "pause_turn":
        continue  # server tool pending; re-send to let the API complete it
    if response.stop_reason != "tool_use":
        break  # end_turn, or a stop such as max_tokens that needs handling (see below)

    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á instrui o modelo a fazer chamadas com moderação.
    if turn == NUDGE_TURN - 1 and not advisor_called:
        messages.append({"role": "user", "content": NUDGE_TEXT})

O loop termina com qualquer motivo de parada diferente de tool_use ou pause_turn. Se max_tokens cortar uma resposta, remova o turno de assistente truncado de messages e tente novamente com um max_tokens maior. Quando esse turno não contém nenhum bloco tool_use, você pode, em vez disso, mantê-lo e continuar a resposta com uma nova mensagem do usuário. Reenviar o turno de assistente truncado como a última mensagem é um prefill, que o Claude 4.6 e modelos posteriores rejeitam.

Anexe o lembrete como sua própria mensagem do usuário após os resultados das ferramentas, em vez de como um bloco irmão na mesma mensagem. Mensagens consecutivas do usuário são válidas. Nos testes da Anthropic com executores Claude Haiku 4.5 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 das ferramentas.

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 da tarefa que você já calcula. Se seu prompt do sistema já contém linguagem de contenção ("reserve o advisor para incertezas genuínas"), pule o lembrete completamente, porque as duas instruções entram em conflito.

O lembrete em texto simples é altamente saliente em executores Claude Haiku 4.5 e Sonnet: de 74 por cento (Sonnet) a 98 por cento (Claude Haiku 4.5) 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 resultante ao advisor terá pouco contexto e pode substituir 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 normalmente ocorre no turno N, defina NUDGE_TURN maior que N. Nos testes da Anthropic, um lembrete no turno 2 em cargas de trabalho em que a primeira chamada de referência ocorria no turno 7 ou depois correlacionou-se com uma queda de 3 a 4 pontos percentuais no desempenho da tarefa. Em uma carga de trabalho de navegação em que a taxa de chamadas de referência era de 86 por cento, o mesmo lembrete aumentou o engajamento sem custo para o 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 o "extended thinking" (pensamento estendido) manual (thinking: {type: "enabled"}): a API retorna um 400 invalid_request_error se você habilitar ambos. O pensamento adaptativo oferece suporte ao uso forçado de ferramentas. Os executores Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 e Claude Mythos 5.1 rejeitam os tipos tool e any de tool_choice, portanto, use o lembrete no prompt nesses modelos.

Streaming

A subinferência do advisor não faz streaming. O stream do executor pausa enquanto o advisor roda; 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 SSE padrão emitidos aproximadamente a cada 30 segundos. Chamadas curtas ao advisor podem não mostrar nenhum ping.

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 rodam como uma subinferência separada cobrada nas tarifas 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 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 tarifa diferente. Iterações com type: "advisor_message" são cobradas nas tarifas do modelo advisor, e iterações com type: "message" são cobradas nas tarifas 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 das iterações posteriores incluem a saída das iterações anteriores, portanto o input_tokens somado 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 é normalmente de 400 a 700 tokens de texto, ou de 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 em sua tarifa mais baixa.

O max_tokens de nível superior aplica-se apenas à saída do executor. Ele não limita os tokens da subinferê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 aplica-se a cada modelo independentemente. Um compromisso de Priority Tier no modelo executor não se estende ao advisor. As chamadas ao advisor rodam 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 no lado do executor

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

Cache no 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-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, de modo que o prefixo é estável entre as 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 pela diferença. Você verá cache_read_input_tokens se tornar diferente de zero na segunda iteração advisor_message e nas posteriores.

Quando habilitar: A gravação no 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 assim durante toda a conversa. Desativá-lo e reativá-lo no meio da conversa causa falhas de cache.

Combinando com outras ferramentas

A ferramenta advisor pode ser combinada com outras ferramentas do lado do servidor e do lado do cliente. Adicione todas elas 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 orientar quais ferramentas o executor usará em seguida.

Melhores práticas

Prompts 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, normalmente não é necessário nenhum prompt 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 antecipada ao advisor, 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 pouco o advisor em alguns domínios, particularmente em tarefas de codificação. Para tarefas de codificação em que você deseja um momento consistente de chamadas ao advisor e cerca de duas a três chamadas por tarefa, insira os blocos a seguir no início do prompt do sistema do seu 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, em que 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 de somente leitura na regra Hard foi adicionada após a medição) elevou as taxas de aprovação do Haiku em cerca de 7,5 pontos percentuais em relação ao padrão embutido.

Use este bloco no lugar dos blocos anteriores de momento e de conselho quando seu executor Haiku roda 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 cerca de 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 substanciais, fique com os blocos sugeridos, ou condicione a troca a um sinal de tipo de carga de trabalho que você já calcula.

Aumentando as chamadas ao advisor em executores Opus

Executores Opus normalmente chamam o advisor em uma taxa apropriada sem prompts adicionais. Se seu executor Opus está chamando pouco na 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 de somente leitura na regra Hard foi adicionada após a medição) elevou as taxas de aprovação em tarefas com poucas chamadas em cerca de 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 em que 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, portanto 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.)

Essa linha pode ser prefixada programaticamente pelo seu framework de agente antes de enviar a requisição. O limite é uma restrição flexível. O advisor ocasionalmente o excede, portanto peça cerca de 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 adotou) para o melhor equilíbrio entre custo e qualidade. Para um teto rígido em vez de um pedido flexível, 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-5",
        "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 aplica-se 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, para que o advisor molde 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 cerca de 7x em comparação com deixar o limite indefinido, com truncamento quase zero e nenhuma degradação de qualidade detectável. O valor mínimo de 1024 reduziu a saída em cerca de 10x, mas truncou cerca de 10 por cento das chamadas. As diferenças de precisão entre 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 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" em ambas as variantes de resultado, qualquer que seja o modelo advisor que você use. Use stop_reason para detectar conselho truncado e decidir se aumenta o limite ou deixa o executor prosseguir com orientação parcial. 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; com um advisor advisor_result em texto simples, esse marcador também é visível para seu cliente. 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_redacted_result",
    "encrypted_content": "EqQBCkYIBRgCIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
    "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.

Em comparação com a abordagem baseada em prompt, max_tokens é um teto rígido em vez de um pedido flexível. 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 tender à brevidade sem arriscar um corte no meio do raciocínio.

Combinação com configurações de esforço

Para tarefas de codificação, combinar um executor Sonnet com effort (esforço) médio com um "advisor" (consultor) 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 com esforço padrão.

Controle de custos

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

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 o 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 indicando a combinação não suportada.

Disponibilidade por plataforma

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

Consultor no Claude Managed Agents

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

Próximos passos