Ferramenta de consultor

A ferramenta de consultor permite que um modelo executor mais rápido e de menor custo consulte um modelo consultor de maior inteligência durante a geração para obter orientação estratégica. O consultor lê a conversa completa, produz um plano ou correção de curso (normalmente 400 a 700 tokens de texto, 1.400 a 1.800 tokens no total incluindo pensamento), e o executor continua com a tarefa.

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

Quando usá-la

Os primeiros benchmarks mostram ganhos significativos para estas configurações:

• Você atualmente usa Sonnet em tarefas complexas: Adicione Opus como consultor para um aumento de qualidade com custo similar ou menor no total.
• Você atualmente usa Haiku e quer um aumento de inteligência: Adicione Opus como consultor. Espere custo maior que Haiku sozinho, mas menor que mudar o executor para um modelo maior.

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

O consultor é um ajuste mais fraco para Q&A de turno único (nada para planejar), seletores de modelo de passagem pura onde seus usuários já escolhem seu próprio custo e tradeoff de qualidade, ou cargas de trabalho onde cada turno genuinamente requer a capacidade completa do modelo consultor.

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 pelo menos tão capaz quanto o executor.

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

Disponibilidade de plataforma

A ferramenta de consultor está disponível em beta na Claude API (Anthropic).

Início rápido

Como funciona

Quando você adiciona a ferramenta de consultor ao seu array tools, o modelo executor decide quando chamá-la, assim como qualquer outra ferramenta. Quando o executor invoca o consultor:

1. O executor emite um bloco server_tool_use com name: "advisor" e um input vazio. O executor sinaliza o tempo; o servidor fornece o contexto.
2. A Anthropic executa uma passagem de inferência separada no servidor do modelo consultor, passando a transcrição completa do executor. O consultor vê o prompt do sistema, todas as definições de ferramentas, todas as voltas anteriores e todos os resultados de ferramentas anteriores.
3. A resposta do consultor retorna ao executor como um bloco advisor_tool_result.
4. O executor continua gerando, informado pelo conselho.

Tudo isso acontece dentro de uma única solicitação /v1/messages. Sem viagens extras do seu lado.

O próprio consultor é executado sem ferramentas e sem gerenciamento de contexto. Seus blocos de pensamento são descartados antes do resultado retornar; apenas o texto de conselho chega ao executor.

Parâmetros da ferramenta

O objeto caching tem a forma {"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 decide onde os limites do cache vão.

Estrutura de resposta

Chamada de consultor bem-sucedida

Quando o consultor é 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 é sempre vazio. O servidor constrói a visão do consultor a partir da transcrição completa automaticamente; nada que o executor coloca em input chega ao consultor.

Variantes de resultado

O campo advisor_tool_result.content é uma união discriminada. Qual variante você recebe depende do modelo consultor:

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; na próxima volta, o servidor descriptografa e renderiza o texto simples no prompt do executor.

Em ambos os casos, faça round-trip do conteúdo verbatim nas voltas subsequentes. Se você mudar modelos de consultor no meio da conversa, ramifique em content.type para lidar com ambas as formas.

Resultados de erro

Se a chamada do consultor 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 solicitação em si não falha.

Os limites de taxa do consultor são extraídos do mesmo bucket por modelo que as chamadas diretas ao modelo consultor. Um limite de taxa no consultor aparece como too_many_requests dentro do resultado da ferramenta; um limite de taxa no executor falha a solicitação inteira com HTTP 429.

Conversas multi-turno

Passe o conteúdo completo do assistente, incluindo blocos advisor_tool_result, de volta à API nas voltas subsequentes:

import anthropic

client = anthropic.Anthropic()

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

messages = [
    {
        "role": "user",
        "content": "Build a concurrent worker pool in Go with graceful shutdown.",
    }
]

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

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

# Continue the conversation
messages.append({"role": "user", "content": "Now add a max-in-flight limit of 10."})

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

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

Streaming

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

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

Quando o consultor 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 consultor.

Uso e faturamento

As chamadas do consultor são executadas como uma sub-inferência separada cobrada nas taxas do modelo consultor. 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-7",
        "input_tokens": 823,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0,
        "output_tokens": 1612
      },
      {
        "type": "message",
        "input_tokens": 1348,
        "cache_read_input_tokens": 412,
        "cache_creation_input_tokens": 0,
        "output_tokens": 442
      }
    ]
  }
}

Os campos usage de nível superior refletem apenas tokens do executor. Os tokens do consultor não são incorporados aos totais de nível superior porque são cobrados em uma taxa diferente. Iterações com type: "advisor_message" são cobradas nas taxas do modelo consultor; iterações com type: "message" são cobradas nas 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. O input_tokens de nível superior e cache_read_input_tokens refletem apenas a primeira iteração do executor; as entradas das iterações subsequentes do executor não são re-somadas porque incluem tokens de saída anteriores. Use usage.iterations para um detalhamento completo por iteração ao construir lógica de rastreamento de custo.

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

O max_tokens de nível superior se aplica apenas à saída do executor. Ele não limita os tokens de sub-inferência do consultor. Os tokens do consultor também não são extraídos de nenhum orçamento de tarefa aplicado ao executor.

Cache de prompt do consultor

Existem duas camadas de cache independentes.

Cache no 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 uma volta subsequente será 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 no lado do consultor

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

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

O prompt do consultor na Nª chamada é o prompt da (N-1)ª chamada com um segmento a mais anexado, então o prefixo é estável entre chamadas. Com caching ativado, cada chamada do consultor escreve uma entrada de cache; 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 e posteriores iterações advisor_message.

Quando ativá-lo: O custo de escrita do cache é maior que as leituras economizam quando o consultor é chamado duas ou menos vezes por conversa. O cache se equilibra em aproximadamente três chamadas de consultor e melhora a partir daí. Ative-o para loops de agente longos; mantenha-o desativado para tarefas curtas.

Mantenha consistência: Defina caching uma vez e deixe para toda a conversa. Alternância desativada e ativada no meio da conversa causa falhas de cache.

Combinando com outras ferramentas

A ferramenta de consultor se compõe com outras ferramentas do lado do servidor e do lado do cliente. Adicione-as 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-7",
    },
    {
        "name": "run_bash",
        "description": "Run a bash command",
        "input_schema": {
            "type": "object",
            "properties": {"command": {"type": "string"}},
        },
    },
]

O executor pode pesquisar a web, chamar o consultor e usar suas ferramentas personalizadas na mesma volta. O plano do consultor pode informar quais ferramentas o executor alcança a seguir.

Melhores práticas

Prompting para tarefas de codificação e agente

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

Em tarefas de codificação e agente, o consultor produz inteligência mais alta com custo similar quando reduz chamadas de ferramentas totais e comprimento da conversa. Dois tempos impulsionam essa melhoria:

1. Uma primeira chamada de consultor inicial, após algumas leituras exploratórias estarem na transcrição.
2. Para tarefas difíceis, uma chamada de consultor final após escritas de arquivo e saídas de teste estarem na transcrição.

Se seu agente expõe outras ferramentas semelhantes a planejador (por exemplo, uma ferramenta de lista de tarefas), solicite ao modelo que chame o consultor antes dessas ferramentas para que o plano do consultor seja canalizado para elas. O prompt do sistema sugerido abaixo reforça o padrão de chamada inicial; adicione sua própria sentença de canalização apontando para quaisquer ferramentas de planejador que seu agente exponha.

Prompt do sistema sugerido para tarefas de codificação

Para tarefas de codificação onde você quer tempo de consultor consistente e cerca de duas a três chamadas por tarefa, coloque os seguintes blocos antes de seu prompt do sistema executor antes de qualquer outra sentença que mencione o consultor. Em avaliações internas de codificação, este padrão produziu a inteligência mais alta com custo próximo ao Sonnet.

Orientação de tempo:

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

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.

Aparando o comprimento da saída do consultor

A saída do consultor é o maior impulsionador de custo do consultor. Para reduzir esse custo, coloque uma única instrução de concisão antes de qualquer outra sentença que mencione o consultor. Em testes internos, a seguinte linha cortou tokens de saída total do consultor em aproximadamente 35 a 45 por cento sem mudar a frequência de chamadas:

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

Combine isto com o bloco de tempo acima para o melhor tradeoff de custo versus qualidade.

Emparelhamento com configurações de esforço

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

Controle de custo

• Para orçamentos em nível de conversa, conte chamadas de consultor no lado do cliente. Quando você atingir seu limite, remova a ferramenta de consultor de tools e remova todos os blocos advisor_tool_result do seu histórico de mensagens para evitar um 400 invalid_request_error.
• Ative caching apenas para conversas onde você espera três ou mais chamadas de consultor.

Limitações

• A saída do consultor não faz streaming. Espere uma pausa no stream enquanto a sub-inferência é executada.
• Nenhum limite de conversa integrado em chamadas de consultor. Rastreie e limite-as no lado do cliente.
• max_tokens se aplica apenas à saída do executor. Ele não limita tokens do consultor.
• Anthropic Priority Tier é honrado por modelo. Priority Tier no modelo executor não se estende ao consultor; você precisa de Priority Tier no modelo consultor especificamente.