Claude Opus 5.5 ejecuta tareas de 18 horas: cómo diseñar APIs para agentes de larga duración

Cada timeout en tu stack asume un cliente que eventualmente se rinde. Se cierra una pestaña del navegador. Un trabajo de CI alcanza su tiempo límite. Un humano se aleja. Los valores predeterminados que heredaste de tu balanceador de carga, tu puerta de enlace y tu biblioteca HTTP estaban ajustados para un llamador cuya paciencia se mide en segundos.

Anthropic dice que Claude Opus 5.5 permanece en la tarea 18 horas o más.

Eso no es una afirmación sobre una única solicitud HTTP muy larga. Es una afirmación sobre la coherencia: el modelo trabaja en un único objetivo durante una sesión mucho más larga que cualquier cosa que tu API haya servido. Cuando una de esas sesiones apunta a tus endpoints, sobrevive a tus tokens de acceso, tu ventana de idempotencia, tu ciclo de despliegue y la mayor parte de tus presupuestos de reintentos. Y, a diferencia de un humano, no se dará cuenta de que debería detenerse.

Este es un problema de diseño de API, no un problema del modelo. Esto es lo que se rompe y lo que hay que cambiar.

Lo que Anthropic publicó realmente

Las cifras del proveedor para el nuevo modelo, para que discutamos desde la misma hoja:

Benchmarks del mismo anuncio: Terminal-Bench 4.0 66,4 %, OSWorld 2.0 81,8 %, AutomationBench 40,0 %, FrontierCode v1.1 54,4 %, CursorBench 4.0 57,8 %, Humanity’s Last Exam 67,7 % con herramientas, Chartography 89,0 %, GDPval-AA v2.1 con 1846 Elo y un 85 % menos de intentos exitosos de elusión de límites.

La cifra de 18 horas es la que aterriza en tu infraestructura. Las puntuaciones de los benchmarks cambian qué modelo eliges. La duración sostenida cambia lo que tu API tiene que sobrevivir.

Seis suposiciones que dejan de sostenerse

Cada una tiene una solución aburrida, bien entendida y normalmente omitida porque nada obligaba a abordarla. Algo la está obligando ahora.

Devuelve handles, no trabajo

El cambio de mayor valor: cualquier operación que pueda superar unos segundos devuelve inmediatamente un recurso de job en lugar de mantener la conexión.

POST /v1/reports HTTP/1.1
Host: api.example.com
Idempotency-Key: 01J9Z4KCQ7M3XN2YB8V6H0
Content-Type: application/json

{"dataset": "orders_2026_q3", "format": "parquet"}

HTTP/1.1 202 Accepted
Location: /v1/jobs/job_01J9Z4KD
Retry-After: 5
Content-Type: application/json

{
  "id": "job_01J9Z4KD",
  "status": "queued",
  "created_at": "2026-09-23T04:12:09Z",
  "api_version": "2026-08-01"
}

Luego, el recurso de estado lleva todo lo que el agente necesita para decidir qué hacer a continuación:

{
  "id": "job_01J9Z4KD",
  "status": "running",
  "progress": { "completed": 41200, "total": 180000, "unit": "rows" },
  "started_at": "2026-09-23T04:12:11Z",
  "updated_at": "2026-09-23T05:47:02Z",
  "expires_at": "2026-09-24T04:12:09Z",
  "retry_after_seconds": 15,
  "result_url": null,
  "error": null
}

Cuatro campos hacen el trabajo real. progress con un unit explícito permite al modelo razonar si esperar es racional en lugar de adivinar a partir del tiempo transcurrido. retry_after_seconds pone la cadencia de sondeo bajo control del servidor, lo cual importa cuando el cliente no tiene instinto de cortesía. expires_at le dice al agente cuánto tiempo es válido el handle, para que pueda hacer checkpoint antes de perderlo. api_version fija el job al contrato bajo el que se creó, lo único que se interpone entre tu despliegue de las 3 p. m. y una ejecución que comenzó al amanecer.

Los webhooks son la mejor señal de finalización cuando puedes ofrecerlos, y el sondeo es el respaldo cuando el agente no tiene una dirección a la que llamar. Nuestro recorrido sobre sondeo frente a webhooks para llamadas de agentes de larga duración cubre el compromiso. Lo que cambia en un horizonte de 18 horas es que necesitas ambos, porque un webhook entregado en la hora tres a un agente que desde entonces ha compactado su contexto llega a un cliente que ya no recuerda haberlo pedido.

Haz que la idempotencia sobreviva a la tarea

La mayoría de las implementaciones de idempotencia almacenan la clave durante un día o menos, y eso siempre fue suficiente. Un agente que reintenta una llamada de aprovisionamiento fallida al final de una ejecución larga cae fuera de la ventana de deduplicación original, y en ese punto tu API hace el trabajo dos veces tan campante.

Tres cambios cuestan muy poco:

1. Publica la ventana. Devuelve la expiración en la respuesta para que el cliente pueda razonar sobre ella, en lugar de documentarla una vez y esperar que funcione.
2. Di cuándo repetiste. Una cabecera Idempotency-Replayed: true convierte un no-op silencioso en algo sobre lo que el agente puede actuar.
3. Rechaza las discrepancias de forma ruidosa. La misma clave con un cuerpo diferente significa que el cliente ha perdido el rastro de su propio estado. Devuelve 409 con la huella de la solicitud original en lugar de servir un resultado obsoleto.

HTTP/1.1 200 OK
Idempotency-Replayed: true
Idempotency-Expires: 2026-09-24T04:12:09Z

Cuando la operación es genuinamente peligrosa, prefiere una clave natural proporcionada por el cliente en lugar de una opaca. Un transfer_id derivado del hecho de negocio sobrevive a la compactación de memoria de un agente de una forma en que un UUID aleatorio que generó hace once horas no lo hace. Nuestro manual sobre idempotencia en agentes tiene los modos de fallo.

Asume que la credencial expira a mitad de la tarea

Una ejecución de 18 horas sobrevive a casi todos los tokens de acceso de corta duración. Esa es la postura de seguridad correcta, pero solo si tu API hace legible la distinción.

Devuelve 401 con un desafío WWW-Authenticate: Bearer error="invalid_token" cuando el token ha expirado, y reserva 403 para un principal que carece de permiso. Los agentes tratan estos casos de forma muy diferente: uno significa refrescar y continuar, el otro significa detenerse e informar. Colapsarlos en un fallo genérico es cómo consigues un agente que quema cuatro horas reintentando algo que nunca se le permitirá hacer.

Vincula los jobs al principal, no a la instancia del token. Un job iniciado con un token que desde entonces ha rotado debe seguir siendo legible por la misma identidad, o cada refresco de credenciales deja huérfano el trabajo en curso.

Trata un stream como reanudable, no como una conexión

Los streams largos se caen. Asúmelo y diseña la reconexión en lugar de la conexión.

Para los eventos enviados por el servidor, eso significa dar a cada evento un id monotónico, respetar la cabecera de solicitud Last-Event-ID al reconectar y emitir un comentario de keepalive en un intervalo más corto que el timeout de inactividad más ajustado entre tú y el cliente. Nombra las claves de configuración en tu propia documentación, porque el lector tiene que ir a cambiarlas: idle_timeout.timeout_seconds en un balanceador de carga de AWS, proxy_read_timeout en nginx, timeout en un servicio de Cloud Run. El punto no es un valor específico. Es que el valor exista, sea más corto que el trabajo y que nadie lo haya mirado desde que se creó el servicio. Nuestra guía de streaming con SSE cubre el formato de transmisión; la parte específica para agentes es la reanudación.

Las cabeceras de límite de tasa también importan más de lo habitual. RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset permiten a un modelo regular su ritmo a lo largo de una ejecución larga, y un Retry-After en cada 429 elimina las conjeturas. Un agente al que se le da un número lo respeta. Un agente al que no se le da nada inventa un backoff, y su invención no será mejor que la tuya.

El lado del costo es una decisión de diseño

Mira de nuevo la fila de precios. La entrada cuesta $4 por millón de tokens y una lectura en caché cuesta $0.20, una diferencia de veinte veces en la parte del payload que un agente reenvía con más frecuencia, y en una ventana de contexto de 1M los números absolutos se vuelven grandes rápido. Las escrituras en caché a $5 significan que la primera pasada cuesta un poco más que una lectura simple, así que el almacenamiento en caché compensa solo cuando el prefijo se reutiliza de verdad. A lo largo de dieciocho horas, lo hace.

Aquí es donde la superficie de tu API se convierte en un insumo de costo en la factura de otra persona. Si tu especificación OpenAPI, tus definiciones de herramientas o tu catálogo de errores están al principio del contexto de un agente, la estabilidad de bytes es una característica. Serializa de forma determinista. Mantén estable el orden de las claves. Versiona las definiciones de herramientas en lugar de editarlas en el lugar. Una reordenación cosmética de tu especificación invalida un prefijo en caché y vuelve a facturar todo el conjunto a precio de entrada completo, y el cliente que paga por eso nunca sabrá que fuiste tú.

La escala no es hipotética. OpenAI reveló que su investigador mediano gasta más de $600 al día en agentes de programación, con el percentil 90 por encima de $7,000 al día. Eso es lo que cuesta el trabajo agéntico continuo cuando nadie optimiza para ello, y parte de por qué tres lanzamientos de modelos en dos días lideraron todos con el costo por tarea en lugar del costo por token. La aritmética de cuándo se amortiza el almacenamiento en caché está en nuestro desglose del costo de caché de Opus 5.5.

Prueba el camino largo antes de que lo encuentre un agente

Nada de esto se verifica haciendo clic en enviar una vez y leyendo un 200. Los fallos viven en la hora nueve.

En Apidog, modela todo el ciclo de vida como un escenario de prueba en lugar de una sola solicitud: verifica que la llamada de creación devuelva 202 con un Location y un Retry-After, recorre en bucle el endpoint de estado hasta un estado terminal y verifica que progress.completed nunca retroceda. Esa última aserción atrapa más errores reales que cualquier comprobación de código de estado, porque el progreso no monotónico es lo que convence a un agente de empezar de nuevo.

Luego rómpelo deliberadamente con un servidor mock. Sirve un job que permanezca en running durante veinte sondeos y luego falle. Sirve un 429 sin Retry-After y observa qué hace tu cliente. Sirve un 401 a mitad de camino para confirmar que la ruta de refresco funciona mientras un job está en curso. Las pruebas SSE de Apidog mantienen abierta una conexión de streaming y verifican eventos individuales, la única forma práctica de comprobar que la reanudación con Last-Event-ID devuelve el cursor correcto en lugar de reproducir desde cero. Conecta el escenario a CI para que un cambio futuro de timeout haga fallar una prueba en lugar de la ejecución nocturna de un cliente. Apidog es gratis para empezar, y el escenario que construyes una vez cubre todos los endpoints de larga duración que tengas.

La lista corta

• Las operaciones largas devuelven 202 con un handle de job, nunca una conexión retenida
• Las respuestas de estado llevan progreso, una unidad, un intervalo de sondeo elegido por el servidor y una expiración
• Los jobs fijan la versión de API con la que se crearon
• Las ventanas de idempotencia se publican, las repeticiones se etiquetan, la reutilización de clave con un cuerpo cambiado devuelve 409
• 401 para tokens expirados se distingue de 403 para tokens denegados
• Los jobs pertenecen a un principal, no a una instancia de token
• Los streams llevan ids de evento, respetan Last-Event-ID y envían keepalives dentro del timeout de inactividad más corto de la ruta
• Cada 429 lleva Retry-After, y las cabeceras de límite de tasa siempre están presentes
• La especificación y las definiciones de herramientas se serializan de forma estable en bytes para que las cachés del lado del cliente se mantengan calientes

Opus 5.5 no inventó ninguno de estos requisitos. Eliminó la última excusa para omitirlos, porque el cliente que antes se rendía antes de encontrar las grietas ahora las atraviesa directamente durante dieciocho horas.