El loop de un agente: pensar, actuar, observar
El loop de un agente repite un ciclo hasta terminar: evaluar, pedir una herramienta, recibir el resultado y decidir de nuevo. Cómo se limita.
¿Qué pasa en cada vuelta?
Según la documentación del Agent SDK de Claude Code, cada sesión sigue cinco pasos. Primero, el modelo recibe el prompt junto con las instrucciones del sistema, las definiciones de herramientas y el historial. Segundo, evalúa el estado y responde con texto, con una o más llamadas a herramientas, o con ambas. Tercero, el SDK ejecuta cada herramienta pedida y recoge los resultados; esos resultados vuelven al modelo para la siguiente decisión. Cuarto, los pasos dos y tres se repiten hasta que el modelo produce una respuesta sin llamadas a herramientas. Quinto, el SDK entrega esa respuesta final junto con el texto del resultado, el uso de tokens, el costo y el identificador de la sesión.
Cada vuelta completa se llama turno. Un turno no es un mensaje: puede tener varias llamadas a herramientas. Una pregunta sencilla como “¿qué archivos hay aquí?” puede tomar uno o dos turnos. Una tarea como “refactoriza el módulo de autenticación y actualiza los tests” puede encadenar decenas.
La propia documentación describe el caso “corrige los tests que fallan en auth.ts”. En el turno uno, el agente corre npm test y ve tres fallos. En el dos lee auth.ts y su archivo de tests. En el tres edita auth.ts y vuelve a correr los tests, que ahora pasan. En el turno final responde solo con texto, sin herramientas, y el loop termina. Son cuatro turnos: tres con herramientas y uno final de texto.
En la API de Anthropic, este mismo ciclo se ve así: cuando Claude quiere usar una herramienta responde con stop_reason: "tool_use" y un bloque tool_use. Tu aplicación ejecuta la operación y devuelve un bloque tool_result, y Claude usa ese resultado para responder o para pedir otra herramienta. Más detalle en tool use.
¿Por qué se llama loop?
Porque el resultado de cada acción alimenta la siguiente decisión. Es la misma idea que en la definición de agente: Anthropic describe a los agentes, en esencia, como modelos de lenguaje que usan herramientas en un loop, guiados por la retroalimentación del entorno. El modelo no sigue un guion fijo: observa lo que pasó y ajusta. Por eso el loop es lo que separa a un agente de una cadena de llamadas predefinida.
Una forma simple de pensarlo es en tres verbos: el modelo piensa qué hacer, actúa pidiendo una herramienta y observa el resultado. Esos verbos son una simplificación didáctica, no nombres de pasos del SDK. Lo importante es que la observación entra al contexto y condiciona lo que viene después.
¿Qué consume el loop?
Todo lo que pasa en el loop se acumula en la ventana de contexto: instrucciones, historial, llamadas y resultados de herramientas. El documento del SDK señala que los resultados de herramientas grandes, como un archivo completo o un comando con mucha salida, pueden consumir miles de tokens en una sola vuelta.
El contexto no se reinicia entre turnos: las sesiones largas con muchas llamadas acumulan mucho más contexto que las cortas. Lo que no cambia de un turno a otro (instrucciones del sistema, definiciones de herramientas, CLAUDE.md) se guarda con prompt caching, lo que reduce costo y latencia de esos prefijos repetidos.
Cuando el contexto se acerca al límite, el SDK compacta la conversación automáticamente: resume el historial viejo y conserva los intercambios recientes y las decisiones clave. La compactación reemplaza mensajes antiguos por un resumen, así que instrucciones específicas del inicio pueden no conservarse. Por eso las reglas que deben sobrevivir van en el archivo de instrucciones (CLAUDE.md, ver CLAUDE.md y AGENTS.md), cuyo contenido se vuelve a inyectar en cada petición.
¿Cómo se controla un loop?
Sin límites, el loop corre hasta que el modelo termina por su cuenta. La documentación del SDK lo considera aceptable para tareas bien acotadas, pero advierte que puede alargarse con pedidos abiertos como “mejora este código”, y recomienda poner un presupuesto como valor por defecto en agentes de producción. Los controles habituales son:
| Control | Qué limita |
|---|---|
Máximo de turnos (max_turns) | Cuántas rondas con herramientas puede dar; no cuenta el turno final de solo texto |
Presupuesto en dólares (max_budget_usd) | El gasto estimado al que el loop se detiene |
| Permisos por herramienta | Qué herramientas se aprueban solas, cuáles se bloquean y cuáles piden confirmación |
| Hooks antes de ejecutar | Interceptan, modifican o bloquean una llamada antes de que ocurra |
Esfuerzo de razonamiento (effort) | Cuánto razona el modelo en cada respuesta |
Cuando un permiso o un hook rechaza una llamada, el modelo recibe el rechazo como resultado de la herramienta y suele intentar otro camino o avisar que no pudo continuar. Para aprobaciones diseñadas como experiencia, mira aprobación de acciones y human-in-the-loop.
El tope de presupuesto no es exacto: el SDK compara el gasto después de recibir cada respuesta, así que la respuesta que cruza el límite igual se completa y se cobra. Conviene dejar margen.
El SDK reporta cómo terminó el loop con un subtipo en el resultado final: success, error_max_turns, error_max_budget_usd, error_during_execution (por ejemplo, una petición cancelada) y error_max_structured_output_retries. Solo el caso de éxito trae el texto final. Revisar ese subtipo es parte de diseñar bien la experiencia.
¿Por qué le importa a un diseñador?
Porque el loop define los momentos de la experiencia. Hay un momento de inicio (la persona describe la tarea), uno o varios de progreso (lo que el agente ya hizo), un punto de decisión (aprobar una acción) y un final (el resultado o el motivo por el que se detuvo). Cada uno necesita una pantalla o un mensaje.
Un error común es diseñar solo el final. Si el loop se detiene por límite de turnos y la interfaz dice “error”, la persona no sabe si puede continuar. Un buen diseño distingue “terminó”, “se detuvo por límite” y “falló”.
¿Cuándo NO conviene un loop?
- Cuando los pasos son fijos y conocidos. Un flujo predefinido es más barato y predecible.
- Cuando cada vuelta cuesta más de lo que aporta. Un loop de muchos turnos sobre una tarea trivial desperdicia dinero.
- Cuando no hay forma de detenerlo a tiempo. Sin límites ni puntos de aprobación, un error se repite.
Anthropic recomienda empezar con la solución más simple y agregar complejidad solo cuando mejora el resultado.
Ejemplo
Ejemplo ilustrativo: un agente recibe la tarea de corregir un botón deshabilitado en un formulario. En el turno uno busca el componente. En el dos lee el archivo. En el tres propone el cambio, y el sistema lo bloquea porque el hook de la carpeta de componentes exige aprobación. El agente recibe el rechazo como resultado, explica el cambio propuesto y se detiene. La persona aprueba desde la pantalla de revisión y el agente vuelve a correr el loop con permiso para editar ese archivo.
Errores comunes
- Confundir un turno con un mensaje. Un turno puede contener varias herramientas.
- Dejar un loop sin límite de turnos ni de presupuesto en tareas abiertas.
- Diseñar solo el estado final y no los estados de progreso.
- Creer que el modelo recuerda todo el loop. Solo ve lo que sigue en el contexto.
- Confiar en que la compactación conserva las instrucciones importantes.