---
title: Ferramenta advisor
url: https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool
description: Combine um modelo executor mais rápido com um modelo advisor de maior inteligência que fornece orientação estratégica no meio da geração.
---
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](https://platform.claude.com/docs/pt-BR/about-claude/models/optimizing-for-cost-and-intelligence).
```mermaid
sequenceDiagram
accTitle: How the executor model consults the advisor model
accDescr: Your application sends a request with the advisor tool to the executor model, which begins the task. The executor emits a server_tool_use block, and Anthropic runs the advisor model server-side. The advisor reads the full transcript and returns strategic guidance in an advisor_tool_result. The executor continues, informed by the advice, and returns the response to your application.
participant U as Your application
participant E as Executor model
participant A as Advisor model
U->>E: Request with advisor tool
note over E: Executor begins the task
E->>A: server_tool_use (server-side)
note over A: Reads the full transcript,
returns strategic guidance
A-->>E: advisor_tool_result
note over E: Executor continues,
informed by the advice
E-->>U: Response
```
Para saber como a "zero data retention" (retenção zero de dados), ou ZDR, se aplica a este recurso, consulte [API e retenção de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention).
## 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
A ferramenta advisor está em beta. Inclua o cabeçalho beta `advisor-tool-2026-03-01` nas suas requisições.
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: advisor-tool-2026-03-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5",
"max_tokens": 4096,
"tools": [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5"
}
],
"messages": [{
"role": "user",
"content": "Build a concurrent worker pool in Go with graceful shutdown."
}]
}'
```
```bash CLI
ant beta:messages create --beta advisor-tool-2026-03-01 <<'YAML'
model: claude-sonnet-5
max_tokens: 4096
tools:
- type: advisor_20260301
name: advisor
model: claude-opus-5
messages:
- role: user
content: Build a concurrent worker pool in Go with graceful shutdown.
YAML
```
```python Python
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)
```
```typescript TypeScript
const client = new Anthropic();
const response = await 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."
}
]
});
console.log(response);
```
```csharp C#
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
var client = new AnthropicClient();
var parameters = new MessageCreateParams
{
Model = Messages::Model.ClaudeSonnet5,
MaxTokens = 4096,
Tools = new BetaToolUnion[]
{
new BetaAdvisorTool20260301
{
Model = Messages::Model.ClaudeOpus5
}
},
Messages =
[
new BetaMessageParam
{
Role = Role.User,
Content = "Build a concurrent worker pool in Go with graceful shutdown."
}
],
Betas = ["advisor-tool-2026-03-01"]
};
var response = await client.Beta.Messages.Create(parameters);
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeSonnet5,
MaxTokens: 4096,
Tools: []anthropic.BetaToolUnionParam{
{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
Model: anthropic.ModelClaudeOpus5,
}},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Build a concurrent worker pool in Go with graceful shutdown.")),
},
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaAdvisorTool2026_03_01,
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_5)
.maxTokens(4096L)
.addTool(BetaAdvisorTool20260301.builder()
.model(Model.CLAUDE_OPUS_5)
.build())
.addUserMessage("Build a concurrent worker pool in Go with graceful shutdown.")
.addBeta("advisor-tool-2026-03-01")
.build();
BetaMessage response = client.beta().messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: [
[
'role' => 'user',
'content' => 'Build a concurrent worker pool in Go with graceful shutdown.',
],
],
model: 'claude-sonnet-5',
tools: [
[
'type' => 'advisor_20260301',
'name' => 'advisor',
'model' => 'claude-opus-5',
],
],
betas: ['advisor-tool-2026-03-01'],
);
echo $response;
```
```ruby Ruby
client = Anthropic::Client.new
response = client.beta.messages.create(
model: "claude-sonnet-5",
max_tokens: 4096,
tools: [
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-5"
}
],
messages: [
{
role: "user",
content: "Build a concurrent worker pool in Go with graceful shutdown."
}
],
betas: ["advisor-tool-2026-03-01"]
)
puts 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#result-variants) para ver os dois formatos lado a lado e quais modelos advisor retornam qual, e [Compatibilidade de modelos](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#model-compatibility) 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`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#resuming-a-paused-turn)).
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
| Parâmetro | Tipo | Padrão | Descrição |
| ------------ | -------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | *obrigatório* | Deve ser `"advisor_20260301"`. |
| `name` | string | *obrigatório* | Deve ser `"advisor"`. |
| `model` | string | *obrigatório* | O ID do modelo advisor, como claude-opus-5. Cobrado nas tarifas deste modelo para a subinferência. |
| `max_uses` | integer | ilimitado | Número máximo de chamadas ao advisor permitidas em uma única requisição. Quando o executor atinge esse limite, chamadas adicionais ao advisor retornam um `advisor_tool_result_error` com `error_code: "max_uses_exceeded"` e o executor continua sem mais conselhos. Este é um limite por requisição, não por conversa. Consulte [Controle de custos](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#cost-control) para limites no nível da conversa. |
| `max_tokens` | integer | limite de saída do modelo advisor | Limita a saída total do advisor (pensamento mais texto) por chamada. Mínimo 1024. Consulte [Limitando a saída do advisor](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#capping-advisor-output). |
| `caching` | object \| null | `null` (desativado) | Habilita o [cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching) para a própria transcrição do advisor entre chamadas dentro de uma conversa. Consulte [Cache de prompt do advisor](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#advisor-prompt-caching). |
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](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs)). Consulte a [Referência de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/tool-reference#tool-definition-properties) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#quick-start) usa Claude Opus 5, que retorna a variante criptografada `advisor_redacted_result`; consulte [Variantes de resultado](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#result-variants) para ver os dois formatos lado a lado.
```json
{
"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:
| Variante | Campos | Retornada quando |
| ------------------------- | ---------------------------------- | ---------------------------------------------------------------------- |
| `advisor_result` | `text`, `stop_reason` | O modelo advisor retorna texto simples (por exemplo, Claude Opus 4.8). |
| `advisor_redacted_result` | `encrypted_content`, `stop_reason` | O modelo advisor retorna saída criptografada. |
Os modelos advisor Claude Sonnet 5.5, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Fable 5, Claude Mythos 5 e Claude Haiku 5.5 retornam o `advisor_redacted_result` criptografado. Todos os outros modelos advisor na [tabela de compatibilidade](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#model-compatibility) retornam o `advisor_result` em texto simples. Para ler o texto do conselho em suas próprias respostas, use um advisor que retorne texto simples, como `claude-opus-4-8`, quando a linha do seu executor na [tabela de compatibilidade](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#model-compatibility) listar um. Os executores Claude Sonnet 5.5, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Fable 5 e Claude Mythos 5 só podem ser combinados com modelos advisor que retornam a forma criptografada, portanto, nesses executores, o texto do conselho não é legível na resposta.
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:
```json
{
"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:
```json
{
"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`](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#capping-advisor-output) 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`](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons) 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:
```json
{
"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.
| `error_code` | Significado |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `max_uses_exceeded` | A requisição atingiu o limite `max_uses` definido na definição da ferramenta. Chamadas adicionais ao advisor na mesma requisição retornam este erro. |
| `too_many_requests` | A subinferência do advisor sofreu limite de taxa. |
| `overloaded` | A subinferência do advisor atingiu limites de capacidade. |
| `prompt_too_long` | A transcrição excedeu a janela de contexto do modelo advisor. |
| `execution_time_exceeded` | A subinferência do advisor expirou por tempo. |
| `model_not_found` | O modelo advisor configurado não está disponível. |
| `unavailable` | Qualquer outra falha do advisor. |
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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#result-variants)). A mecânica é idêntica para qualquer modelo advisor.
```python Python
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,
)
```
```typescript TypeScript
const client = new Anthropic();
const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-5"
}
];
const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
{
role: "user",
content: "Build a concurrent worker pool in Go with graceful shutdown."
}
];
const response = await client.beta.messages.create({
model: "claude-sonnet-5",
max_tokens: 1024,
betas: ["advisor-tool-2026-03-01"],
tools,
messages
});
// Anexe o conteúdo completo da resposta, incluindo quaisquer blocos advisor_tool_result
messages.push({ role: "assistant", content: response.content });
// Continue a conversa
messages.push({ role: "user", content: "Now add a max-in-flight limit of 10." });
const followUp = await client.beta.messages.create({
model: "claude-sonnet-5",
max_tokens: 1024,
betas: ["advisor-tool-2026-03-01"],
tools,
messages
});
```
```csharp C#
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
var client = new AnthropicClient();
var tools = new BetaToolUnion[]
{
new BetaAdvisorTool20260301 { Model = Messages::Model.ClaudeOpus5 }
};
var messages = new List
{
new() { Role = Role.User, Content = "Build a concurrent worker pool in Go with graceful shutdown." }
};
var response = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Messages::Model.ClaudeSonnet5,
MaxTokens = 1024,
Tools = tools,
Messages = messages,
Betas = ["advisor-tool-2026-03-01"]
});
// Anexe o conteúdo completo da resposta, incluindo quaisquer blocos advisor_tool_result
messages.Add(new BetaMessageParam
{
Role = Role.Assistant,
Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList()
});
// Continue a conversa
messages.Add(new BetaMessageParam { Role = Role.User, Content = "Now add a max-in-flight limit of 10." });
var followUp = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Messages::Model.ClaudeSonnet5,
MaxTokens = 1024,
Tools = tools,
Messages = messages,
Betas = ["advisor-tool-2026-03-01"]
});
```
```go Go
client := anthropic.NewClient()
tools := []anthropic.BetaToolUnionParam{
{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
Model: anthropic.ModelClaudeOpus5,
}},
}
messages := []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Build a concurrent worker pool in Go with graceful shutdown.")),
}
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeSonnet5,
MaxTokens: 1024,
Tools: tools,
Messages: messages,
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaAdvisorTool2026_03_01,
},
})
if err != nil {
log.Fatal(err)
}
// Anexe o conteúdo completo da resposta, incluindo quaisquer blocos advisor_tool_result.
messages = append(messages, response.ToParam())
// Continue a conversa
messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Now add a max-in-flight limit of 10.")))
response, err = client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeSonnet5,
MaxTokens: 1024,
Tools: tools,
Messages: messages,
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaAdvisorTool2026_03_01,
},
})
if err != nil {
log.Fatal(err)
}
```
```java Java
import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;
import com.anthropic.models.beta.messages.BetaContentBlock;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaMessageParam;
import com.anthropic.models.beta.messages.BetaToolUnion;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
List tools = List.of(
BetaToolUnion.ofAdvisorTool20260301(
BetaAdvisorTool20260301.builder().model(Model.CLAUDE_OPUS_5).build()));
List messages = new ArrayList<>();
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.content("Build a concurrent worker pool in Go with graceful shutdown.")
.build());
BetaMessage response = client.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_5)
.maxTokens(1024L)
.tools(tools)
.messages(messages)
.addBeta("advisor-tool-2026-03-01")
.build());
// Anexe o conteúdo completo da resposta, incluindo quaisquer blocos advisor_tool_result
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.ASSISTANT)
.contentOfBetaContentBlockParams(
response.content().stream().map(BetaContentBlock::toParam).toList())
.build());
// Continue a conversa
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.content("Now add a max-in-flight limit of 10.")
.build());
BetaMessage followUp = client.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_5)
.maxTokens(1024L)
.tools(tools)
.messages(messages)
.addBeta("advisor-tool-2026-03-01")
.build());
}
```
```php PHP
$client = new Client();
$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(
maxTokens: 1024,
messages: $messages,
model: 'claude-sonnet-5',
tools: $tools,
betas: ['advisor-tool-2026-03-01'],
);
// Anexe o conteúdo completo da resposta, incluindo quaisquer blocos advisor_tool_result
$messages[] = ['role' => 'assistant', 'content' => $response->content];
// Continue a conversa
$messages[] = ['role' => 'user', 'content' => 'Now add a max-in-flight limit of 10.'];
$response = $client->beta->messages->create(
maxTokens: 1024,
messages: $messages,
model: 'claude-sonnet-5',
tools: $tools,
betas: ['advisor-tool-2026-03-01'],
);
```
```ruby Ruby
client = Anthropic::Client.new
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,
tools: tools,
messages: messages,
betas: ["advisor-tool-2026-03-01"]
)
# Anexe o conteúdo completo da resposta, incluindo quaisquer blocos advisor_tool_result
messages << { role: "assistant", content: response.content }
# Continue a conversa
messages << { role: "user", content: "Now add a max-in-flight limit of 10." }
response = client.beta.messages.create(
model: "claude-sonnet-5",
max_tokens: 1024,
tools: tools,
messages: messages,
betas: ["advisor-tool-2026-03-01"]
)
```
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.
A ferramenta advisor não tem um limite embutido no nível da conversa. Para limitar as chamadas ao advisor ao longo de uma conversa, conte-as no lado do cliente. Quando você atingir seu teto, remova a ferramenta advisor do seu array `tools`. Você não precisa remover os blocos `advisor_tool_result` do seu histórico de mensagens.
### 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools#mixing-server-tools-and-client-tools-in-one-turn).
### 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.
```python Python
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})
```
```typescript TypeScript
const client = new Anthropic();
const NUDGE_TURN = 2; // inject before this assistant turn if no advisor call yet
const 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.";
const MAX_TURNS = 10; // agent loop cap
function runYourTools(
content: Anthropic.Beta.Messages.BetaContentBlock[]
): Anthropic.Beta.Messages.BetaToolResultBlockParam[] {
// Substitua pelo seu despacho de ferramentas. Retorna um bloco tool_result por bloco tool_use.
return content
.filter((block) => block.type === "tool_use")
.map((block) => ({
type: "tool_result" as const,
tool_use_id: block.id,
content: "Replace with your tool output."
}));
}
const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [
{ type: "advisor_20260301", name: "advisor", model: "claude-opus-5" }
// ... suas outras ferramentas
];
const task = "Build a concurrent worker pool in Go with graceful shutdown.";
const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [{ role: "user", content: task }];
let advisorCalled = false;
for (let turn = 1; turn <= MAX_TURNS; turn++) {
const response = await client.beta.messages.create({
model: "claude-haiku-5-5",
max_tokens: 4096,
betas: ["advisor-tool-2026-03-01"],
tools,
messages
});
messages.push({ role: "assistant", content: response.content });
advisorCalled =
advisorCalled ||
response.content.some(
(block) => block.type === "server_tool_use" && block.name === "advisor"
);
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)
}
const results = runYourTools(response.content); // list of tool_result blocks
if (results.length > 0) {
messages.push({ 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 && !advisorCalled) {
messages.push({ role: "user", content: NUDGE_TEXT });
}
}
```
```csharp C#
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
var client = new AnthropicClient();
const int NudgeTurn = 2; // inject before this assistant turn if no advisor call yet
const string NudgeText =
"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.";
const int MaxTurns = 10; // agent loop cap
// Substitua pelo seu despacho de ferramentas. Retorna um bloco tool_result para cada bloco tool_use.
List RunYourTools(IReadOnlyList content)
{
List results = [];
foreach (var block in content)
{
if (block.TryPickToolUse(out var toolUse))
{
results.Add(new BetaToolResultBlockParam
{
ToolUseID = toolUse.ID,
Content = "Replace with your tool output."
});
}
}
return results;
}
var tools = new BetaToolUnion[]
{
new BetaAdvisorTool20260301 { Model = Messages::Model.ClaudeOpus5 }
// ... suas outras ferramentas
};
var task = "Build a concurrent worker pool in Go with graceful shutdown.";
var messages = new List { new() { Role = Role.User, Content = task } };
var advisorCalled = false;
for (var turn = 1; turn <= MaxTurns; turn++)
{
var response = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Messages::Model.ClaudeHaiku5_5,
MaxTokens = 4096,
Tools = tools,
Messages = messages,
Betas = ["advisor-tool-2026-03-01"]
});
messages.Add(new BetaMessageParam
{
Role = Role.Assistant,
Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList()
});
advisorCalled =
advisorCalled
|| response.Content.Any(block =>
block.TryPickServerToolUse(out var serverToolUse)
&& serverToolUse.Name.Value() == Name.Advisor
);
if (response.StopReason == BetaStopReason.PauseTurn)
{
continue; // server tool pending; re-send to let the API complete it
}
if (response.StopReason != BetaStopReason.ToolUse)
{
break; // end_turn, or a stop such as max_tokens that needs handling (see below)
}
var results = RunYourTools(response.Content); // list of tool_result blocks
if (results.Count > 0)
{
messages.Add(new BetaMessageParam { Role = Role.User, Content = results });
}
// Pule isto se o seu prompt do sistema já instrui o modelo a fazer chamadas com moderação.
if (turn == NudgeTurn - 1 && !advisorCalled)
{
messages.Add(new BetaMessageParam { Role = Role.User, Content = NudgeText });
}
}
```
```go Go
const (
nudgeTurn = 2 // inject before this assistant turn if no advisor call yet
nudgeText = "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."
maxTurns = 10 // agent loop cap
)
// Substitua pelo seu despacho de ferramentas. Retorna um bloco tool_result por bloco tool_use.
func runYourTools(content []anthropic.BetaContentBlockUnion) []anthropic.BetaContentBlockParamUnion {
var results []anthropic.BetaContentBlockParamUnion
for _, block := range content {
if block.Type == "tool_use" {
results = append(results, anthropic.NewBetaToolResultBlock(block.ID, "Replace with your tool output.", false))
}
}
return results
}
func main() {
client := anthropic.NewClient()
tools := []anthropic.BetaToolUnionParam{
{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
Model: anthropic.ModelClaudeOpus5,
}},
// ... suas outras ferramentas
}
task := "Build a concurrent worker pool in Go with graceful shutdown."
messages := []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(task)),
}
advisorCalled := false
for turn := 1; turn <= maxTurns; turn++ {
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeHaiku5_5,
MaxTokens: 4096,
Tools: tools,
Messages: messages,
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaAdvisorTool2026_03_01,
},
})
if err != nil {
log.Fatal(err)
}
messages = append(messages, response.ToParam())
for _, block := range response.Content {
if block.Type == "server_tool_use" && block.Name == "advisor" {
advisorCalled = true
}
}
if response.StopReason == anthropic.BetaStopReasonPauseTurn {
continue // server tool pending; re-send to let the API complete it
}
if response.StopReason != anthropic.BetaStopReasonToolUse {
break // end_turn, or a stop such as max_tokens that needs handling (see below)
}
results := runYourTools(response.Content) // list of tool_result blocks
if len(results) > 0 {
messages = append(messages, anthropic.BetaMessageParam{
Role: anthropic.BetaMessageParamRoleUser,
Content: results,
})
}
// Pule isto se o seu prompt do sistema já instrui o modelo a fazer chamadas com moderação.
if turn == nudgeTurn-1 && !advisorCalled {
messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(nudgeText)))
}
}
}
```
```java Java
import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;
import com.anthropic.models.beta.messages.BetaContentBlock;
import com.anthropic.models.beta.messages.BetaContentBlockParam;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaMessageParam;
import com.anthropic.models.beta.messages.BetaServerToolUseBlock;
import com.anthropic.models.beta.messages.BetaStopReason;
import com.anthropic.models.beta.messages.BetaToolResultBlockParam;
import com.anthropic.models.beta.messages.BetaToolUnion;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
static final int NUDGE_TURN = 2; // inject before this assistant turn if no advisor call yet
static final String 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.";
static final int MAX_TURNS = 10; // agent loop cap
// Substitua pelo seu despacho de ferramentas. Retorna um bloco tool_result por bloco tool_use.
List runYourTools(List content) {
List results = new ArrayList<>();
for (BetaContentBlock block : content) {
if (block.isToolUse()) {
results.add(BetaContentBlockParam.ofToolResult(
BetaToolResultBlockParam.builder()
.toolUseId(block.asToolUse().id())
.content("Replace with your tool output.")
.build()));
}
}
return results;
}
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
List tools = List.of(
BetaToolUnion.ofAdvisorTool20260301(
BetaAdvisorTool20260301.builder().model(Model.CLAUDE_OPUS_5).build())
// ... suas outras ferramentas
);
String task = "Build a concurrent worker pool in Go with graceful shutdown.";
List messages = new ArrayList<>();
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.content(task)
.build());
boolean advisorCalled = false;
for (int turn = 1; turn <= MAX_TURNS; turn++) {
BetaMessage response = client.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_HAIKU_5_5)
.maxTokens(4096L)
.tools(tools)
.messages(messages)
.addBeta("advisor-tool-2026-03-01")
.build());
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.ASSISTANT)
.contentOfBetaContentBlockParams(
response.content().stream().map(BetaContentBlock::toParam).toList())
.build());
advisorCalled = advisorCalled
|| response.content().stream().anyMatch(block ->
block.isServerToolUse()
&& block.asServerToolUse().name().equals(BetaServerToolUseBlock.Name.ADVISOR));
BetaStopReason stopReason = response.stopReason().orElse(null);
if (BetaStopReason.PAUSE_TURN.equals(stopReason)) {
continue; // server tool pending; re-send to let the API complete it
}
if (!BetaStopReason.TOOL_USE.equals(stopReason)) {
break; // end_turn, or a stop such as max_tokens that needs handling (see below)
}
List results = runYourTools(response.content()); // list of tool_result blocks
if (!results.isEmpty()) {
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.contentOfBetaContentBlockParams(results)
.build());
}
// Pule isto se o seu prompt do sistema já instrui o modelo a fazer chamadas com moderação.
if (turn == NUDGE_TURN - 1 && !advisorCalled) {
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.content(NUDGE_TEXT)
.build());
}
}
}
```
```php PHP
$client = new Client();
const NUDGE_TURN = 2; // inject before this assistant turn if no advisor call yet
const 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.";
const MAX_TURNS = 10; // agent loop cap
// Substitua pelo seu despacho de ferramentas. Retorna um bloco tool_result por bloco tool_use.
function runYourTools(array $content): array
{
$results = [];
foreach ($content as $block) {
if ($block->type === 'tool_use') {
$results[] = [
'type' => 'tool_result',
'tool_use_id' => $block->id,
'content' => 'Replace with your tool output.',
];
}
}
return $results;
}
$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]];
$advisorCalled = false;
for ($turn = 1; $turn <= MAX_TURNS; $turn++) {
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-haiku-5-5',
tools: $tools,
betas: ['advisor-tool-2026-03-01'],
);
$messages[] = ['role' => 'assistant', 'content' => $response->content];
foreach ($response->content as $block) {
if ($block->type === 'server_tool_use' && $block->name === 'advisor') {
$advisorCalled = true;
}
}
if ($response->stopReason === 'pause_turn') {
continue; // server tool pending; re-send to let the API complete it
}
if ($response->stopReason !== 'tool_use') {
break; // end_turn, or a stop such as max_tokens that needs handling (see below)
}
$results = runYourTools($response->content); // list of tool_result blocks
if ($results !== []) {
$messages[] = ['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 && !$advisorCalled) {
$messages[] = ['role' => 'user', 'content' => NUDGE_TEXT];
}
}
```
```ruby Ruby
client = Anthropic::Client.new
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
# Substitua pelo seu despacho de ferramentas. Retorna um bloco tool_result por bloco tool_use.
def run_your_tools(content)
content.filter_map do |block|
next unless block.type == :tool_use
{ type: "tool_result", tool_use_id: block.id, content: "Replace with your tool output." }
end
end
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
(1..MAX_TURNS).each do |turn|
response = client.beta.messages.create(
model: "claude-haiku-5-5",
max_tokens: 4096,
tools: tools,
messages: messages,
betas: ["advisor-tool-2026-03-01"]
)
messages << { role: "assistant", content: response.content }
advisor_called ||= response.content.any? do |block|
block.type == :server_tool_use && block.name == :advisor
end
next if response.stop_reason == :pause_turn # server tool pending; re-send to let the API complete it
break unless response.stop_reason == :tool_use # 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
messages << { role: "user", content: results } unless results.empty?
# Pule isto se o seu prompt do sistema já instrui o modelo a fazer chamadas com moderação.
messages << { role: "user", content: NUDGE_TEXT } if turn == NUDGE_TURN - 1 && !advisor_called
end
```
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](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#max-tokens). Quando esse turno não contém nenhum bloco `tool_use`, você pode, em vez disso, mantê-lo e [continuar a resposta](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons#ensuring-complete-responses) com uma nova mensagem do usuário. Reenviar o turno de assistente truncado como a última mensagem é um [prefill](https://platform.claude.com/docs/pt-BR/api/errors#prefill-not-supported), 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/define-tools#forcing-tool-use). 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[]`:
```json
{
"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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#capping-advisor-output). Os tokens do advisor também não consomem de nenhum [orçamento de tarefa](https://platform.claude.com/docs/pt-BR/build-with-claude/task-budgets) aplicado ao executor.
O [Priority Tier](https://platform.claude.com/docs/pt-BR/api/service-tiers) 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:
```python Python
tools = [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5",
"caching": {"type": "ephemeral", "ttl": "5m"},
}
]
```
```typescript TypeScript
const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-5",
caching: { type: "ephemeral", ttl: "5m" }
}
];
```
```csharp C#
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
var tools = new BetaToolUnion[]
{
new BetaAdvisorTool20260301
{
Model = Messages::Model.ClaudeOpus5,
Caching = new BetaCacheControlEphemeral { Ttl = Ttl.Ttl5m }
}
};
```
```go Go
tools := []anthropic.BetaToolUnionParam{
{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
Model: anthropic.ModelClaudeOpus5,
Caching: anthropic.BetaCacheControlEphemeralParam{TTL: anthropic.BetaCacheControlEphemeralTTLTTL5m},
}},
}
```
```java Java
import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;
import com.anthropic.models.beta.messages.BetaCacheControlEphemeral;
import com.anthropic.models.beta.messages.BetaToolUnion;
import com.anthropic.models.messages.Model;
List tools = List.of(
BetaToolUnion.ofAdvisorTool20260301(BetaAdvisorTool20260301.builder()
.model(Model.CLAUDE_OPUS_5)
.caching(BetaCacheControlEphemeral.builder()
.ttl(BetaCacheControlEphemeral.Ttl.TTL_5M)
.build())
.build()));
```
```php PHP
$tools = [
[
'type' => 'advisor_20260301',
'name' => 'advisor',
'model' => 'claude-opus-5',
'caching' => ['type' => 'ephemeral', 'ttl' => '5m'],
],
];
```
```ruby Ruby
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.
[`clear_thinking`](https://platform.claude.com/docs/pt-BR/build-with-claude/context-editing) com um valor de `keep` diferente de `"all"` desloca a transcrição citada do advisor a cada turno, causando falhas de cache no lado do advisor. Isso é apenas uma degradação de custo. A qualidade do conselho não é afetada. Quando o pensamento está ativado sem uma configuração explícita de explícita de `clear_thinking`, a API usa por padrão `keep: {type: "thinking_turns", value: 1}`, o que aciona esse comportamento (o padrão em modelos Opus e Sonnet anteriores e em modelos Haiku até o Claude Haiku 4.5; no Claude Opus 4.5 e modelos Opus posteriores, no Claude Sonnet 4.6 e modelos Sonnet posteriores, e no Claude Haiku 5.5, o padrão é manter todos os turnos). Defina `keep: "all"` para preservar a estabilidade do cache do advisor.
## 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`:
```python Python
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"}},
},
},
]
```
```typescript TypeScript
const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [
{
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" } }
}
}
];
```
```csharp C#
using System.Text.Json;
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
var tools = new BetaToolUnion[]
{
new BetaWebSearchTool20250305 { MaxUses = 5 },
new BetaAdvisorTool20260301 { Model = Messages::Model.ClaudeOpus5 },
new BetaTool
{
Name = "run_bash",
Description = "Run a bash command",
InputSchema = new()
{
Properties = new Dictionary
{
["command"] = JsonSerializer.SerializeToElement(new { type = "string" })
}
}
}
};
```
```go Go
tools := []anthropic.BetaToolUnionParam{
{OfWebSearchTool20250305: &anthropic.BetaWebSearchTool20250305Param{
MaxUses: anthropic.Int(5),
}},
{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
Model: anthropic.ModelClaudeOpus5,
}},
{OfTool: &anthropic.BetaToolParam{
Name: "run_bash",
Description: anthropic.String("Run a bash command"),
InputSchema: anthropic.BetaToolInputSchemaParam{
Properties: map[string]any{
"command": map[string]any{"type": "string"},
},
},
}},
}
```
```java Java
import com.anthropic.core.JsonValue;
import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;
import com.anthropic.models.beta.messages.BetaTool;
import com.anthropic.models.beta.messages.BetaToolUnion;
import com.anthropic.models.beta.messages.BetaWebSearchTool20250305;
import com.anthropic.models.messages.Model;
List tools = List.of(
BetaToolUnion.ofWebSearchTool20250305(BetaWebSearchTool20250305.builder()
.maxUses(5L)
.build()),
BetaToolUnion.ofAdvisorTool20260301(BetaAdvisorTool20260301.builder()
.model(Model.CLAUDE_OPUS_5)
.build()),
BetaToolUnion.ofBetaTool(BetaTool.builder()
.name("run_bash")
.description("Run a bash command")
.inputSchema(BetaTool.InputSchema.builder()
.properties(JsonValue.from(Map.of(
"command", Map.of("type", "string"))))
.build())
.build()));
```
```php PHP
$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']],
],
],
];
```
```ruby Ruby
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.
| Recurso | Interação |
| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Processamento em lote](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing) | Suportado. `usage.iterations` é relatado por item. |
| [Contagem de tokens](https://platform.claude.com/docs/pt-BR/build-with-claude/token-counting) | Retorna apenas os tokens de entrada da primeira iteração do executor. Para uma estimativa aproximada do advisor, chame `client.beta.messages.count_tokens()` (typescript: `client.beta.messages.countTokens()`; go, csharp: `client.Beta.Messages.CountTokens()`; java: `client.beta().messages().countTokens()`; php: `$client->beta->messages->countTokens()`; cli: `ant beta:messages count-tokens`; curl: `POST /v1/messages/count_tokens`) com `model` definido como o modelo advisor e as mesmas mensagens. |
| [Edição de contexto](https://platform.claude.com/docs/pt-BR/build-with-claude/context-editing) | `clear_tool_uses` não é totalmente compatível com os blocos da ferramenta advisor. Com `clear_thinking`, consulte o aviso sobre cache anterior. |
| `pause_turn` | Uma chamada pendente ao advisor encerra a resposta com `stop_reason: "pause_turn"` e um bloco `server_tool_use` sem resultado quando nenhum bloco `tool_use` do cliente está aguardando seu resultado no mesmo turno. O advisor é executado na retomada. Se o executor também tiver chamado uma de suas ferramentas nesse turno, a resposta termina com `stop_reason: "tool_use"`, e a chamada pendente ao advisor é executada no início da sua próxima requisição, depois que você enviar os blocos `tool_result`. Consulte [Retomando um turno pausado](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#resuming-a-paused-turn), [Misturando ferramentas de servidor e ferramentas de cliente em um turno](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools#mixing-server-tools-and-client-tools-in-one-turn) e [Ferramentas de servidor](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn). |
## 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#suggested-system-prompt-for-coding-tasks) 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:
```text wrap
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):
```text wrap
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:
```text wrap
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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#suggested-system-prompt-for-coding-tasks), 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:
```text wrap
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:
```text wrap
(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.
Nos testes da Anthropic, essa linha também aumentou a frequência com que o executor consulta o advisor, mas o efeito líquido ainda foi um custo total menor (mais consultas, cada uma mais curta).
Combine essa abordagem com a orientação de momento em [Prompt do sistema sugerido para tarefas de codificação](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#suggested-system-prompt-for-coding-tasks) (ou o [bloco alternativo para Haiku](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#alternative-system-prompt-for-haiku-on-coding-workloads), 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#capping-advisor-output).
### 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:
```python Python
tools = [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5",
"max_tokens": 2048,
}
]
```
```typescript TypeScript
const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-5",
max_tokens: 2048
}
];
```
```csharp C#
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
var tools = new BetaToolUnion[]
{
new BetaAdvisorTool20260301
{
Model = Messages::Model.ClaudeOpus5,
MaxTokens = 2048
}
};
```
```go Go
tools := []anthropic.BetaToolUnionParam{
{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: anthropic.Int(2048),
}},
}
```
```java Java
import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;
import com.anthropic.models.beta.messages.BetaToolUnion;
import com.anthropic.models.messages.Model;
List tools = List.of(
BetaToolUnion.ofAdvisorTool20260301(BetaAdvisorTool20260301.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(2048L)
.build()));
```
```php PHP
$tools = [
[
'type' => 'advisor_20260301',
'name' => 'advisor',
'model' => 'claude-opus-5',
'max_tokens' => 2048,
],
];
```
```ruby Ruby
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.
| `max_tokens` | Média de tokens de saída do advisor | Chamadas truncadas |
| ------------ | ----------------------------------- | ------------------ |
| indefinido | \~4.200 a 5.900 | n/a |
| 2048 | \~630 a 840 | \~0% |
| 1024 | \~370 a 480 | \~10% |
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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#usage-and-billing) 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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#result-variants), 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.
```json
{
"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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#trimming-advisor-output-length), `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](https://platform.claude.com/docs/pt-BR/build-with-claude/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](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/advisor-tool#multi-turn-conversations)).
* 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.
| Modelos executores | Modelos advisor |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Haiku 4.5 (claude-haiku-4-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 5.5 (claude-sonnet-5-5)
Claude Sonnet 5 (claude-sonnet-5)
Claude Sonnet 4.6 (claude-sonnet-4-6)
Claude Haiku 5.5 (claude-haiku-5-5) |
| Claude Haiku 5.5 (claude-haiku-5-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Sonnet 5.5 (claude-sonnet-5-5)
Claude Sonnet 5 (claude-sonnet-5)
Claude Haiku 5.5 (claude-haiku-5-5) |
| Claude Sonnet 4.6 (claude-sonnet-4-6) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 5.5 (claude-sonnet-5-5)
Claude Sonnet 5 (claude-sonnet-5)
Claude Sonnet 4.6 (claude-sonnet-4-6)
Claude Haiku 5.5 (claude-haiku-5-5) |
| Claude Sonnet 5 (claude-sonnet-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Sonnet 5.5 (claude-sonnet-5-5)
Claude Sonnet 5 (claude-sonnet-5)
Claude Haiku 5.5 (claude-haiku-5-5) |
| Claude Sonnet 5.5 (claude-sonnet-5-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Sonnet 5.5 (claude-sonnet-5-5) |
| Claude Opus 4.6 (claude-opus-4-6) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 5.5 (claude-sonnet-5-5)
Claude Sonnet 5 (claude-sonnet-5)
Claude Haiku 5.5 (claude-haiku-5-5) |
| Claude Opus 4.7 (claude-opus-4-7) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Sonnet 5.5 (claude-sonnet-5-5) |
| Claude Opus 4.8 (claude-opus-4-8) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Sonnet 5.5 (claude-sonnet-5-5) |
| Claude Opus 5 (claude-opus-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5) |
| Claude Opus 5.5 (claude-opus-5-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5) |
| Claude Fable 5 (claude-fable-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5) |
| Claude Mythos 5 (claude-mythos-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5) |
| Claude Fable 5.1 (claude-fable-5-1) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1) |
| Claude Mythos 5.1 (claude-mythos-5-1) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1) |
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](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-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](https://platform.claude.com/docs/pt-BR/managed-agents/overview) 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](https://platform.claude.com/docs/pt-BR/managed-agents/multiagent-orchestration#give-the-session-an-advisor).
## Próximos passos
Armazene e recupere informações entre conversas com um diretório de memória no lado do cliente.
Trabalhe com ferramentas executadas pela Anthropic: blocos server\_tool\_use, continuação com pause\_turn e filtragem de domínios.
Diretório de ferramentas fornecidas pela Anthropic e referência para propriedades opcionais de definição de ferramentas.
Controle quantos tokens o Claude usa ao responder com o parâmetro effort, equilibrando entre a profundidade da resposta e a eficiência de tokens.