Claude Agent SDK Tutorial 2026: El Loop de Producción que Claude Code Ya Ejecuta, Ahora Como Librería TypeScript

Todos Esperáis un Modelo Más Listo para que los Agentes Sean Fiables. El Loop Ya Está Aquí

La industria se ha dividido en dos campamentos.

Uno dice: esperad al siguiente modelo, será más listo y los agentes arreglarán solos sus bugs. El otro dice: elegid el framework de grafos más popular y construid vuestro propio state machine.

Los dos se equivocan.

Mientras tanto, Anthropic ya ejecuta en producción el loop exacto que hace fiables a sus agentes. Lo llamáis Claude Code. Es el CLI que revisa código, edita ficheros y corre tests dentro de miles de repositorios todos los días.

*Ese mismo loop, el loop turn-based de producción, se os entrega como librería TypeScript. * Se llama Claude Agent SDK. Y el loop, no el modelo, es donde se gana la fiabilidad.

El SDK viene de la documentación pública de Anthropic. Puso a prueba su funcionamiento con el patrón que voy a darte aquí. Sin números inventados: lo que importa es la arquitectura, y la arquitectura es la historia.

El Problema: Estáis Reimplementando el Loop que Ya Está Resuelto

La conversación típica de equipo al construir un agente suena así:

"Necesitamos gestionar el contexto para que no se desborde la ventana."

"Tenemos que añadir reintentos y recuperación de errores."

"¿Y el prompt caching?"

"Hay que manejar el presupuesto de tokens."

Ese es el trabajo de reimplementar el loop de agente sobre las llamadas crudas a la API de tool-use. Semanas de ingeniería para resolver problemas que —esto es lo incómodo— ya resolvió Claude Code.

El Claude Agent SDK baja a la librería todo ese andamiaje. La unidad central es Agent, que envuelve un AgentLoop. Ejecutas agent.run() o streamAgentEvents() para consumir la ejecución turno a turno. El loop termina cuando un resultado de tool devuelve 'done' o cuando se alcanza max_turns.

Mientras tanto, en el otro extremo, los frameworks de grafos como LangGraph modelan los agentes como máquinas de estado explícitas: nodos y aristas. Potente para ramificación compleja. Pero te obliga a diseñar el grafo de estado tú mismo. El SDK es opinado: un loop de sesión turn-based con hooks y orquestación opcional.

❌ El enfoque débil: Implementar tu propio while-loop sobre la API cruda de Messages. Funciona en el demo. Se rompe en producción cuando el contexto se desborda, el caching no está optimizado y un error de tool no se recupera.

✅ El enfoque correcto: Usar el loop de producción que el SDK ya trae y dedicar tu primera semana a escribir tools e instrucciones, no a depurar desbordamientos de la ventana de contexto.

La decisión es clara: las tareas lineales (fetch → razonar → actuar → done) mapean de forma natural al loop del SDK. Solo los workflows genuinamente paralelos o con ramificación compleja justifican un framework de grafos. El SDK resuelve un problema; LangGraph resuelve otro. La simplicidad del SDK es una feature, no una deficiencia.

Evidencia: El Loop es el Producto, No el Modelo

El SDK no está atado a un único modelo frontera. El mismo loop puede correr con diferentes opciones de Claude: Opus 4.1, Sonnet 4 y Haiku 4.5, seleccionables por agente vía la opción model.

Eso cambia cómo piensas el sistema.

Cambiar de modelo no rompe el loop. La misma estructura de turnos, el mismo manejo de contexto, el mismo caching. Lo que cambia es la robustez del razonamiento y la latencia.

El loop gestiona internamente lo que la mayoría de equipos reimplementan a mano: construcción dinámica del system prompt (ensamblado en runtime desde tools e instrucciones), compresión del contexto, y caching automático. Ese es el delta entre tu while-loop de 50 líneas y el SDK. Tu loop funciona en el demo; el del SDK funciona en producción.

También es TypeScript-first. El SDK de TypeScript es el camino primario/GA; los bindings de Python llegaron en beta. Si tu equipo vive en Python, tenéis margen: el patrón conceptual es idéntico, pero el soporte primario es TS.

Análisis: Los Hooks son una Apuesta Arquitectónica, No un Detalle

El diseño de personalización del SDK es una declaración de intenciones. En lugar de personalizar haciendo fork de los internos —modelo que se rompe en cada upgrade— tienes un API de hooks de ciclo de vida estable.

AgentHooks expone eventos como onSystemPrompt, onModelPrompt, onTurnStart, onTurnEnd, onAgentUpdate, onToolUse y onStop.

Aquí se aplica el principio de observar antes de hacer fork. No tocas los internos del loop. Añades telemetría, guardrails y personalización de prompts por el punto de extensión sancionado.

Esto importa porque el SDK sigue siendo joven. Se renombró desde Claude Code SDK y la versión churn es real. Si personalizas vía hooks, tus upgrades no se rompen. Si haces fork de los internos, cada release te duele.

Añade hooks para tracing/logging desde el día uno (onToolUse, onTurnStart, onAgentUpdate). Es la diferencia entre entender qué hace tu agente y adivinar.

El Marco del Contrato de Terminación

Hay una decisión que determina si tu agente correrá en bucle infinito gastando tokens o terminará con gracia: el contrato de terminación. Es la regla que define cuándo el loop para.

Aquí está el marco de 5 pasos:

Paso 1: Un agente, un loop. Antes de diseñar multi-agente, pregunta si tu tarea (extracción de datos, generación de código, automatización de API) es un problema de un solo loop. El 90% de los casos reales lo son. Añade sub-agentes solo cuando el loop simple demuestre que no puede expresar el workflow.

Paso 2: Diseña tus tools alrededor del contrato de finalización. Cada tool hace una de dos cosas: devuelve datos para continuar, o señala 'done' para terminar. Define este contrato primero. La terminación ambigua es la causa número uno de loops desbocados.

❌ Una tool que devuelve datos ambiguos sin señal de fin → el modelo rellama sin criterio de parada.

✅ Una tool con { done: true } explícito → el loop termina con determinismo.

Paso 3: Hooks de observabilidad desde el día uno. Cablea onToolUse, onTurnStart y onAgentUpdate antes de optimizar nada. No puedes mejorar lo que no observas.

Paso 4: Acota `max_turns` e instrucciones de parada. Pon límites explícitos al loop. Luego valida la robustez del loop contra múltiples modelos: Sonnet para paths sensibles a coste, Opus para razonamiento duro. Evalúa la robustez del loop, no solo la calidad de la respuesta.

Paso 5: Gradua al Orchestrator solo cuando necesites separación de roles. El Orchestrator es una abstracción de primera clase con sub-agentes corriendo en sesiones aisladas que solo se comunican por mensajes.

Atención a la idea clave: el multi-agente resuelve contaminación de contexto, no solo paralelismo. Cada sub-agente tiene su propia sesión aislada, su propio system prompt y sus propias tools. Intercambian solo mensajes.

Esto evita el fallo clásico: un contexto gigante donde las instrucciones del planner se mezclan con el output del coder. El patrón mapea bien a roles reales (Planner, Researcher, Coder) y se parece más a cómo dividen el trabajo los equipos humanos que un solo loop con un prompt enorme.

Objeción del Lector: "¿No Puedo Hacer el Loop en 50 Líneas?"

Sí. Y el demo funciona.

El problema es que tu while-loop de 50 líneas no hace compresión de contexto, no maneja el caching automático, no tiene contrato de terminación, no recupera errores de tool correctamente y no aísla contexto entre sub-agentes.

Tu equipo gasta la primera semana depurando desbordamientos de la ventana de contexto. Con el SDK, la primera semana va en escribir tools e instrucciones reales. El esfuerzo de ingeniería cambia de sitio.

¿Y el lock-in? La decisión honesta: el SDK corre múltiples modelos de Claude pero está atado a Anthropic. Si necesitas modelos no-Anthropic en el mismo codebase, un framework genérico puede encajar mejor. Si construyes sobre Claude, el loop de producción y el manejo de contexto integrado son el pago.

Pinea versiones. Mantén las personalizaciones a nivel de hooks. Así el churn del SDK recién renombrado no rompe tu arquitectura.

Tutorial Pragmático: Tu Primer Agente en 3 Pasos

Empieza pequeño. Un agente, una tool, un loop.

Empieza barato con Haiku. Si el loop no razona bien, escala al mismo código con Sonnet u Opus. El loop no cambia. El modelo sí. Esa portabilidad es la ventaja competitiva del SDK.

Si ya has usado Claude Code, ya conoces el comportamiento del loop. El aprendizaje no es de conceptos agentic; es la superficie del API de TypeScript y los contratos de tools y hooks.

El Loop es el Motor. El Producto eres Tú

Claude Code es la experiencia CLI terminada. El SDK es el mismo motor expuesto como librería para equipos que construyen tools internas, agentes y automatizaciones.

La próxima vez que alguien diga "esperemos al modelo más listo", recuérdale que el loop de producción ya existe y ya corre en Claude Code. La fiabilidad no está pendiente de un modelo futuro: está en el diseño del loop, y ese diseño ya se os entrega.

El trabajo no es reimplementar el loop. Es escribir mejores tools, mejores instrucciones de parada y mejor telemetría.

El loop es el producto. Y tu producto es lo que construyes encima.

Empieza con un agente, un loop y un contrato de terminación claro. Escala al Orchestrator solo cuando la separación de roles lo exija. Pinéa versiones. Observa con hooks desde el día uno.

Eso es lo que separa un agente que parece que funciona en el demo de un agente que aguanta producción con usuarios reales delante. Comienza con Sonnet barato y una sola tool. Extiende solo cuando el loop lo demuestre.

El SDK no te promete agentes perfectos. Te promete un loop que ya aguanta producción. El resto es tuyo.