Ferramenta Claude Advisor: combine um executor rápido com um planejador mais inteligente

Você tem um agente de codificação executando o Sonnet. Ele lida com 90% das voltas sem suar a camisa: lendo arquivos, executando testes, escrevendo clichês. Mas quando se trata de uma decisão de arquitetura complicada ou de uma simultaneidade sutil bug, você gostaria que pudesse telefonar para um amigo.

Essa é a ferramenta Advisor. O novo recurso beta da API da Anthropic permite um modelo de executor mais rápido (Sonnet ou Haiku) chame de modelo de conselheiro de inteligência superior (Opus) de meia geração. O orientador lê a transcrição completa, produz um breve plano ou correção de curso, e o executor continua com a tarefa. Uma solicitação de API, dois modelos, qualidade quase Opus a preços Sonnet.

Como funciona a ferramenta Advisor

Quando você adiciona a ferramenta Advisor ao seu tools array, o executor decide quando chamá-lo, como qualquer outra ferramenta. O fluxo:

1. O executor emite um server_tool_use bloquear com name: "advisor" e um vazio input.
2. A Anthropic executa uma passagem de inferência separada no lado do servidor do modelo orientador, passando a transcrição completa do executor (prompt do sistema, definições de ferramentas, todos os turnos e resultados anteriores).
3. A resposta do orientador retorna como um advisor_tool_result bloco (normalmente 400 a 700 tokens de texto).
4. O executor continua gerando, informado pela assessoria.

Tudo isso acontece dentro de um único /v1/messages solicitar. Não há viagens extras de ida e volta do seu lado. O orientador funciona sem ferramentas e sem gerenciamento de contexto; seus bloqueios de pensamento são eliminados e apenas o texto do conselho chega ao executor.

Sua primeira chamada de consultor: curl, Python e TypeScript

A ferramenta do consultor está em versão beta. Incluir o advisor-tool-2026-03-01 cabeçalho beta em suas solicitações. Aqui está a chamada mais simples possível:

enrolar

curl https://api.anthropic.com/v1/messages \\
  --header "x-api-key: \$ANTHROPIC_API_KEY" \\
  --header "anthropic-version: 2023-06-01" \\
  --header "anthropic-beta: advisor-tool-2026-03-01" \\
  --header "content-type: application/json" \\
  --data '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 4096,
    "tools": [
      {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-6"
      }
    ],
    "messages": [{
      "role": "user",
      "content": "Build a concurrent worker pool in Go with graceful shutdown."
    }]
  }'

Pitão

import anthropic

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-6",
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Build a concurrent worker pool in Go with graceful shutdown.",
        }
    ],
)

print(response)

Texto datilografado

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await 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-6",
    },
  ],
  messages: [
    {
      role: "user",
      content: "Build a concurrent worker pool in Go with graceful shutdown.",
    },
  ],
});

console.log(response);

Como é a resposta

Uma chamada de conselheiro bem-sucedida produz quatro blocos de conteúdo: o texto inicial do executor, o server_tool_use bloco, o advisor_tool_result bloco, e o executor resultado final informado pela assessoria.

{
  "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. Close the input channel first, then wait on a WaitGroup..."
      }
    },
    {
      "type": "text",
      "text": "Here's the implementation using a channel-based coordination pattern..."
    }
  ]
}

O advisor_tool_result o conteúdo tem duas variantes: advisor_result com texto simples conselhos, e advisor_redacted_result com conteúdo criptografado. Em ambos os casos, faça uma viagem de ida e volta conteúdo literalmente nos turnos subsequentes.

Pares de modelos válidos

O conselheiro deve ser pelo menos tão capaz quanto o executor. Pares inválidos retornam um 400 erro.

O ponto ideal para a maioria das cargas de trabalho: Sonnet como executor, Opus como consultor. Você obtém um elevador de qualidade em custo total semelhante ou inferior em comparação com a execução do Opus para cada token.

Conversas multivoltas

Passe o conteúdo completo do assistente, incluindo advisor_tool_result blocos, de volta à API em turnos subsequentes. Se você omitir a ferramenta Advisor do tools em um turno de acompanhamento enquanto o o histórico de mensagens ainda contém advisor_tool_result blocos, a API retorna um 400.

import anthropic

client = anthropic.Anthropic()

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

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

# First turn: executor calls advisor, builds the worker pool
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

# Pass back the full response content (including advisor_tool_result blocks)
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": "Now add a max-in-flight limit of 10."})

# Second turn: executor has context from first advisor call
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

Engenharia imediata para agentes de codificação

A ferramenta orientadora vem com uma descrição integrada que estimula o executor a chamá-la perto do início de tarefas complexas. Para cargas de trabalho de codificação e de agente, você pode melhorar os resultados com um prompt do sistema que reforça dois timings:

• Uma primeira ligação antecipada do consultor, depois de algumas leituras exploratórias estarem na transcrição
• Uma chamada final do orientador após a gravação do arquivo e as saídas de teste estarem na transcrição

Aqui está o padrão de prompt do sistema que a Anthropic recomenda para tarefas de codificação. Produziu o maior inteligência a um custo próximo do Sonnet em avaliações internas:

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.

Call advisor BEFORE substantive work: before writing, before committing
to an interpretation, before building on an assumption.

Also call advisor:
- When you believe the task is complete (save your deliverable first)
- When stuck: errors recurring, approach not converging
- When considering a change of approach

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

Combinando com outras ferramentas

A ferramenta consultor compõe pesquisa na web, execução de código e suas ferramentas personalizadas no mesmo tools variedade. O executor pode pesquisar na web, ligar para o consultor e usar suas ferramentas em o mesmo turno. O plano do consultor pode informar quais ferramentas o executor utilizará em seguida.

tools = [
    {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 5,
    },
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-6",
    },
    {
        "name": "run_bash",
        "description": "Run a bash command",
        "input_schema": {
            "type": "object",
            "properties": {"command": {"type": "string"}},
        },
    },
]

Cache de prompt do Advisor

Duas camadas de cache independentes estão disponíveis. O cache do lado do executor funciona da mesma forma que qualquer bloco de conteúdo: coloque um cache_control ponto de interrupção após um advisor_tool_result e bate.

O cache do lado do orientador mantém a transcrição do orientador armazenada em cache nas chamadas da mesma conversa. Habilite-o com um caching campo na definição da ferramenta:

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

A gravação do cache custa mais do que as leituras salvas quando o orientador é chamado duas ou menos vezes. O cache atinge o equilíbrio em aproximadamente três chamadas de consultor e melhora a partir daí. Habilite-o por muito tempo loops de agente; mantenha-o desligado para tarefas curtas.

Análise de uso e faturamento

As chamadas do consultor são executadas como uma subinferência separada cobrada de acordo com as taxas do modelo do consultor. O usage.iterations array fornece um detalhamento por iteração:

{
  "usage": {
    "input_tokens": 412,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "output_tokens": 531,
    "iterations": [
      {
        "type": "message",
        "input_tokens": 412,
        "output_tokens": 89
      },
      {
        "type": "advisor_message",
        "model": "claude-opus-4-6",
        "input_tokens": 823,
        "output_tokens": 1612
      },
      {
        "type": "message",
        "input_tokens": 1348,
        "cache_read_input_tokens": 412,
        "output_tokens": 442
      }
    ]
  }
}

Nível superior usage os campos refletem apenas tokens de executor. Iterações com type: "advisor_message" são cobrados de acordo com as taxas do modelo de consultor. Use o iterations array ao construir lógica de rastreamento de custos.

Controle de custos: limitando chamadas de consultores

A ferramenta do consultor não possui limite de nível de conversa integrado. Usar max_uses na ferramenta definição de limites por solicitação. Para limites no nível de conversação, conte as chamadas do lado do cliente e tire o conselheiro quando você atingir o teto:

# Track advisor calls client-side
advisor_count = 0
MAX_ADVISOR_CALLS = 5

for turn in conversation:
    response = client.beta.messages.create(...)

    # Count advisor calls in response
    for block in response.content:
        if block.type == "server_tool_use" and block.name == "advisor":
            advisor_count += 1

    if advisor_count >= MAX_ADVISOR_CALLS:
        # Remove advisor tool and strip advisor_tool_result blocks
        tools = [t for t in tools if t.get("name") != "advisor"]
        for msg in messages:
            if msg["role"] == "assistant":
                msg["content"] = [
                    b for b in msg["content"]
                    if b.get("type") not in ("server_tool_use", "advisor_tool_result")
                    or b.get("name") != "advisor"
                ]

Tratamento de erros

Se a chamada do orientador falhar, o resultado carrega um advisor_tool_result_error com um error_code. O executor vê o erro e continua sem aviso; o pedido em si não falha.

Comportamento de streaming

A subinferência do orientador não é transmitida. O fluxo do executor é pausado enquanto o orientador é executado, então o completo advisor_tool_result chega em um único content_block_start evento. Keepalives de ping SSE são acionados a cada 30 segundos durante a pausa. Planeje 2 a 5 segundos de silêncio por chamada do consultor, dependendo da duração da transcrição.

Quando o consultor ajuda (e quando não ajuda)

Limitações para saber

• A saída do Advisor não é transmitida. Espere uma pausa durante a subinferência.
• Nenhum limite de nível de conversa integrado nas chamadas do consultor. Rastreie e limite-os do lado do cliente.
• max_tokens aplica-se apenas à saída do executor. Não vincula tokens de conselheiro.
• O nível de prioridade do executor não se estende ao orientador; você precisa disso em ambos os modelos.
• O recurso está em beta. Incluir anthropic-beta: advisor-tool-2026-03-01 em cada solicitação.