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 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 codificación, uso de computadora, pipelines de investigación de múltiples 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 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 Opus como asesor para una mejora de calidad a un costo total similar o menor.
• Actualmente usas Haiku y quieres un salto en inteligencia: Agrega Opus como asesor. Espera un costo mayor que 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 una opción menos adecuada para preguntas y respuestas de un solo turno (no hay nada que planificar), selectores de modelos 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.



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 inválido, la API devuelve un 400 invalid_request_error indicando la combinación no compatible.



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.



Inicio rápido

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    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.",
        }
    ],
)

print(response)



Cómo funciona

Cuando agregas la herramienta de asesor a tu arreglo tools, el modelo ejecutor determina 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" 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 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, informado por el consejo.

Todo esto ocurre dentro de una sola solicitud /v1/messages, sin viajes de ida y vuelta adicionales de tu parte. La excepción es un turno que se pausa a mitad de 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 los 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 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 (cubiertas en salidas estructuradas). Consulta la Referencia de herramientas para conocer su semántica.



Estructura de la respuesta



Llamada exitosa al asesor

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 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 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 llevan un campo stop_reason cuando estableces max_tokens en la definición de la herramienta, y lo omiten cuando no lo haces. Contiene la razón de detención 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 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 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 consejos. La solicitud en sí no falla.

Los límites de velocidad del asesor se extraen del mismo contenedor 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 posteriores:

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-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

# Agrega el contenido completo de la respuesta, incluyendo cualquier bloque 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-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 todavía contiene bloques advisor_tool_result, la API devuelve un 400 invalid_request_error.



Reanudar un turno pausado

Una respuesta puede terminar con stop_reason: "pause_turn" mientras una llamada al asesor todavía está pendiente. Cuando eso sucede, 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 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 pausarse de nuevo. Si lo hace, repite el mismo paso. Omitir la herramienta de asesor de la solicitud de reanudación devuelve un 400 invalid_request_error. 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 todavía 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 del servidor y herramientas del cliente en un turno.



Recordatorio a mitad de conversación para ejecutores que llaman poco

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 conductual 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-4-8"},
    # ... 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(
        b.type == "server_tool_use" and b.name == "advisor" for b 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 eleva la tasa de llamadas, lo que puede empujar tareas trivialmente simples a una consulta innecesaria. Si tu carga de trabajo mezcla tareas simples y complejas, considera elevar 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 altamente 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 reunido contexto, la llamada al asesor resultante tiene poco contexto y puede desplazar una llamada posterior mejor programada. 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 la tarea. 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 la tarea.

Para forzar una consulta en una solicitud específica en lugar de usar el 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 el pensamiento extendido: la API devuelve un 400 invalid_request_error si habilitas ambos.



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 estándar ping de SSE emitidos aproximadamente cada 30 segundos. Las llamadas cortas al asesor pueden 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 reflejando 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": 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-8",
        "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.

Las reglas de agregación difieren según el campo. El output_tokens de nivel superior es la suma de todas las iteraciones del ejecutor. Los input_tokens y cache_read_input_tokens de nivel superior reflejan solo la primera iteración del ejecutor. Las entradas de las iteraciones posteriores del ejecutor no se vuelven a sumar 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 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 la 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 extraen 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 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 interrupción cache_control colocado después de él en un turno posterior 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 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 prompts para la propia transcripción del asesor a través de llamadas dentro de la misma conversación:

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-8",
        "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 y posteriores iteraciones advisor_message.

Cuándo habilitarlo: La escritura en caché cuesta más de lo que ahorran las lecturas cuando el asesor es llamado dos o menos veces por conversación. El almacenamiento en caché alcanza el punto de equilibrio en aproximadamente 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 para toda la conversación. Activarlo y desactivarlo 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. 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-4-8",
    },
    {
        "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 codificación y de agente

La herramienta de asesor viene con 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 codificación y de agente, 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 pendientes), 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 codificación

Sin dirección en la indicación del sistema, el ejecutor tiende a llamar poco al asesor en algunos dominios, particularmente en tareas de codificación. Para tareas de codificación donde quieres un momento de llamada al asesor consistente y alrededor de dos a tres llamadas por cada tarea, antepón los siguientes bloques a tu indicación del sistema del 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 (colócalo 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 codificació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 codificación, donde una consulta temprana al asesor se paga a sí misma de manera confiable. En un benchmark interno de codificación, una variante cercana del siguiente bloque (la excepción de solo lectura en la regla Hard 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 codificación o de 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 codificació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 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 Hard 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 el asesor en tareas donde una consulta habría ayudado. No lo agregues como predeterminado.



Recortar la longitud de la salida del asesor

La salida del asesor es el mayor impulsor de costos 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 antepuesta programáticamente por tu framework de agente antes de enviar la solicitud. El límite es una restricción suave. El asesor ocasionalmente lo excede, así que pide aproximadamente el 80 por ciento de tu tope real.

Combina este enfoque con la orientación sobre el momento en Indicación del sistema sugerida para tareas de codificación (o el bloque alternativo de Haiku si lo sustituiste) para obtener 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 propio límite de salida 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 le pasa al asesor su presupuesto de tokens restante, por lo que el asesor da forma a su respuesta para que se ajuste.

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 un 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 entre todas las configuraciones estuvieron dentro del ruido con este tamaño de muestra. Valida con 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 línea base universal para la salida del asesor.

Cuando el asesor alcanza el límite, el bloque de resultado lleva stop_reason: "max_tokens". La API también agrega [Advisor output truncated at max_tokens=2048.] (indicando 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 elevar 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"
  }
}

Verifica 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 por costo o latencia. Usa el enfoque basado en prompts (o ambos juntos) cuando quieras sesgar hacia la brevedad sin arriesgar un corte a mitad de pensamiento.



Combinación con configuraciones de esfuerzo

Para tareas de codificación, combinar un ejecutor Sonnet con esfuerzo medio con un asesor Opus logra una inteligencia comparable a Sonnet con esfuerzo predeterminado, a menor costo. Para máxima inteligencia, mantén el ejecutor en 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 y elimina todos los bloques advisor_tool_result de tu historial de mensajes para evitar un 400 invalid_request_error (consulta la nota en Conversaciones de múltiples turnos).
• Habilita caching solo para conversaciones donde esperes tres o más llamadas al asesor.



Próximos pasos