---
title: Herramienta de asesor
url: https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool
description: Combina un modelo ejecutor más rápido con un modelo asesor de mayor inteligencia que proporciona orientación estratégica a mitad de la generación.
---
La herramienta de asesor permite que un **executor model** (modelo ejecutor) más rápido y de menor costo consulte a un **advisor model** (modelo asesor) de mayor inteligencia durante la generación para obtener orientación estratégica. El asesor lee la conversación completa, produce un plan o una corrección de rumbo, y el ejecutor continúa con la tarea.
Este patrón se adapta a cargas de trabajo agénticas de largo horizonte (agentes de programación, uso de computadora, pipelines de investigación de varios pasos) donde la mayoría de los turnos son mecánicos, pero tener un plan excelente es crucial. Obtienes una calidad cercana a la del asesor por sí solo, mientras que la mayor parte de la generación de tokens ocurre a las tarifas del modelo ejecutor. Para ver resultados medidos, incluido cómo el beneficio se reduce a medida que la capacidad propia del ejecutor se acerca a la del asesor, consulta [Optimización de costo e inteligencia](https://platform.claude.com/docs/es/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 cómo se aplica la "zero data retention" (retención cero de datos), o ZDR, a esta función, consulta [API y retención de datos](https://platform.claude.com/docs/es/manage-claude/api-and-data-retention).
## Cuándo usarla
El asesor se adapta a estas configuraciones:
* **Actualmente usas Sonnet en tareas complejas:** Agrega un asesor de nivel superior. Opus mantiene el costo total similar o menor; Claude Fable 5.1 maximiza la mejora de calidad.
* **Actualmente usas Haiku y quieres un salto en inteligencia:** Agrega un asesor Opus o Fable. Espera un costo mayor que con Haiku solo, pero menor que si cambias el ejecutor a un modelo más grande.
Los resultados dependen de la tarea. Evalúa con tu propia carga de trabajo.
El asesor encaja peor en tres casos: preguntas y respuestas de un solo turno (no hay nada que planificar), selectores de modelo de paso directo donde tus usuarios ya eligen su propio equilibrio entre costo y calidad, y cargas de trabajo donde cada turno realmente requiere la capacidad completa del modelo asesor.
## Inicio rápido
La herramienta de asesor está en beta. Incluye el encabezado beta `advisor-tool-2026-03-01` en tus solicitudes.
```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
```
El `content` de la respuesta incluye un bloque `advisor_tool_result` que contiene la orientación del asesor. Con `claude-opus-5` como asesor, como en este inicio rápido, el campo `content` del bloque es una variante `advisor_redacted_result` (cifrada; el ejecutor la lee del lado del servidor, pero tu cliente no). Para ver el texto del consejo directamente en tu respuesta, usa `claude-opus-4-8` como modelo asesor, que devuelve la variante en texto plano `advisor_result`. Consulta [Variantes de resultado](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#result-variants) para ver ambas formas lado a lado y qué modelos asesores devuelven cada una. Consulta [Compatibilidad de modelos](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#model-compatibility) para ver la lista completa de pares válidos.
## Cómo funciona
Cuando agregas la herramienta de asesor a tu arreglo `tools`, el modelo ejecutor determina cuándo llamarla, como con cualquier otra herramienta. Cuando el ejecutor llama al asesor:
1. El ejecutor emite un bloque [`server_tool_use`](https://platform.claude.com/docs/es/agents-and-tools/tool-use/server-tools) con `name: "advisor"` y un `input` vacío. El ejecutor indica el momento y el servidor proporciona el contexto.
2. Anthropic ejecuta una pasada de inferencia separada en el modelo asesor del lado del servidor. El asesor se ejecuta con su propio "system prompt" (indicación del sistema) proporcionado por Anthropic y recibe la transcripción completa del ejecutor como contexto citado en su entrada. Esa transcripción incluye tu indicación del sistema, las definiciones de herramientas, los turnos anteriores y los resultados de herramientas, y el texto que el ejecutor ha producido hasta ahora en este turno.
3. La respuesta del asesor regresa al ejecutor como un bloque `advisor_tool_result`.
4. El ejecutor continúa generando, guiado por el consejo.
Todo esto ocurre dentro de una sola solicitud `/v1/messages`, sin viajes de ida y vuelta adicionales de tu lado. La excepción es un turno que se pausa a mitad de una llamada, que reanudas con una solicitud de seguimiento (consulta [Reanudar un turno pausado](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#resuming-a-paused-turn)).
El asesor en sí se ejecuta sin herramientas y sin gestión de contexto. Sus bloques de pensamiento se descartan antes de que se devuelva el resultado. Solo el texto del consejo llega al ejecutor.
## Parámetros de la herramienta
| Parámetro | Tipo | Predeterminado | Descripción |
| ------------ | -------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | *obligatorio* | Debe ser `"advisor_20260301"`. |
| `name` | string | *obligatorio* | Debe ser `"advisor"`. |
| `model` | string | *obligatorio* | El ID del modelo asesor, como claude-opus-5. La subinferencia se factura a las tarifas de este modelo. |
| `max_uses` | integer | ilimitado | Número máximo de llamadas al asesor permitidas en una sola solicitud. Una vez que el ejecutor alcanza este límite, las llamadas adicionales al asesor devuelven un `advisor_tool_result_error` con `error_code: "max_uses_exceeded"` y el ejecutor continúa sin más consejos. Este límite es por solicitud, no por conversación. Consulta [Control de costos](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#cost-control) para ver los límites a nivel de conversación. |
| `max_tokens` | integer | límite de salida del modelo asesor | Limita la salida total del asesor (pensamiento más texto) por llamada. Mínimo 1024. Consulta [Limitar la salida del asesor](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#capping-advisor-output). |
| `caching` | object \| null | `null` (desactivado) | Habilita el "[prompt caching](https://platform.claude.com/docs/es/build-with-claude/prompt-caching)" (almacenamiento en caché de prompts) para la transcripción propia del asesor entre llamadas dentro de una conversación. Consulta [Almacenamiento en caché de prompts del asesor](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#advisor-prompt-caching). |
El objeto `caching` tiene la forma `{"type": "ephemeral", "ttl": "5m" | "1h"}`. A diferencia de `cache_control` en los bloques de contenido, no es un marcador de punto de interrupción, sino un interruptor de encendido y apagado. El servidor determina dónde van los límites de la caché.
La herramienta de asesor también acepta las propiedades genéricas disponibles en cualquier definición de herramienta: `cache_control`, `allowed_callers`, `defer_loading` y `strict` (tratada en [salidas estructuradas](https://platform.claude.com/docs/es/build-with-claude/structured-outputs)). Consulta la [Referencia de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-reference#tool-definition-properties) para conocer su semántica.
## Estructura de la respuesta
### Llamada exitosa al asesor
Cuando se llama al asesor, un bloque `server_tool_use` va seguido de un bloque `advisor_tool_result` en el contenido del asistente. El siguiente ejemplo muestra la variante en texto plano `advisor_result` que devuelve un asesor Claude Opus 4.8. El [Inicio rápido](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#quick-start) usa Claude Opus 5, que en su lugar devuelve la variante cifrada `advisor_redacted_result`; consulta [Variantes de resultado](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#result-variants) para ver ambas formas 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..."
}
]
}
```
El `server_tool_use.input` siempre está vacío. El servidor construye automáticamente la vista del asesor a partir de la transcripción completa. Nada de lo que el ejecutor ponga en `input` llega al asesor.
### Variantes de resultado
El campo `advisor_tool_result.content` es una unión discriminada. Para las llamadas exitosas, la variante depende del modelo asesor:
| Variante | Campos | Se devuelve cuando |
| ------------------------- | ---------------------------------- | --------------------------------------------------------------------- |
| `advisor_result` | `text`, `stop_reason` | El modelo asesor devuelve texto plano (por ejemplo, Claude Opus 4.8). |
| `advisor_redacted_result` | `encrypted_content`, `stop_reason` | El modelo asesor devuelve una salida cifrada. |
Los asesores 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 y Claude Haiku 5.5 devuelven el `advisor_redacted_result` cifrado. Todos los demás modelos asesores de la [tabla de compatibilidad](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#model-compatibility) devuelven el `advisor_result` en texto plano. Para leer el texto del consejo en tus propias respuestas, usa un asesor que devuelva texto plano, como `claude-opus-4-8`, cuando la fila de tu ejecutor en la [tabla de compatibilidad](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#model-compatibility) incluya uno. Los ejecutores Claude Sonnet 5.5, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Fable 5 y Claude Mythos 5 solo se combinan con asesores que devuelven la forma cifrada, por lo que en esos ejecutores el texto del consejo no se puede leer en la respuesta.
A continuación se muestra la misma solicitud enviada dos veces, idéntica salvo por el `model` del asesor en la definición de la herramienta, con ambas variantes.
Con `"model": "claude-opus-4-8"`, el consejo está en texto plano:
```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..."
}
}
```
Con `"model": "claude-opus-5"`, el consejo está cifrado:
```json
{
"type": "advisor_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "advisor_redacted_result",
"encrypted_content": "EqQBCkYIBRgCIiQ5ZjE0N2M2OC0yYWIxLTRkZTktYjA3ZC1hZTUyMzkxYjhkMmU..."
}
}
```
Ambas variantes de resultado incluyen un campo `stop_reason` cuando estableces [`max_tokens`](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#capping-advisor-output) en la definición de la herramienta, y lo omiten cuando no lo haces. Contiene el motivo de detención de la subllamada del asesor, normalmente `"end_turn"`, o `"max_tokens"` cuando se alcanza el límite. Los valores coinciden con el [`stop_reason`](https://platform.claude.com/docs/es/build-with-claude/handling-stop-reasons) de nivel superior de la Messages API.
Con `advisor_result`, el campo `text` contiene un consejo legible por humanos. Con `advisor_redacted_result`, el campo `encrypted_content` contiene un blob opaco que no puedes leer. En el siguiente turno, el servidor lo descifra y renderiza el texto plano en el prompt del ejecutor.
En ambos casos, devuelve el contenido textualmente en los turnos posteriores. Si cambias de modelo asesor a mitad de la conversación, ramifica según `content.type` para manejar ambas formas.
### Resultados de error
Si la llamada al asesor falla, el resultado contiene un error:
```json
{
"type": "advisor_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "advisor_tool_result_error",
"error_code": "overloaded"
}
}
```
El ejecutor ve el error y continúa sin más consejos. La solicitud en sí no falla.
| `error_code` | Significado |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `max_uses_exceeded` | La solicitud alcanzó el límite `max_uses` establecido en la definición de la herramienta. Las llamadas adicionales al asesor en la misma solicitud devuelven este error. |
| `too_many_requests` | La subinferencia del asesor alcanzó un "rate limit" (límite de velocidad). |
| `overloaded` | La subinferencia del asesor alcanzó los límites de capacidad. |
| `prompt_too_long` | La transcripción excedió la "context window" (ventana de contexto) del modelo asesor. |
| `execution_time_exceeded` | Se agotó el tiempo de espera de la subinferencia del asesor. |
| `model_not_found` | El modelo asesor configurado no está disponible. |
| `unavailable` | Cualquier otro fallo del asesor. |
Los límites de velocidad del asesor consumen la misma cuota por modelo que las llamadas directas al modelo asesor. Un límite de velocidad en el asesor aparece como `too_many_requests` dentro del resultado de la herramienta. Un límite de velocidad en el ejecutor hace fallar toda la solicitud con HTTP 429.
## Conversaciones de varios turnos
En los turnos posteriores, devuelve a la API el contenido completo del asistente, incluidos los bloques `advisor_tool_result`. Devuelve los bloques de resultado tal cual. Con un asesor Claude Opus 5, el `content` del bloque de resultado es la variante cifrada `advisor_redacted_result`. En el siguiente turno, el servidor la descifra e inserta el consejo en el prompt del ejecutor (consulta [Variantes de resultado](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#result-variants)). La mecánica es idéntica para cualquier modelo asesor.
```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,
)
# Agrega el contenido completo de la respuesta, incluidos los bloques advisor_tool_result
messages.append({"role": "assistant", "content": response.content})
# Continúa la conversación
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
});
// Agrega el contenido completo de la respuesta, incluidos los bloques advisor_tool_result
messages.push({ role: "assistant", content: response.content });
// Continúa la conversación
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"]
});
// Agrega el contenido completo de la respuesta, incluidos los bloques advisor_tool_result
messages.Add(new BetaMessageParam
{
Role = Role.Assistant,
Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList()
});
// Continúa la conversación
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)
}
// Agrega el contenido completo de la respuesta, incluidos los bloques advisor_tool_result.
messages = append(messages, response.ToParam())
// Continúa la conversación
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());
// Agrega el contenido completo de la respuesta, incluidos los bloques advisor_tool_result
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.ASSISTANT)
.contentOfBetaContentBlockParams(
response.content().stream().map(BetaContentBlock::toParam).toList())
.build());
// Continúa la conversación
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'],
);
// Agrega el contenido completo de la respuesta, incluidos los bloques advisor_tool_result
$messages[] = ['role' => 'assistant', 'content' => $response->content];
// Continúa la conversación
$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"]
)
# Agrega el contenido completo de la respuesta, incluidos los bloques advisor_tool_result
messages << { role: "assistant", content: response.content }
# Continúa la conversación
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"]
)
```
Puedes quitar la herramienta de asesor de `tools` en un turno de seguimiento aunque el historial de mensajes aún contenga bloques `advisor_tool_result`. La solicitud se acepta y los bloques del historial se conservan, pero el modelo no puede llamar al asesor en ese turno. Aun así, debes enviar el encabezado beta `advisor-tool-2026-03-01` para que se acepten esos bloques del historial.
La herramienta de asesor no tiene un límite integrado a nivel de conversación. Para limitar las llamadas al asesor a lo largo de una conversación, cuéntalas del lado del cliente. Cuando alcances tu límite máximo, elimina la herramienta de asesor de tu arreglo `tools`. No necesitas quitar los bloques `advisor_tool_result` de tu historial de mensajes.
### Reanudar un turno pausado
Una respuesta puede terminar con `stop_reason: "pause_turn"` mientras una llamada al asesor sigue pendiente. En ese caso, la respuesta contiene el bloque `server_tool_use` del asesor sin su `advisor_tool_result` correspondiente. Para reanudar, agrega ese mensaje del asistente a `messages` con su contenido sin cambios, incluido el bloque `server_tool_use`. Luego, vuelve a enviar la solicitud con la misma herramienta de asesor y el mismo encabezado beta. No necesitas agregar un mensaje de usuario ni un bloque `tool_result`. La API ejecuta la llamada pendiente al asesor y continúa el turno del ejecutor en la nueva respuesta. Un turno reanudado puede volver a pausarse; si eso ocurre, repite el mismo paso.
Si omites la herramienta de asesor en la solicitud de reanudación, la API devuelve un error 400 `invalid_request_error`, porque el bloque `server_tool_use` pendiente no tiene una definición de herramienta con la cual ejecutarse. Incluye la herramienta siempre que haya una llamada pendiente.
Si, en cambio, el ejecutor llamó a una de tus herramientas en el mismo turno, la respuesta termina con `stop_reason: "tool_use"` mientras la llamada al asesor sigue pendiente. Envía los bloques `tool_result` como de costumbre; la llamada pendiente al asesor se ejecuta al inicio de esa siguiente solicitud. Consulta [Combinar herramientas de servidor y herramientas de cliente en un turno](https://platform.claude.com/docs/es/agents-and-tools/tool-use/server-tools#mixing-server-tools-and-client-tools-in-one-turn).
### Recordatorio a mitad de la conversación para ejecutores que llaman poco al asesor
Si un ejecutor Haiku no ha llamado al asesor en su primer turno de asistente, agrega un breve recordatorio como un mensaje de usuario adicional antes del segundo turno de asistente. En la evaluación de comportamiento interna de Anthropic con ejecutores Claude Haiku 4.5, esto aumentó las tasas de aprobación de tareas en aproximadamente 7 puntos porcentuales. En ejecutores Sonnet, el recordatorio en texto plano no tuvo un efecto medible en las pruebas de Anthropic. Las consideraciones sobre el momento de las llamadas que siguen son especialmente relevantes para Sonnet. No apliques el recordatorio a ejecutores Opus: en Opus redujo ligeramente las tasas de aprobación.
Con el `NUDGE_TURN` predeterminado de 2, el recordatorio normalmente llega después de que el modelo se ha orientado en la tarea, pero antes de que se haya comprometido con un enfoque.
```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):
# Reemplaza con tu despacho de herramientas. Devuelve un bloque tool_result por cada bloque 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"},
# ... tus otras herramientas
]
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})
# Omite esto si tu indicación del sistema ya le indica al modelo que haga llamadas con moderación.
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[] {
// Reemplaza con tu despacho de herramientas. Devuelve un bloque tool_result por cada bloque 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" }
// ... tus otras herramientas
];
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 });
}
// Omite esto si tu indicación del sistema ya le indica al modelo que haga llamadas con moderación.
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
// Reemplaza esto con tu despacho de herramientas. Devuelve un bloque tool_result por cada bloque 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 }
// ... tus otras herramientas
};
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 });
}
// Omite esto si tu indicación del sistema ya le indica al modelo que haga llamadas con moderación.
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
)
// Reemplaza con tu despacho de herramientas. Devuelve un bloque tool_result por cada bloque 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,
}},
// ... tus otras herramientas
}
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,
})
}
// Omite esto si tu indicación del sistema ya le indica al modelo que haga llamadas con moderación.
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
// Reemplaza con tu despacho de herramientas. Devuelve un bloque tool_result por cada bloque 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())
// ... tus otras herramientas
);
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());
}
// Omite esto si tu indicación del sistema ya le indica al modelo que haga llamadas con moderación.
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
// Reemplaza con tu despacho de herramientas. Devuelve un bloque tool_result por cada bloque 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'],
// ... tus otras herramientas
];
$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];
}
// Omite esto si tu indicación del sistema ya le indica al modelo que llame con moderación.
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
# Reemplaza con tu despacho de herramientas. Devuelve un bloque tool_result por cada bloque 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" }
# ... tus otras herramientas
]
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?
# Omite esto si tu indicación del sistema ya le indica al modelo que haga llamadas con moderación.
messages << { role: "user", content: NUDGE_TEXT } if turn == NUDGE_TURN - 1 && !advisor_called
end
```
El bucle termina con cualquier motivo de detención distinto de `tool_use` o `pause_turn`. Si `max_tokens` corta una respuesta, elimina el turno de asistente truncado de `messages` y [vuelve a intentarlo con un `max_tokens` mayor](https://platform.claude.com/docs/es/build-with-claude/handling-stop-reasons#max-tokens). Cuando ese turno no contiene ningún bloque `tool_use`, puedes en cambio conservarlo y [continuar la respuesta](https://platform.claude.com/docs/es/build-with-claude/handling-stop-reasons#ensuring-complete-responses) con un nuevo mensaje de usuario. Volver a enviar el turno de asistente truncado como último mensaje es un [prefill](https://platform.claude.com/docs/es/api/errors#prefill-not-supported), que Claude 4.6 y los modelos posteriores rechazan.
Agrega el recordatorio como su propio mensaje de usuario después de los resultados de herramientas, en lugar de como un bloque hermano en el mismo mensaje. Los mensajes de usuario consecutivos son válidos. En las pruebas de Anthropic con ejecutores Claude Haiku 4.5 y Sonnet, se comportaron de forma equivalente a un bloque hermano. La forma de mensaje separado también mantiene el recordatorio claramente diferenciado de la salida de las herramientas.
**Compensaciones:** El recordatorio aumenta la tasa de llamadas, lo que puede llevar tareas trivialmente simples a una consulta innecesaria. Si tu carga de trabajo mezcla tareas simples y complejas, considera aumentar `NUDGE_TURN` a 3 para que las tareas de dos turnos se completen antes de que se active el recordatorio, o condiciona el recordatorio a una señal de complejidad de la tarea que ya calcules. Si tu indicación del sistema ya contiene lenguaje de moderación ("reserva el asesor para la incertidumbre genuina"), omite el recordatorio por completo, porque las dos instrucciones entran en conflicto.
El recordatorio en texto plano es muy prominente en los ejecutores Claude Haiku 4.5 y Sonnet: entre el 74 por ciento (Sonnet) y el 98 por ciento (Claude Haiku 4.5) de los intentos con recordatorio en las pruebas de Anthropic llamaron al asesor inmediatamente en el turno 2. Si eso ocurre antes de que tu ejecutor haya leído el problema o reunido contexto, la llamada resultante al asesor tiene poco contexto y puede desplazar una llamada posterior mejor sincronizada. Mide el turno de la primera llamada de referencia de tu ejecutor antes de agregar el recordatorio. Si el ejecutor ya llama al asesor de forma confiable y su primera llamada normalmente ocurre en el turno N, establece `NUDGE_TURN` en un valor mayor que N. En las pruebas de Anthropic, un recordatorio en el turno 2 en cargas de trabajo donde la primera llamada de referencia era en el turno 7 o posterior se correlacionó con una caída de 3 a 4 puntos porcentuales en el rendimiento de las tareas. En una carga de trabajo de navegación donde la tasa de llamadas de referencia era del 86 por ciento, el mismo recordatorio aumentó la participación sin costo en el rendimiento de las tareas.
Para forzar una consulta en una solicitud específica en lugar de usar un recordatorio, establece `tool_choice` en `{"type": "tool", "name": "advisor"}`, sujeto a las restricciones de [Forzar el uso de herramientas](https://platform.claude.com/docs/es/agents-and-tools/tool-use/define-tools#forcing-tool-use). Forzar el uso de herramientas no se puede combinar con el pensamiento extendido manual (`thinking: {type: "enabled"}`): la API devuelve un `400 invalid_request_error` si habilitas ambos. El pensamiento adaptativo admite el uso forzado de herramientas. Los ejecutores Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 y Claude Mythos 5.1 rechazan los tipos `tool` y `any` de `tool_choice`, así que usa el recordatorio en el prompt en esos modelos.
## Streaming
La subinferencia del asesor no admite streaming. El stream del ejecutor se pausa mientras el asesor se ejecuta y, después, el resultado completo llega en un solo evento.
El bloque `server_tool_use` con `name: "advisor"` indica que está comenzando una llamada al asesor. La pausa comienza cuando ese bloque se cierra (`content_block_stop`). Durante la pausa, el stream permanece en silencio, salvo por los keepalives `ping` estándar de SSE, que se emiten aproximadamente cada 30 segundos. Es posible que las llamadas cortas al asesor no muestren pings.
Cuando el asesor termina, el `advisor_tool_result` llega completo en un solo evento `content_block_start` (sin deltas). Luego, la salida del ejecutor reanuda el streaming.
A continuación llega un evento `message_delta` con el arreglo `usage.iterations` actualizado, que refleja los recuentos de tokens del asesor.
## Uso y facturación
Las llamadas al asesor se ejecutan como una subinferencia separada que se factura a las tarifas del modelo asesor. El uso se informa en el arreglo `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
}
]
}
}
```
Los campos `usage` de nivel superior reflejan solo los tokens del ejecutor. Los tokens del asesor no se suman a los totales de nivel superior porque se facturan a una tarifa diferente. Las iteraciones con `type: "advisor_message"` se facturan a las tarifas del modelo asesor, y las iteraciones con `type: "message"`, a las tarifas del modelo ejecutor.
Cada campo `usage` de nivel superior es la suma de ese campo en todas las iteraciones del ejecutor, incluidos `input_tokens`, `output_tokens` y `cache_read_input_tokens`. Como cada iteración del ejecutor vuelve a enviar la conversación, que va creciendo, las entradas de las iteraciones posteriores incluyen la salida de las anteriores. Por eso, la suma de `input_tokens` supera el tamaño de cualquier prompt individual. Usa `usage.iterations` para obtener un desglose completo por iteración cuando crees lógica de seguimiento de costos.
La salida del asesor suele ser de 400 a 700 tokens de texto, o de 1,400 a 1,800 tokens en total si se incluye el pensamiento. El ahorro de costos se debe a que el asesor no genera tu salida final completa: de eso se encarga el ejecutor, a su tarifa más baja.
El `max_tokens` de nivel superior se aplica solo a la salida del ejecutor y no limita los tokens de la subinferencia del asesor. Para limitar directamente la salida del asesor, establece [`max_tokens` en la definición de la herramienta](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#capping-advisor-output). Los tokens del asesor tampoco se descuentan de ningún [presupuesto de tarea](https://platform.claude.com/docs/es/build-with-claude/task-budgets) aplicado al ejecutor.
[Priority Tier](https://platform.claude.com/docs/es/api/service-tiers) se aplica a cada modelo de forma independiente. Un compromiso de Priority Tier en el modelo ejecutor no se extiende al asesor. Las llamadas al asesor se ejecutan en Priority Tier solo si tu organización también tiene un compromiso en el modelo asesor.
## Almacenamiento en caché de prompts del asesor
Hay dos capas de almacenamiento en caché independientes.
### Almacenamiento en caché del lado del ejecutor
El bloque `advisor_tool_result` se puede almacenar en caché como cualquier otro bloque de contenido. Un punto de interrupción `cache_control` colocado después de él en un turno posterior produce un acierto de caché. El prompt del ejecutor siempre contiene el consejo en texto plano, sin importar si tu cliente recibió `text` o `encrypted_content`. Por eso, el almacenamiento en caché se comporta igual con ambas variantes de resultado.
### Almacenamiento en caché del lado del asesor
Establece `caching` en la definición de la herramienta para habilitar el almacenamiento en caché de prompts para la propia transcripción del asesor entre llamadas dentro de la misma conversación:
```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" }
}
]
```
El prompt del asesor en la N-ésima llamada es el prompt de la llamada (N-1) con un segmento más agregado, por lo que el prefijo es estable entre llamadas. Con `caching` habilitado, cada llamada al asesor escribe una entrada de caché, y la siguiente llamada lee hasta ese punto y paga solo por la diferencia. Verás que `cache_read_input_tokens` deja de ser cero en la segunda iteración `advisor_message` y en las posteriores.
**Cuándo habilitarlo:** La escritura en caché cuesta más de lo que ahorran las lecturas cuando el asesor se llama dos veces o menos por conversación. El almacenamiento en caché alcanza el punto de equilibrio aproximadamente con tres llamadas al asesor y mejora a partir de ahí. Habilítalo para bucles de agente largos y mantenlo desactivado para tareas cortas.
**Mantenlo consistente:** Establece `caching` una vez y déjalo así durante toda la conversación. Desactivarlo y activarlo a mitad de la conversación provoca fallos de caché.
[`clear_thinking`](https://platform.claude.com/docs/es/build-with-claude/context-editing) con un valor de `keep` distinto de `"all"` desplaza la transcripción citada del asesor en cada turno, lo que provoca fallos de caché del lado del asesor. Esto es solo una degradación de costos. La calidad del consejo no se ve afectada. Cuando el pensamiento está activado sin una configuración explícita de `clear_thinking`, la API usa de forma predeterminada `keep: {type: "thinking_turns", value: 1}`, lo que desencadena este comportamiento (el valor predeterminado en los modelos Opus y Sonnet anteriores y en los modelos Haiku hasta Claude Haiku 4.5; en Claude Opus 4.5 y los modelos Opus posteriores, Claude Sonnet 4.6 y los modelos Sonnet posteriores, y Claude Haiku 5.5, el valor predeterminado es conservar todos los turnos). Establece `keep: "all"` para preservar la estabilidad de la caché del asesor.
## Combinación con otras herramientas
La herramienta de asesor se combina con otras herramientas del lado del servidor y del lado del cliente. Agrégalas todas al mismo arreglo `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" } }
}
}
]
```
El ejecutor puede buscar en la web, llamar al asesor y usar tus herramientas personalizadas en el mismo turno. El plan del asesor puede orientar qué herramientas usará el ejecutor a continuación.
| Función | Interacción |
| ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Procesamiento por lotes](https://platform.claude.com/docs/es/build-with-claude/batch-processing) | Compatible. `usage.iterations` se informa por elemento. |
| [Conteo de tokens](https://platform.claude.com/docs/es/build-with-claude/token-counting) | Devuelve solo los tokens de entrada de la primera iteración del ejecutor. Para una estimación aproximada del asesor, llama a `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`) con `model` establecido en el modelo asesor y los mismos mensajes. |
| [Edición de contexto](https://platform.claude.com/docs/es/build-with-claude/context-editing) | `clear_tool_uses` no es totalmente compatible con los bloques de la herramienta de asesor. Con `clear_thinking`, consulta la advertencia anterior sobre el almacenamiento en caché. |
| `pause_turn` | Una llamada al asesor pendiente termina la respuesta con `stop_reason: "pause_turn"` y un bloque `server_tool_use` sin resultado cuando ningún bloque `tool_use` del cliente está esperando tu resultado en el mismo turno. El asesor se ejecuta al reanudar. Si el ejecutor también llamó a una de tus herramientas en ese turno, la respuesta termina en cambio con `stop_reason: "tool_use"`, y la llamada pendiente al asesor se ejecuta al inicio de tu siguiente solicitud, después de que envíes los bloques `tool_result`. Consulta [Reanudar un turno pausado](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#resuming-a-paused-turn), [Combinar herramientas de servidor y herramientas de cliente en un turno](https://platform.claude.com/docs/es/agents-and-tools/tool-use/server-tools#mixing-server-tools-and-client-tools-in-one-turn) y [Herramientas de servidor](https://platform.claude.com/docs/es/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn). |
## Mejores prácticas
### Prompts para tareas de programación y de agentes
La herramienta de asesor incluye una descripción integrada que anima al ejecutor a llamarla cerca del inicio de las tareas complejas y cuando encuentra dificultades. En las tareas de investigación, normalmente no se necesitan prompts adicionales.
En las tareas de programación y de agentes, el asesor aporta mayor inteligencia a un costo similar cuando reduce el total de llamadas a herramientas y la longitud de la conversación. Dos momentos de llamada impulsan esta mejora:
1. Una primera llamada temprana al asesor, cuando la transcripción ya incluye algunas lecturas exploratorias.
2. En tareas difíciles, una llamada final al asesor, cuando la transcripción ya incluye las escrituras de archivos y las salidas de las pruebas.
Si tu agente expone otras herramientas de planificación (por ejemplo, una herramienta de lista de tareas), indica al modelo que llame al asesor antes de usarlas, para que el plan del asesor se traslade a ellas. La [indicación del sistema sugerida](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#suggested-system-prompt-for-coding-tasks) refuerza el patrón de llamada temprana. Agrega tu propia oración que indique al modelo que traslade el plan a las herramientas de planificación que exponga tu agente.
#### Indicación del sistema sugerida para tareas de programación
Sin orientación en la indicación del sistema, el ejecutor tiende a llamar poco al asesor en algunos dominios, en particular en las tareas de programación. Si en tus tareas de programación quieres que el asesor se llame en momentos consistentes y unas dos o tres veces por tarea, antepón los siguientes bloques a la indicación del sistema de tu ejecutor. Colócalos antes de cualquier otra oración que mencione al asesor.
Orientación sobre el momento de las llamadas:
```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.
```
Cómo debe tratar el ejecutor el consejo (colócalo justo después del bloque sobre el momento de las llamadas):
```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.
```
#### Indicación del sistema alternativa para Haiku en cargas de trabajo de programación
Claude Haiku 4.5 aplica la orientación predeterminada del asesor de forma conservadora. Eso mantiene su tasa de llamadas adecuadamente baja en cargas de trabajo de investigación y búsqueda. Sin embargo, sacrifica calidad en las cargas de trabajo de programación, donde una consulta temprana al asesor compensa de forma confiable. En un benchmark interno de programación, una variante muy similar del siguiente bloque aumentó las tasas de aprobación de Haiku en aproximadamente 7.5 puntos porcentuales respecto al valor predeterminado integrado. (La excepción para acciones de solo lectura en la regla "Hard rule" se agregó después de la medición).
Usa este bloque en lugar de los bloques anteriores sobre el momento de las llamadas y el consejo cuando tu ejecutor Haiku ejecute principalmente cargas de trabajo de programación o de escritura:
```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.
```
**Advertencia:** En un benchmark interno de comprensión de navegación (n = 1,266), una variante muy similar de este bloque redujo la precisión en aproximadamente 4 puntos porcentuales respecto al valor predeterminado integrado. Si tu carga de trabajo combina programación con una cantidad considerable de búsqueda o recuperación, mantén los [bloques sugeridos](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#suggested-system-prompt-for-coding-tasks). También puedes condicionar el cambio a una señal del tipo de carga de trabajo que ya calcules.
#### Aumentar las llamadas al asesor en ejecutores Opus
Los ejecutores Opus suelen llamar al asesor con una frecuencia adecuada sin prompts adicionales. Si tu ejecutor Opus llama poco al asesor en tu carga de trabajo, agrega el siguiente punto de control a tu indicación del 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.
```
**Advertencia:** En las pruebas de Anthropic, una variante muy similar de este bloque aumentó entre 7 y 10 puntos porcentuales las tasas de aprobación en las tareas donde Opus llamaba poco al asesor. (La excepción para acciones de solo lectura en la regla "Hard rule" se agregó después de la medición). Sin embargo, también hizo que Opus llamara en exceso en tareas cuya primera acción no requiere planificación. En una carga de trabajo mixta, el efecto neto fue prácticamente nulo. Agrégalo solo si has observado que Opus omite el asesor en tareas donde una consulta habría ayudado. No lo agregues de forma predeterminada.
#### Reducir la longitud de la salida del asesor
La salida del asesor es su mayor factor de costo, y el `max_tokens` de nivel superior no la limita. El asesor ve tanto tu indicación del sistema como tus mensajes de usuario como contexto citado sobre la tarea del ejecutor. Por eso, sigue mucho mejor las instrucciones dirigidas directamente a él que las descripciones en tercera persona. La ubicación más efectiva que probó Anthropic es una línea en el mensaje del usuario:
```text wrap
(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)
```
Tu framework de agentes puede anteponer esta línea automáticamente antes de enviar la solicitud. El límite es una restricción flexible y el asesor a veces lo supera, así que pide aproximadamente el 80 por ciento de tu límite real.
En las pruebas de Anthropic, esta línea también aumentó la frecuencia con la que el ejecutor consulta al asesor, pero el efecto neto siguió siendo un costo total menor (más consultas, pero cada una más corta).
Para lograr el mejor equilibrio entre costo y calidad, combina este enfoque con la orientación sobre el momento de las llamadas de [Indicación del sistema sugerida para tareas de programación](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#suggested-system-prompt-for-coding-tasks) (o con el [bloque alternativo para Haiku](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#alternative-system-prompt-for-haiku-on-coding-workloads), si lo usas en su lugar). Si necesitas un límite estricto en lugar de una solicitud flexible, consulta [Limitar la salida del asesor](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#capping-advisor-output).
### Limitar la salida del asesor
Establece `max_tokens` en la definición de la herramienta para limitar la salida total del asesor (pensamiento más texto) por llamada:
```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
}
]
```
El valor mínimo es 1024. Si estableces `max_tokens` por encima del límite de salida propio del modelo asesor, la API devuelve un error 400. El límite se aplica a cada llamada al asesor de forma independiente y no se comparte entre las llamadas de una misma solicitud.
No se trata solo de un truncamiento estricto: el servidor también le indica al asesor cuántos tokens le quedan, para que ajuste su respuesta a ese presupuesto.
**Punto de partida recomendado:** `max_tokens: 2048`. En las pruebas de Anthropic con un benchmark de razonamiento difícil (n = 40 por configuración), este valor redujo la salida media del asesor unas 7 veces en comparación con no establecer el límite. Además, casi no hubo truncamientos ni una degradación de calidad detectable. El valor mínimo de 1024 redujo la salida unas 10 veces, pero truncó alrededor del 10 por ciento de las llamadas. Con este tamaño de muestra, las diferencias de precisión entre todas las configuraciones quedaron dentro del margen de ruido. Valida los resultados con tu propia carga de trabajo.
| `max_tokens` | Tokens de salida medios del asesor | Llamadas truncadas |
| -------------- | ---------------------------------- | ------------------ |
| sin establecer | \~4,200 a 5,900 | n/d |
| 2048 | \~630 a 840 | \~0% |
| 1024 | \~370 a 480 | \~10% |
Las tareas de razonamiento difíciles generan una salida del asesor considerablemente más larga que los [1,400 a 1,800 tokens típicos](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#usage-and-billing) mencionados antes para cargas de trabajo más ligeras. Usa esta tabla para estimar la proporción de ahorro, no como referencia universal de la salida del asesor.
Cuando el asesor alcanza el límite, el bloque de resultado incluye `stop_reason: "max_tokens"` en ambas [variantes de resultado](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#result-variants), sin importar qué modelo asesor uses. Usa `stop_reason` para detectar consejos truncados y decidir si aumentas el límite o dejas que el ejecutor continúe con una orientación parcial. La API también agrega `[Advisor output truncated at max_tokens=2048.]` (con el valor de tu límite) al texto del consejo, para que el ejecutor vea el truncamiento en su propio contexto. Con un asesor que devuelve `advisor_result` en texto plano, tu cliente también puede ver ese marcador. Ambas señales aparecen solo cuando estableces `max_tokens` en la definición de la herramienta.
```json
{
"type": "advisor_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "advisor_redacted_result",
"encrypted_content": "EqQBCkYIBRgCIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
"stop_reason": "max_tokens"
}
}
```
Revisa `output_tokens` en la entrada `advisor_message` correspondiente de `usage.iterations` para ver qué tan cerca estuvo cada llamada de su límite.
A diferencia del [enfoque basado en prompts](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#trimming-advisor-output-length), `max_tokens` es un límite estricto y no una solicitud flexible. Usa `max_tokens` cuando necesites un límite garantizado de costo o de "latency" (latencia). Usa el enfoque basado en prompts (o ambos a la vez) cuando quieras favorecer la brevedad sin arriesgarte a que el consejo se corte a mitad de una idea.
### Combinación con la configuración de effort
Para tareas de programación, combinar un "executor" (ejecutor) Sonnet con un [effort](https://platform.claude.com/docs/es/build-with-claude/effort) (esfuerzo) medio con un "advisor" (asesor) Opus logra una inteligencia comparable a la de Sonnet con el esfuerzo predeterminado, a un costo menor. Para obtener la máxima inteligencia, mantén el ejecutor con el esfuerzo predeterminado.
### Control de costos
* Para presupuestos a nivel de conversación, cuenta las llamadas al asesor del lado del cliente. Cuando alcances tu límite, elimina la herramienta de asesor de `tools`; no necesitas quitar los bloques `advisor_tool_result` de tu historial de mensajes (consulta la nota en [Conversaciones de varios turnos](https://platform.claude.com/docs/es/agents-and-tools/tool-use/advisor-tool#multi-turn-conversations)).
* Habilita `caching` solo para conversaciones en las que esperes tres o más llamadas al asesor.
## Compatibilidad de modelos
El modelo ejecutor (el campo `model` de nivel superior) y el modelo asesor (el campo `model` dentro de la definición de la herramienta) deben formar un par válido. El asesor debe ser Claude Sonnet 4.6 o un modelo más capaz, y debe ser al menos tan capaz como el ejecutor. Los modelos de igual capacidad (por ejemplo, Claude Opus 4.7 y Claude Opus 4.8) pueden asesorarse entre sí.
| Modelos ejecutores | Modelos asesores |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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) |
Si solicitas un par no válido, la API devuelve un `400 invalid_request_error` que indica la combinación no admitida.
### Disponibilidad en plataformas
La herramienta de asesor está disponible en beta en la Claude API y en [Claude Platform on AWS](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws). Actualmente no está disponible en Amazon Bedrock, Google Cloud ni Microsoft Foundry.
## Asesor en Claude Managed Agents
Las sesiones de [Claude Managed Agents](https://platform.claude.com/docs/es/managed-agents/overview) también admiten un asesor, configurado como parte del agente en lugar de como una definición de herramienta: establece `"advisor": {"type": "enabled", "model": ...}` en el bloque `multiagent` del agente, y el hilo principal de la sesión podrá consultar ese modelo a mitad de un turno. La configuración no acepta las opciones `max_uses`, `max_tokens` ni `caching`, y el consejo se entrega como eventos de hilo en el flujo de eventos de la sesión en lugar de como bloques `advisor_tool_result` en la respuesta. Consulta [Darle un asesor a la sesión](https://platform.claude.com/docs/es/managed-agents/multiagent-orchestration#give-the-session-an-advisor).
## Próximos pasos
Almacena y recupera información entre conversaciones con un directorio de memoria del lado del cliente.
Trabaja con herramientas ejecutadas por Anthropic: bloques server\_tool\_use, continuación con pause\_turn y filtrado de dominios.
Directorio de herramientas proporcionadas por Anthropic y referencia de las propiedades opcionales de la definición de herramientas.
Controla cuántos tokens usa Claude al responder mediante el parámetro effort, equilibrando la exhaustividad de la respuesta y la eficiencia de tokens.