Guía paso a paso para implementar el Advisor Tool de Anthropic: calidad Opus, costo Sonnet

El Advisor Tool es un tipo especial de herramienta del API de Anthropic que conecta dos modelos en una sola solicitud: un executor (el modelo principal, como Sonnet) y un advisor (un modelo más potente, como Opus). El executor decide cuándo llamar al advisor; cuando lo hace, Anthropic corre un sub-inference del advisor con el transcript completo de la conversación y devuelve su consejo al executor —sin que tu código haga una llamada adicional.

El patrón es especialmente útil en tareas de largo aliento: agentes de codificación, pipelines de investigación multi-paso o computer use, donde la mayoría de los turnos son mecánicos pero tener un plan excelente al inicio marca la diferencia.

El problema del costo sin configurar

Sin ninguna restricción, el advisor genera entre 4.200 y 5.900 tokens por llamada en tareas de razonamiento complejo —incluyendo thinking interno— facturados a la tarifa de Opus. Eso anula gran parte del ahorro de usar Sonnet como executor. La solución es directa: el parámetro max_tokens a nivel de herramienta.

El ejemplo completo a continuación muestra un agente de codificación que usa Sonnet como executor y Opus como advisor, con max_tokens=2048 activado para controlar el costo del advisor.

import anthropic
import os

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

# Definicion de la herramienta advisor con max_tokens optimizado
ADVISOR_TOOL = {
    "type": "advisor_20260301",
    "name": "advisor",
    "model": "claude-opus-4-8",
    "max_tokens": 2048,  # Reduce output de ~5000 a <800 tokens
    "max_uses": 3,       # Limite por solicitud
}

SYSTEM_PROMPT = """Eres un agente de codificacion experto.
Tienes acceso a una herramienta advisor respaldada por un modelo mas potente.
Llama al advisor ANTES de trabajo sustantivo: antes de escribir codigo,
antes de comprometerte con una arquitectura, antes de declarar que terminaste.
"""

def ejecutar_tarea_codificacion(tarea: str) -> str:
    """Ejecuta una tarea de codificacion con el patron Executor+Advisor."""
    messages = [
        {"role": "user", "content": tarea}
    ]

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

    # Extraer el texto final del response
    resultado = ""
    for bloque in response.content:
        if bloque.type == "text":
            resultado += bloque.text

    return resultado

# Uso
tarea = "Implementa un rate limiter en Python con el algoritmo token bucket."
respuesta = ejecutar_tarea_codificacion(tarea)
print(respuesta)

Qué ocurre internamente

Cuando el executor invoca el advisor, Anthropic corre una inferencia separada del advisor pasándole el transcript completo. El advisor no tiene herramientas propias y sus bloques de thinking se descartan antes de retornar su consejo. Todo ocurre dentro de una sola llamada a /v1/messages: no hay round-trips adicionales desde tu código.

Un agente de codificación real necesita mantener contexto entre turnos. El punto crítico: debes incluir los bloques advisor_tool_result en el historial de mensajes que envías al API en cada turno. Si omites el advisor de tools en un turno posterior mientras el historial tiene esos bloques, recibirás un error 400.

import anthropic
import os

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

ADVISOR_TOOL = {
    "type": "advisor_20260301",
    "name": "advisor",
    "model": "claude-opus-4-8",
    "max_tokens": 2048,
    "max_uses": 3,
}

def agente_multi_turno(mensajes_iniciales: list, max_turnos: int = 10):
    """Agente con soporte multi-turno y conteo de llamadas al advisor."""
    messages = list(mensajes_iniciales)
    llamadas_advisor = 0
    LIMITE_ADVISOR_GLOBAL = 6  # cap de conversacion

    for turno in range(max_turnos):
        # Determinar si el advisor sigue activo
        tools_activos = [ADVISOR_TOOL] if llamadas_advisor < LIMITE_ADVISOR_GLOBAL else []

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

        # Incluir el response completo, con advisor_tool_result
        messages.append({"role": "assistant", "content": response.content})

        # Contar llamadas al advisor
        for bloque in response.content:
            if hasattr(bloque, 'type') and bloque.type == "server_tool_use" and bloque.name == "advisor":
                llamadas_advisor += 1

        if response.stop_reason == "end_turn":
            break

    return messages, llamadas_advisor

# Ejemplo de uso
conversacion_inicial = [
    {"role": "user", "content": "Crea una clase Python para manejar reintentos con backoff exponencial."}
]
mensajes, total_advisor = agente_multi_turno(conversacion_inicial)
print(f"Llamadas al advisor en esta conversacion: {total_advisor}")

Cuándo habilitar caché del advisor

El advisor soporta un parámetro caching opcional: actívalo solo si esperas 3 o más llamadas al advisor en una misma conversación. Con dos o menos llamadas, el costo de escritura supera el ahorro de lectura.

El siguiente ejemplo integra todo lo anterior en un agente de revisión de código productivo: recibe un archivo Python, lo analiza con Sonnet y consulta a Opus en los puntos críticos de decisión.

import anthropic
import os

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

SYSTEM_AGENTE_REVISION = """Eres un revisor de codigo experto en Python.
Revisa el codigo del usuario identificando:
1. Bugs concretos (con numero de linea)
2. Problemas de seguridad (inyeccion, secretos expuestos)
3. Problemas de rendimiento criticos
4. Sugerencias de refactor si hay duplicacion obvia

ANTES de emitir tu revision final, llama al advisor para validar
que no omitiste ningun vector de seguridad importante.
"""

ADVISOR_CONFIG = {
    "type": "advisor_20260301",
    "name": "advisor",
    "model": "claude-opus-4-8",
    "max_tokens": 2048,
    "max_uses": 2,
}

def revisar_codigo(codigo_fuente: str) -> dict:
    """Revisa codigo Python con el patron Executor+Advisor."""
    # Instruccion al advisor embebida en el mensaje
    nudge_advisor = (
        "(Advisor: mantén el analisis en menos de 100 palabras. "
        "Prioriza vectores de seguridad que el revisor pudo omitir.)"
    )

    messages = [{
        "role": "user",
        "content": nudge_advisor + "\n\nRevisa este codigo:\n\n" + codigo_fuente
    }]

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

    # Separar texto final y metadata de uso
    texto_revision = ""
    for bloque in response.content:
        if hasattr(bloque, 'text'):
            texto_revision += bloque.text

    # Extraer tokens del advisor desde iterations
    tokens_advisor = 0
    for it in response.usage.iterations:
        if it.get("type") == "advisor_message":
            tokens_advisor += it.get("output_tokens", 0)

    return {
        "revision": texto_revision,
        "tokens_executor": response.usage.output_tokens,
        "tokens_advisor": tokens_advisor,
    }

# Codigo de ejemplo a revisar
codigo_a_revisar = """
import sqlite3

def get_user(username):
    conn = sqlite3.connect('usuarios.db')
    query = "SELECT * FROM users WHERE username = '" + username + "'"
    return conn.execute(query).fetchone()
"""

resultado = revisar_codigo(codigo_a_revisar)
print("=== REVISION ===")
print(resultado["revision"])
print(f"\nTokens executor: {resultado['tokens_executor']}")
print(f"Tokens advisor (Opus): {resultado['tokens_advisor']}")

Este ejemplo muestra la vulnerabilidad de inyección SQL clásica: el agente la detectará y, con la llamada al advisor, Opus validará que no haya otros vectores de seguridad omitidos. Los tokens del advisor quedan separados en usage.iterations para que puedas construir tu propio tracking de costos.