Definición corta
El agent loop es el ciclo en el que un modelo recibe una tarea, decide qué herramienta usar, observa el resultado y vuelve a decidir, hasta que puede responder sin pedir más herramientas. El Claude Agent SDK ejecuta el mismo bucle que potencia Claude Code y te permite controlarlo desde Python.
Las cinco fases
- 01
Recibir el prompt
Claude recibe la tarea con el system prompt, las herramientas y el historial. El SDK emite SystemMessage "init".
- 02
Evaluar y responder
Responde con texto, llamadas a herramientas o ambas (AssistantMessage).
- 03
Ejecutar herramientas
El SDK ejecuta y devuelve resultados; los hooks pueden interceptar, modificar o bloquear.
- 04
Repetir
Los pasos 2 y 3 forman un turno; se repite hasta una respuesta sin herramientas.
- 05
Devolver el resultado
ResultMessage con texto, uso de tokens, costo y session_id.
Los mensajes que recibes
| SystemMessage | Eventos de la sesión: init, compact_boundary (se resumió el historial), entre otros. |
| AssistantMessage | Cada respuesta de Claude: texto y/o llamadas a herramientas. |
| UserMessage | Los resultados de las herramientas que vuelven a Claude. |
| StreamEvent | Fragmentos parciales, solo con include_partial_messages. |
| ResultMessage | Cierre: resultado, costo, tokens, turnos y session_id. |
El ResultMessage trae un subtype: success (único con result), error_max_turns, error_max_budget_usd o error_during_execution.
Cómo controlarlo
max_turns
Límite de turnos con herramientas.
Al llegar al límite: error_max_turns
max_budget_usd
Límite de gasto, incluye subagentes.
Al llegar al límite: error_max_budget_usd
effort
Cuánto razona el modelo: low → max (según el modelo).
permission_mode
default · acceptEdits · plan · dontAsk · auto · bypassPermissions
allowed_tools / disallowed_tools
Qué se aprueba sin preguntar y qué se bloquea.
hooks
Interceptar, registrar o bloquear cada llamada.
Orden de evaluación de permisos: hooks → reglas deny → reglas ask → modo de permiso → reglas allow → callback can_use_tool. Para agentes cerrados: allowed_tools + permission_mode="dontAsk".
Del agent loop al loop engineering
El agent loop es el motor. Loop engineering es cómo lo diseñas.
En un proyecto Odoo, diseñar el loop significa decidir cuatro cosas:
Spec
Qué debe construir el agente: modelos, reglas, permisos y criterios de aceptación (CLAUDE.md + spec del módulo).
Herramientas
Qué puede usar: archivos, odoo-bin, la API JSON-2 con un usuario técnico de permisos mínimos.
Verificadores
Cómo sabe que terminó: instalación del módulo, tests TransactionCase, linters.
Límites y revisión
max_turns, presupuesto, hooks y una revisión humana antes de producción.
Fuentes: Cómo funciona el agent loop · Permisos · Referencia Python. Verificado con claude-agent-sdk 0.2.163 (oct. 2026).