Herramienta de asesor

La herramienta de asesor permite que un modelo ejecutor más rápido y de menor costo consulte a un 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 corrección de curso (típicamente 400 a 700 tokens de texto, 1.400 a 1.800 tokens totales incluyendo pensamiento), y el ejecutor continúa con la tarea.

Este patrón se ajusta a cargas de trabajo agentes de horizonte largo (agentes de codificación, uso de computadora, canalizaciones de investigación de múltiples pasos) donde la mayoría de los turnos son mecánicos pero tener un excelente plan es crucial. Obtienes una calidad cercana a la del asesor solo mientras la mayor parte de la generación de tokens ocurre a las tasas del modelo ejecutor.

Cuándo usarla

Los primeros puntos de referencia muestran ganancias significativas para estas configuraciones:

• Actualmente usas Sonnet en tareas complejas: Agrega Opus como asesor para una mejora de calidad a costo similar o menor.
• Actualmente usas Haiku y deseas un paso hacia arriba en inteligencia: Agrega Opus como asesor. Espera un costo más alto que Haiku solo, pero menor que cambiar el ejecutor a un modelo más grande.

Los resultados dependen de la tarea. Evalúa en tu propia carga de trabajo.

El asesor es un ajuste más débil para preguntas y respuestas de un solo turno (nada que planificar), selectores de modelos de paso directo puro donde tus usuarios ya eligen su propio equilibrio de costo y calidad, o cargas de trabajo donde cada turno genuinamente requiere la capacidad completa del modelo 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 al menos tan capaz como el ejecutor.

Si solicitas un par inválido, la API devuelve un 400 invalid_request_error nombrando la combinación no compatible.

Disponibilidad de plataforma

La herramienta de asesor está disponible en beta en Claude API (Anthropic).

Inicio rápido

Cómo funciona

Cuando agregas la herramienta de asesor a tu array tools, el modelo ejecutor decide cuándo llamarla, como cualquier otra herramienta. Cuando el ejecutor invoca al asesor:

1. El ejecutor emite un bloque server_tool_use con name: "advisor" e input vacío. El ejecutor señala el tiempo; el servidor proporciona contexto.
2. Anthropic ejecuta un pase de inferencia separado en el servidor del modelo asesor, pasando la transcripción completa del ejecutor. El asesor ve el mensaje del sistema, todas las definiciones de herramientas, todos los turnos anteriores y todos los resultados de herramientas anteriores.
3. La respuesta del asesor regresa al ejecutor como un bloque advisor_tool_result.
4. El ejecutor continúa generando, informado por el consejo.

Todo esto sucede dentro de una única solicitud /v1/messages. Sin viajes redondos adicionales de tu parte.

El asesor mismo se ejecuta sin herramientas y sin gestión de contexto. Sus bloques de pensamiento se descartan antes de que el resultado regrese; solo el texto de consejo llega al ejecutor.

Parámetros de la herramienta

El objeto caching tiene la forma {"type": "ephemeral", "ttl": "5m" | "1h"}. A diferencia de cache_control en bloques de contenido, esto no es un marcador de punto de ruptura; es un interruptor de encendido/apagado. El servidor decide dónde van los límites de caché.

Estructura de respuesta

Llamada de asesor exitosa

Cuando se invoca al asesor, un bloque server_tool_use es seguido por un bloque advisor_tool_result en el contenido del asistente:

{
  "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 la vista del asesor a partir de la transcripción completa automáticamente; nada de lo que el ejecutor pone en input llega al asesor.

Variantes de resultado

El campo advisor_tool_result.content es una unión discriminada. Qué variante recibes depende del modelo asesor:

Con advisor_result, el campo text contiene 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 sin formato en el mensaje del ejecutor.

En ambos casos, devuelve el contenido verbatim en turnos posteriores. Si cambias modelos asesores a mitad de la conversación, ramifica en content.type para manejar ambas formas.

Resultados de error

Si la llamada del asesor falla, el resultado lleva un error:

{
  "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 consejo. La solicitud en sí no falla.

Los límites de velocidad del asesor se extraen del mismo depósito 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 falla toda la solicitud con HTTP 429.

Conversaciones de múltiples turnos

Pasa el contenido completo del asistente, incluyendo bloques advisor_tool_result, de vuelta a la API en turnos posteriores:

import anthropic

client = anthropic.Anthropic()

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

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

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

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

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

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

Si omites la herramienta de asesor de tools en un turno de seguimiento mientras el historial de mensajes aún contiene bloques advisor_tool_result, la API devuelve un 400 invalid_request_error.

Transmisión

La sub-inferencia del asesor no se transmite. La transmisión del ejecutor se pausa mientras se ejecuta el asesor, luego el resultado completo llega en un único evento.

El bloque server_tool_use con name: "advisor" señala que se está iniciando una llamada de asesor. La pausa comienza cuando ese bloque se cierra (content_block_stop). Durante la pausa, la transmisión está silenciosa excepto por los ping de SSE estándar emitidos aproximadamente cada 30 segundos; las llamadas de asesor cortas pueden no mostrar pings.

Cuando el asesor termina, el advisor_tool_result llega completamente formado en un único evento content_block_start (sin deltas). La salida del ejecutor luego reanuda la transmisión.

Un evento message_delta sigue con el array usage.iterations actualizado reflejando los conteos de tokens del asesor.

Uso y facturación

Las llamadas del asesor se ejecutan como una sub-inferencia separada facturada a las tasas del modelo asesor. El uso se reporta en el array usage.iterations[]:

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

Los campos usage de nivel superior reflejan solo tokens del ejecutor. Los tokens del asesor no se incluyen en los totales de nivel superior porque se facturan a una tasa diferente. Las iteraciones con type: "advisor_message" se facturan a las tasas del modelo asesor; las iteraciones con type: "message" se facturan a las tasas del modelo ejecutor.

Las reglas de agregación difieren por campo. El output_tokens de nivel superior es la suma de todas las iteraciones del ejecutor. El input_tokens de nivel superior y cache_read_input_tokens reflejan solo la primera iteración del ejecutor; las entradas de iteraciones posteriores del ejecutor no se re-suman porque incluyen tokens de salida anteriores. Usa usage.iterations para un desglose completo por iteración al construir lógica de seguimiento de costos.

La salida del asesor es típicamente 400 a 700 tokens de texto, o 1.400 a 1.800 tokens totales incluyendo pensamiento. El ahorro de costo proviene del asesor que no genera tu salida final completa; el ejecutor hace eso a su tasa más baja.

El max_tokens de nivel superior se aplica solo a la salida del ejecutor. No limita los tokens de sub-inferencia del asesor. Los tokens del asesor tampoco se extraen de ningún presupuesto de tarea aplicado al ejecutor.

Almacenamiento en caché de solicitudes del asesor

Hay dos capas de almacenamiento en caché independientes.

Almacenamiento en caché del lado del ejecutor

El bloque advisor_tool_result es almacenable en caché como cualquier otro bloque de contenido. Un punto de ruptura cache_control colocado después de él en un turno posterior lo alcanzará. El mensaje del ejecutor siempre contiene el consejo de texto sin formato independientemente de si tu cliente recibió text o encrypted_content, por lo que el comportamiento de almacenamiento en caché es idéntico para 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 solicitudes para la propia transcripción del asesor en todas las llamadas dentro de la misma conversación:

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

El mensaje del asesor en la llamada N es el mensaje de la llamada (N-1) con un segmento más anexado, por lo que el prefijo es estable en todas las llamadas. Con caching habilitado, cada llamada del asesor escribe una entrada de caché; la siguiente llamada lee hasta ese punto y paga solo por el delta. Verás que cache_read_input_tokens se vuelve distinto de cero en la segunda y posteriores iteraciones advisor_message.

Cuándo habilitarlo: El costo de escritura de caché es mayor que lo que los ahorros de lectura cuando el asesor se llama dos o menos veces por conversación. El almacenamiento en caché se equilibra en aproximadamente tres llamadas de asesor y mejora a partir de ahí. Habilítalo para bucles de agente largos; mantenlo desactivado para tareas cortas.

Mantenlo consistente: Establece caching una vez y déjalo para toda la conversación. Alternarlo desactivado y activado a mitad de la conversación causa fallos de caché.

Combinación con otras herramientas

La herramienta de asesor se compone con otras herramientas del lado del servidor y del lado del cliente. Agrega todas al mismo array tools:

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

El ejecutor puede buscar en la web, llamar al asesor y usar tus herramientas personalizadas en el mismo turno. El plan del asesor puede informar qué herramientas alcanza el ejecutor a continuación.

Mejores prácticas

Indicaciones para tareas de codificación y agentes

La herramienta de asesor viene con una descripción integrada que empuja al ejecutor a llamarla cerca del inicio de tareas complejas y cuando encuentra dificultad. Para tareas de investigación, generalmente no se necesita indicación adicional.

En tareas de codificación y agentes, el asesor produce mayor inteligencia a costo similar cuando reduce el total de llamadas de herramientas y la longitud de la conversación. Dos tiempos impulsan esta mejora:

1. Una primera llamada de asesor temprana, después de que algunas lecturas exploratorias estén en la transcripción.
2. Para tareas difíciles, una llamada de asesor final después de que las escrituras de archivos y salidas de prueba estén en la transcripción.

Si tu agente expone otras herramientas similares a planificadores (por ejemplo, una herramienta de lista de tareas), solicita al modelo que llame al asesor antes de esas herramientas para que el plan del asesor se canalice hacia ellas. El mensaje del sistema sugerido a continuación refuerza el patrón de llamada temprana; agrega tu propia oración de canalización apuntando a cualquiera de las herramientas de planificador que tu agente exponga.

Mensaje del sistema sugerido para tareas de codificación

Para tareas de codificación donde deseas tiempo de asesor consistente y alrededor de dos a tres llamadas por tarea, antepón los siguientes bloques a tu mensaje del sistema del ejecutor antes de cualquier otra oración que mencione al asesor. En evaluaciones internas de codificación, este patrón produjo la mayor inteligencia a costo cercano a Sonnet.

Orientación de tiempo:

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 el ejecutor debe tratar el consejo (coloca directamente después del bloque de tiempo):

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.

Recorte de la longitud de salida del asesor

La salida del asesor es el mayor impulsor de costo del asesor. Para reducir ese costo, antepón una única instrucción de concisión al mensaje del sistema antes de cualquier otra oración que mencione al asesor. En pruebas internas, la siguiente línea redujo los tokens de salida total del asesor en aproximadamente 35 a 45 por ciento sin cambiar la frecuencia de llamadas:

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

Empareja esto con el bloque de tiempo anterior para el equilibrio más fuerte de costo versus calidad.

Emparejamiento con configuraciones de esfuerzo

Para tareas de codificación, emparejar un ejecutor Sonnet en esfuerzo medio con un asesor Opus logra inteligencia comparable a Sonnet en esfuerzo predeterminado, a menor costo. Para máxima inteligencia, mantén el ejecutor en esfuerzo predeterminado.

Control de costo

• Para presupuestos a nivel de conversación, cuenta las llamadas del asesor del lado del cliente. Cuando alcances tu límite, elimina la herramienta de asesor de tools y elimina todos los bloques advisor_tool_result de tu historial de mensajes para evitar un 400 invalid_request_error.
• Habilita caching solo para conversaciones donde esperas tres o más llamadas de asesor.

Limitaciones

• La salida del asesor no se transmite. Espera una pausa en la transmisión mientras se ejecuta la sub-inferencia.
• Sin límite integrado a nivel de conversación en llamadas de asesor. Rastrea y limita del lado del cliente.
• max_tokens se aplica solo a la salida del ejecutor. No limita los tokens del asesor.
• Anthropic Priority Tier se honra por modelo. Priority Tier en el modelo ejecutor no se extiende al asesor; necesitas Priority Tier en el modelo asesor específicamente.