Herramienta de asesor

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.

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

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 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 para ver ambas formas lado a lado y qué modelos asesores devuelven cada una. Consulta Compatibilidad de modelos 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 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).

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

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). Consulta la Referencia de herramientas 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 usa Claude Opus 5, que en su lugar devuelve la variante cifrada advisor_redacted_result; consulta Variantes de resultado para ver ambas formas lado a lado.

{
  "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:

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:

{
  "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:

{
  "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 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 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:

{
  "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 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). La mecánica es idéntica para cualquier modelo asesor.

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

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.

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.

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.

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

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. Cuando ese turno no contiene ningún bloque tool_use, puedes en cambio conservarlo y continuar la respuesta con un nuevo mensaje de usuario. Volver a enviar el turno de asistente truncado como último mensaje es un prefill, 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. 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[]:

{
  "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. Los tokens del asesor tampoco se descuentan de ningún presupuesto de tarea aplicado al ejecutor.

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 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:

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é.

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:

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.

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 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:

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

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:

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. 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:

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:

(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.

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 (o con el bloque alternativo para Haiku, si lo usas en su lugar). Si necesitas un límite estricto en lugar de una solicitud flexible, 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-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.

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

{
  "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, 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 (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).
• 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í.

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. 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: 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.

Próximos pasos