Herramienta advisor

La herramienta "advisor" (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 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 múltiples pasos) donde la mayoría de los turnos son mecánicos pero contar con un plan excelente es crucial. Obtienes una calidad cercana a la del asesor en solitario mientras que la mayor parte de la generación de tokens ocurre a las tarifas del modelo ejecutor.



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 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 cambiar el ejecutor a un modelo más grande.

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

El asesor es menos adecuado para 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, o cargas de trabajo donde cada turno realmente requiere la capacidad completa del modelo asesor.



Inicio rápido

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)

El content de la respuesta incluye un bloque advisor_tool_result que contiene la orientación del asesor. Con Claude Opus 5, Claude Fable 5 o Claude Mythos 5 como asesor, 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 advisor_result en texto plano. Consulta Variantes de resultado para ambas formas y Compatibilidad de modelos para la lista completa de pares válidos.



Cómo funciona

Cuando agregas la herramienta advisor a tu arreglo tools, el modelo ejecutor determina cuándo llamarla, como cualquier otra herramienta. Cuando el ejecutor llama al asesor:

1. El ejecutor emite un bloque server_tool_use con name: "advisor" y un input vacío. El ejecutor señala 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 bajo su propia indicación del sistema proporcionada 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 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, informado por el consejo.

Todo esto ocurre dentro de una sola solicitud a /v1/messages, sin viajes de ida y vuelta adicionales de tu lado. La excepción es un turno que se pausa a mitad de la llamada, el cual reanudas con una solicitud de seguimiento (consulta Reanudar un turno pausado).

El asesor en sí 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 del 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 interrupción. Es un interruptor de encendido/apagado. El servidor determina dónde van los límites de caché.

La herramienta advisor también acepta las propiedades genéricas disponibles en cualquier definición de herramienta: cache_control, allowed_callers, defer_loading y strict (cubierto en salidas estructuradas). Consulta la Referencia de herramientas para su semántica.



Estructura de la respuesta



Llamada exitosa al asesor

Cuando se llama al asesor, un bloque server_tool_use es seguido por un bloque advisor_tool_result en el contenido del asistente. El siguiente ejemplo muestra la variante advisor_result en texto plano devuelta por un asesor Claude Opus 4.8. El Inicio rápido usa Claude Opus 5, que devuelve la variante cifrada advisor_redacted_result en su lugar; consulta Variantes de resultado.

{
  "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 ponga en input llega al asesor.



Variantes de resultado

El campo advisor_tool_result.content es una unión discriminada. Para llamadas exitosas, la variante depende del modelo asesor:

Los asesores Claude Opus 5, Claude Fable 5 y Claude Mythos 5 devuelven advisor_redacted_result. Los otros modelos asesores en la tabla de compatibilidad devuelven advisor_result.

Ambas variantes de resultado incluyen un campo stop_reason cuando estableces max_tokens en la definición de la herramienta, y lo omiten cuando no lo haces. Contiene el stop reason de la subllamada del asesor, típicamente "end_turn", o "max_tokens" cuando se alcanza el límite. Los valores coinciden con el stop_reason de nivel superior de la API de Messages.

Con advisor_result, el campo text contiene consejos legibles 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, reenvía el contenido sin modificaciones en los turnos subsiguientes. Si cambias de modelo asesor a mitad de la conversación, bifurca según content.type para manejar ambas formas.



Resultados de error

Si la llamada al asesor falla, el resultado contiene 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 consejos. La solicitud en sí no falla.

Los límites de velocidad del asesor se descuentan del mismo bucket 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 múltiples turnos

Pasa el contenido completo del asistente, incluidos los bloques advisor_tool_result, de vuelta a la API en los turnos subsiguientes. Este ejemplo usa claude-opus-4-8 como asesor para que el consejo en texto plano sea visible en response.content; la mecánica es idéntica para cualquier modelo asesor.

client = anthropic.Anthropic()

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

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,
)

Puedes quitar la herramienta advisor de tools en un turno de seguimiento mientras el historial de mensajes aún contiene bloques advisor_tool_result. La solicitud se acepta y los bloques históricos se preservan; el modelo no puede llamar al asesor en ese turno. Aún debes enviar el encabezado beta advisor-tool-2026-03-01 para que esos bloques del historial sean aceptados.



Reanudar un turno pausado

Una respuesta puede terminar con stop_reason: "pause_turn" mientras una llamada al asesor aún está pendiente. Cuando eso ocurre, la respuesta contiene el bloque server_tool_use del asesor sin un advisor_tool_result correspondiente. Para reanudar, agrega ese mensaje del asistente a messages con su contenido sin cambios, manteniendo el bloque server_tool_use, y envía la solicitud nuevamente con la misma herramienta advisor y el 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 pausarse nuevamente. Si lo hace, repite el mismo paso. Omitir la herramienta advisor de la solicitud de reanudación devuelve un 400 invalid_request_error, porque el bloque server_tool_use pendiente no tiene una definición de herramienta contra 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 aún está pendiente. Envía los bloques tool_result como de costumbre, y la llamada pendiente al asesor se ejecuta al inicio de esa siguiente solicitud. Consulta Mezclar herramientas de servidor y herramientas de cliente en un turno.



Recordatorio a mitad de 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, esto elevó las tasas de aprobación de tareas en aproximadamente 7 puntos porcentuales en ejecutores Haiku. En ejecutores Sonnet, el recordatorio en texto plano no tuvo un efecto medible en las pruebas de Anthropic. Las consideraciones sobre el momento de la llamada 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 típicamente llega después de que el modelo se ha orientado en la tarea pero antes de que se haya comprometido con un enfoque.

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-4-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 == "end_turn":
        break
    if response.stop_reason == "pause_turn":
        continue  # server tool pending; re-send to let the API complete it

    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 dice al modelo que llame con moderación.
    if turn == NUDGE_TURN - 1 and not advisor_called:
        messages.append({"role": "user", "content": NUDGE_TEXT})

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 Haiku y Sonnet se comportaron de manera equivalente a un bloque hermano. La forma de mensaje separado también mantiene el recordatorio claramente distinto de la salida de 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 tarea que ya calcules. Si tu indicación del sistema ya contiene lenguaje de moderación ("reserva el asesor para incertidumbre genuina"), omite el recordatorio por completo, porque las dos instrucciones entran en conflicto.

El recordatorio en texto plano es muy prominente en ejecutores Haiku y Sonnet: del 74 por ciento (Sonnet) al 98 por ciento (Haiku) 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 recopilado contexto, la llamada resultante al asesor tiene poco contexto y puede desplazar una llamada posterior mejor sincronizada. Mide el turno de primera llamada de referencia de tu ejecutor antes de agregar el recordatorio. Si el ejecutor ya llama al asesor de manera confiable y su primera llamada típicamente ocurre en el turno N, establece NUDGE_TURN 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 el turno 7 o posterior se correlacionó con una caída de 3 a 4 puntos porcentuales en el rendimiento de 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 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 en Forzar el uso de herramientas. Forzar el uso de herramientas no se puede combinar con 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.



Streaming

La subinferencia del asesor no hace streaming. El stream del ejecutor se pausa mientras el asesor se ejecuta; luego el resultado completo llega en un solo evento.

El bloque server_tool_use con name: "advisor" señala que una llamada al asesor está comenzando. La pausa comienza cuando ese bloque se cierra (content_block_stop). Durante la pausa, el stream está en silencio excepto por los keepalives ping estándar de SSE emitidos aproximadamente cada 30 segundos. Las llamadas cortas al asesor podrían no mostrar pings.

Cuando el asesor termina, el advisor_tool_result llega completamente formado en un solo evento content_block_start (sin deltas). La salida del ejecutor luego reanuda el streaming.

Un evento message_delta sigue 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 facturada a las tarifas del modelo asesor. El uso se reporta en el arreglo usage.iterations[]:

{
  "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 incluyen en 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" se facturan 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. Debido a que cada iteración del ejecutor reenvía la conversación creciente, las entradas de iteraciones posteriores incluyen la salida de iteraciones anteriores, por lo que la suma de input_tokens excede el tamaño de cualquier prompt individual. 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 de 400 a 700 tokens de texto, o de 1,400 a 1,800 tokens en total incluyendo el pensamiento. El ahorro de costos proviene de que el asesor no genera tu salida final completa. El ejecutor hace eso a su tarifa más baja.

El max_tokens de nivel superior se aplica solo a la salida del ejecutor. No limita los tokens de subinferencia del asesor. Para limitar la salida del asesor directamente, establece max_tokens en la definición de la herramienta. Los tokens del asesor tampoco se descuentan de ningún presupuesto de tarea aplicado al ejecutor.

El Priority Tier 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 caché independientes.



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 subsiguiente acierta. El prompt del ejecutor siempre contiene el consejo en texto plano independientemente de si tu cliente recibió text o encrypted_content, por lo que el comportamiento de caché es idéntico para ambas variantes de resultado.



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:

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

El prompt del asesor en la llamada N 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 el delta. Verás que cache_read_input_tokens se vuelve distinto de cero en la segunda iteración advisor_message y posteriores.

Cuándo habilitarlo: La escritura de caché cuesta más de lo que ahorran las lecturas cuando el asesor se llama dos veces o menos por conversación. El caché alcanza el punto de equilibrio aproximadamente en 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 durante toda la conversación. Activarlo y desactivarlo a mitad de conversación causa fallos de caché.



Combinación con otras herramientas

La herramienta advisor se compone con otras herramientas del lado del servidor y del lado del cliente. Agrégalas todas al mismo arreglo tools:

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 informar qué herramientas usa el ejecutor a continuación.



Mejores prácticas



Prompting para tareas de programación y agentes

La herramienta advisor incluye una descripción integrada que incita al ejecutor a llamarla cerca del inicio de tareas complejas y cuando encuentra dificultades. Para tareas de investigación, típicamente no se necesita prompting adicional.

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

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

Si tu agente expone otras herramientas tipo planificador (por ejemplo, una herramienta de lista de tareas), indica al modelo que llame al asesor antes que a esas herramientas para que el plan del asesor se canalice hacia ellas. La indicación del sistema sugerida refuerza el patrón de llamada temprana. Agrega tu propia oración de canalización apuntando a las herramientas de planificación que tu agente exponga.



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, particularmente en tareas de programación. Para tareas de programación donde quieres una sincronización consistente del asesor y alrededor de dos a tres llamadas por cada tarea, antepón los siguientes bloques a la indicación del sistema de tu ejecutor antes de cualquier otra oración que mencione al asesor.

Orientación sobre el momento:

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 (coloca directamente después del bloque de momento):

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 manera conservadora. Eso mantiene su tasa de llamadas apropiadamente baja en cargas de trabajo de investigación y búsqueda, pero sacrifica calidad en cargas de trabajo de programación, donde una consulta temprana al asesor se paga sola de manera confiable. En un benchmark interno de programación, una variante cercana del siguiente bloque (la excepción de solo lectura en la regla estricta se agregó después de la medición) elevó las tasas de aprobación de Haiku en aproximadamente 7.5 puntos porcentuales sobre el valor predeterminado integrado.

Usa este bloque en lugar de los bloques anteriores de momento y consejo cuando tu ejecutor Haiku ejecute predominantemente cargas de trabajo de programación o tareas de escritura:

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 cercana de este bloque costó aproximadamente 4 puntos porcentuales de precisión en relación con el valor predeterminado integrado. Si tu carga de trabajo mezcla programación con búsqueda o recuperación sustancial, quédate con los bloques sugeridos, o condiciona el cambio a una señal de tipo de carga de trabajo que ya calcules.



Aumentar las llamadas al asesor en ejecutores Opus

Los ejecutores Opus típicamente llaman al asesor a una tasa apropiada sin prompting adicional. Si tu ejecutor Opus está llamando poco al asesor en tu carga de trabajo, agrega el siguiente punto de control a tu indicación del sistema:

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 cercana de este bloque (la excepción de solo lectura en la regla estricta se agregó después de la medición) elevó las tasas de aprobación en tareas con pocas llamadas en aproximadamente 7 a 10 puntos porcentuales, pero causó que Opus llamara en exceso en tareas cuya primera acción no necesita planificación. El efecto neto fue aproximadamente neutro en una carga de trabajo mixta. Solo agrégalo si has observado que Opus omite al asesor en tareas donde una consulta habría ayudado. No lo agregues como predeterminado.



Recortar la longitud de salida del asesor

La salida del asesor es el mayor factor de costo del asesor, 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 lo que las instrucciones que se dirigen al asesor directamente se siguen de manera mucho más confiable que las descripciones en tercera persona. La ubicación más efectiva que Anthropic probó es una línea en el mensaje de usuario:

(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)

Esta línea puede ser prefijada programáticamente por tu framework de agente antes de enviar la solicitud. El límite es una restricción suave. El asesor ocasionalmente la excede, así que pide aproximadamente el 80 por ciento de tu tope real.

Combina este enfoque con la orientación de momento en Indicación del sistema sugerida para tareas de programación (o el bloque alternativo de Haiku si lo sustituiste) para el mejor equilibrio entre costo y calidad. Para un tope estricto en lugar de una solicitud suave, consulta Limitar la salida del asesor.



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:

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

El valor mínimo es 1024. Establecer max_tokens por encima del límite de salida propio del modelo asesor devuelve un error 400. El límite se aplica a cada llamada al asesor de forma independiente y no se comparte entre llamadas en la misma solicitud.

Esto no es solo un truncamiento estricto. El servidor también pasa al asesor su presupuesto de tokens restante, por lo que el asesor adapta su respuesta para ajustarse.

Punto de partida recomendado: max_tokens: 2048. En las pruebas de Anthropic en un benchmark de razonamiento difícil (n = 40 por configuración), esto redujo la salida media del asesor en aproximadamente 7x en comparación con dejar el límite sin establecer, con truncamiento casi nulo y sin degradación de calidad detectable. El valor mínimo de 1024 redujo la salida aproximadamente 10x pero truncó alrededor del 10 por ciento de las llamadas. Las diferencias de precisión en todas las configuraciones estuvieron dentro del ruido en este tamaño de muestra. Valida en tu propia carga de trabajo.

Las tareas de razonamiento difícil provocan una salida del asesor sustancialmente más larga que los típicos 1,400 a 1,800 tokens citados anteriormente para cargas de trabajo más ligeras. Usa esta tabla para dimensionar la proporción de ahorro, no como una referencia universal para la salida del asesor.

Cuando el asesor alcanza el límite, el bloque de resultado incluye stop_reason: "max_tokens". La API también agrega [Advisor output truncated at max_tokens=2048.] (nombrando tu límite) al texto del consejo, para que el ejecutor vea el truncamiento en su propio contexto. Usa stop_reason para detectar consejos truncados y decidir si aumentar el límite o dejar que el ejecutor proceda con orientación parcial. Ambas señales aparecen solo cuando estableces max_tokens en la definición de la herramienta.

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_result",
    "text": "Use a channel-based coordination pattern. The tricky part is\n\n[Advisor output truncated at max_tokens=2048.]",
    "stop_reason": "max_tokens"
  }
}

Revisa output_tokens en la entrada advisor_message correspondiente en usage.iterations para ver qué tan cerca estuvo cada llamada de su límite.

En comparación con el enfoque basado en prompts, max_tokens es un tope estricto en lugar de una solicitud suave. Usa max_tokens cuando necesites un límite garantizado para costo o latencia. Usa el enfoque basado en prompts (o ambos juntos) cuando quieras inclinarte hacia la brevedad sin arriesgar un corte a mitad de pensamiento.



Combinación con configuraciones de esfuerzo

Para tareas de programación, combinar un ejecutor Sonnet con esfuerzo medio con un asesor Opus logra una inteligencia comparable a Sonnet con esfuerzo predeterminado, a un costo menor. Para máxima inteligencia, mantén el ejecutor con 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 advisor de tools; no necesitas eliminar los bloques advisor_tool_result de tu historial de mensajes (consulta la nota en Conversaciones de múltiples turnos).
• Habilita caching solo para conversaciones donde 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 capacidad equivalente (por ejemplo, Claude Opus 4.7 y Claude Opus 4.8) pueden asesorarse mutuamente.

Si solicitas un par no válido, la API devuelve un error 400 invalid_request_error que indica la combinación no admitida.



Disponibilidad por plataforma

La herramienta de asesor está disponible en beta en la API de Claude y en Claude Platform en AWS. Actualmente no está disponible en Amazon Bedrock, Google Cloud ni Microsoft Foundry.



Asesor en Claude Managed Agents

Las sesiones de Claude Managed Agents también admiten un asesor, configurado como parte del agente en lugar de como una definición de herramienta: agrega una entrada {"type": "advisor", "model": ...} al roster multiagente del agente, y el hilo principal de la sesión podrá consultar ese modelo a mitad de turno. La entrada del roster no acepta las opciones max_uses, max_tokens ni caching, y el asesoramiento 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 Asignar un asesor a la sesión.



Próximos pasos