Claude Opus 5 en tu agente: controla effort y costo con el Agent SDK

Hoy, 24 de julio de 2026, Anthropic lanzó Claude Opus 5. Según el anuncio, es un modelo que "se acerca a la inteligencia de frontera de Claude Fable 5 a la mitad del precio", y ya está disponible en la API con el identificador claude-opus-5.

Si construyes agentes, lo más útil del anuncio no es un benchmark en particular, sino cómo se presentan los resultados: las gráficas de rendimiento muestran cómo cambia según el nivel de effort, la opción con la que eliges entre más inteligencia o menos tokens. En este post vemos qué significa eso para tu agent loop y cómo medirlo con el Claude Agent SDK.

Lo que trae Opus 5 para quien programa agentes

Del anuncio oficial, lo relevante para desarrolladores:

• Precio: US$ 5 por millón de tokens de entrada y US$ 25 por millón de salida, el mismo que Opus 4.8.
• Effort como perilla principal: Anthropic compara a Opus 5 en los niveles high, xhigh y max, y explica que el effort sirve para "optimizar la inteligencia o ahorrar tokens para obtener resultados más rápidos y baratos".
• Más verificación: según Anthropic, Opus 5 es "mucho más fuerte verificando su trabajo e iterando con cuidado hasta lograrlo".
• Fast mode: corre unas 2,5 veces más rápido, al doble del precio base.
• Dos novedades en beta en la plataforma: cambiar las herramientas disponibles a mitad de una conversación sin invalidar el caché del prompt, y fallbacks automáticos en la API cuando un clasificador de seguridad marca una solicitud.
• En Claude Code, las solicitudes marcadas por esos clasificadores pasan a Opus 4.8 por defecto.

Para tener contexto: el 30 de junio salió Claude Sonnet 5, a un precio introductorio de US$ 2 / US$ 10 por millón de tokens. Hoy tienes dos modelos nuevos y varios niveles de effort: ya no basta con "usar el mejor modelo".

Effort en el Claude Agent SDK

En el SDK de Python, ClaudeAgentOptions tiene el campo effort, que acepta "low", "medium", "high", "xhigh" y "max". Lo comprobamos en la versión 0.2.126, publicada el 22 de julio. Según su CHANGELOG, esa misma versión agregó dos campos muy útiles en ResultMessage:

• terminal_reason: indica por qué terminó el loop ("completed", "max_turns", "aborted_streaming", "aborted_tools", etc.).
• model_usage: ahora está tipado como dict[str, ModelUsage], con tokens y costo por modelo.

Con eso puedes medir, en lugar de adivinar.

Ejemplo: mide antes de elegir

Este script le pide a Opus 5 que revise un archivo de un módulo Odoo, primero con effort low y luego con high. Solo le damos herramientas de lectura y le ponemos un tope de turnos y de gasto:

import anyio

from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query

TAREA = (
    "Revisa models/garantia.py de este módulo Odoo. "
    "Lista como máximo 3 riesgos concretos, con el número de línea. No edites nada."
)


async def correr(effort: str) -> None:
    opciones = ClaudeAgentOptions(
        model="claude-opus-5",
        effort=effort,
        cwd="focuz_garantia",
        allowed_tools=["Read", "Grep", "Glob"],
        disallowed_tools=["Edit", "Write", "Bash"],
        max_turns=10,
        max_budget_usd=0.50,
    )
    async for mensaje in query(prompt=TAREA, options=opciones):
        if isinstance(mensaje, ResultMessage):
            print(effort, mensaje.terminal_reason, mensaje.num_turns,
                  mensaje.total_cost_usd, mensaje.duration_ms)
            print(list((mensaje.model_usage or {}).keys()))
            print(mensaje.result)


async def main() -> None:
    for effort in ("low", "high"):
        await correr(effort)


anyio.run(main)

Lo ejecutamos con claude-agent-sdk 0.2.126 sobre un módulo de prueba de 22 líneas. Tres observaciones de nuestra corrida (una sola, así que tómalas como ejemplo y no como estadística):

1. Ambos niveles terminaron con terminal_reason="completed" y en 3 turnos. Con high, el agente tardó más del doble y costó algo más. Para tareas cortas de lectura, low puede bastar.
2. model_usage mostró también un modelo Haiku, además de claude-opus-5. Revisa el desglose por modelo antes de atribuirle todo el costo a Opus 5.
3. El tope de gasto se respeta, y se nota. En un intento anterior se superó max_budget_usd y, en esta versión del SDK, query() terminó con una excepción ("Reached maximum budget"). Si automatizas, captura esa excepción y registra el motivo.

Cómo encaja en tu agent loop

El effort es un parámetro de ingeniería del loop, igual que max_turns o las herramientas permitidas. Una regla práctica para empezar:

• Lectura, clasificación y resúmenes: effort bajo, herramientas de solo lectura.
• Cambios de código con pruebas: effort alto. Opus 5 destaca verificando su trabajo, así que dale con qué verificar: un comando de tests, un linter o una base de datos de prueba de Odoo.
• Siempre: max_budget_usd y max_turns como red de seguridad, y terminal_reason en tus logs.

Si tu agente cambia de herramientas según la fase (primero lee y luego edita), sigue de cerca la beta de cambio de herramientas a mitad de conversación: según el anuncio, permite hacerlo sin invalidar el caché del prompt, lo que impacta directamente en el costo de los loops largos.

Ejercicio

1. Elige tres tareas reales de tu equipo: una de lectura, una de refactor y una de corrección de bug en un módulo Odoo.
2. Ejecuta el script con low, medium y high en cada una. Anota terminal_reason, turnos, costo, tiempo y, sobre todo, si el resultado era correcto.
3. Define un effort por defecto para cada tipo de tarea y fíjalo en el código, no en la memoria del equipo.
4. Agrega max_budget_usd a todos tus agentes y maneja la excepción cuando se alcance.

Fuentes: Introducing Claude Opus 5 (Anthropic), Introducing Claude Sonnet 5 (Anthropic), CHANGELOG de claude-agent-sdk-python, claude-agent-sdk 0.2.126 en PyPI.