Cuando tu agente de IA se atasca en un bucle: 4 síntomas y el fix para cada uno

Depurar un agente de IA que repite la misma acción 20 veces es distinto a depurar un bug normal. El código no falla. Los logs se ven bien. El agente simplemente se queda en un pequeño círculo, gastando tokens, mientras tú miras la terminal preguntándote si valdrá la pena esperar un turno más.

Después de ver estos bucles aparecer en Claude Code, en mi propio harness y en agentes que mis amigos me mandan a revisar, encontré que hay 4 patrones que se repiten casi siempre. Ninguno necesita reiniciar la sesión. Cada uno tiene un fix concreto que puedes aplicar en el momento.

Este artículo cubre los 4 patrones, cómo diagnosticarlos en 30 segundos, y qué prompt o config cambiar para cortarlos.

Síntoma 1: la llamada idéntica, N veces

El agente ejecuta la misma tool call, con exactamente los mismos argumentos, una y otra vez. En Claude Code se ve así:

Bash: ls src/
Bash: ls src/
Bash: ls src/

Tres veces seguidas, mismo comando, mismos flags. El output es idéntico porque nada cambió entre llamadas.

Por qué pasa: el modelo no recuerda haber ejecutado esa llamada. O sí la recuerda, pero interpretó el resultado como incompleto y decide “voy a intentarlo de nuevo, quizás salga distinto”. Ninguna de las dos hipótesis va a resolver sola.

Cómo diagnosticarlo: revisas las últimas 5 tool calls en el historial. Si ves ≥2 idénticas seguidas, es este patrón.

El fix: interrumpe el turno y pega este prompt:

“Ya ejecutaste <comando> dos veces con el mismo resultado. Antes de ejecutarlo de nuevo, explica en 2 líneas qué esperas que sea distinto esta vez. Si no puedes explicarlo, propón otra acción.”

El 80% de las veces, el agente responde “no espero nada distinto, era una llamada redundante” y pasa a otro plan. El 20% restante, admite que se olvidó del resultado anterior y ahí ya sabes que necesitas darle el output pegado en el prompt.

Síntoma 2: retry ciego a la causa

El agente ejecuta un comando que falla, y en vez de leer el error, ejecuta el mismo comando otra vez. Después otra. La versión más común:

Bash: npm run test
  → error: Cannot find module 'axios'
Bash: npm run test
  → error: Cannot find module 'axios'
Bash: npm run test
  → error: Cannot find module 'axios'

Por qué pasa: el modelo trata el error como transitorio. En pipelines reales a veces lo son (rate limit, timeout), y el modelo aprendió a reintentar. Cuando la causa es determinística (falta una dependencia), reintentar no ayuda nunca.

Cómo diagnosticarlo: si ves ≥2 tool calls seguidas donde el output empieza con error: o exit code no-cero, es este patrón. Especialmente si el mensaje de error es idéntico byte a byte.

El fix: agrégale al system prompt (o al prompt del turno actual):

“Antes de reintentar un comando que falló, cita la línea exacta del error y clasifícalo: (a) transitorio (rate limit, timeout, red), (b) determinístico (dependencia falta, sintaxis, config). Solo reintenta si es (a).”

Este prompt funciona porque obliga al modelo a leer el error antes de tomar acción. En mi harness lo tengo como hook post-error que se inyecta automáticamente en el próximo turno si detecto exit code no-cero seguido.

Síntoma 3: ping-pong entre 2 herramientas

Dos tool calls que se alternan sin progreso:

Read: file-a.ts
Read: file-b.ts
Read: file-a.ts
Read: file-b.ts

O peor, cuando involucra edición:

Edit: config.json (agrega campo "timeout": 30)
Edit: config.json (quita campo "timeout": 30)
Edit: config.json (agrega campo "timeout": 30)

Por qué pasa: el modelo tiene dos hipótesis y no puede decidir. Cada tool call parece cerrarle una hipótesis, pero al siguiente turno vuelve a abrirla. Es indecisión, no ejecución.

Cómo diagnosticarlo: si detectas patrón ABAB en las últimas 4 tool calls (donde A y B son distintas pero se alternan), es este.

El fix: fuerza plan mode. En Claude Code:

“Detén las llamadas y entra en modo plan. Escribe qué hipótesis A y qué hipótesis B estás evaluando, qué evidencia decidiría entre las dos, y qué única llamada te la daría. Espera aprobación antes de continuar.”

Este patrón es el más costoso en tokens de los 4, porque cada oscilación gasta 2 turnos completos. Cortarlo temprano ahorra mucho. En mi harness pongo un contador ABAB y si llega a 3 oscilaciones, forzo pausa automática. Este mismo patrón lo cubrí desde otro ángulo en 10 hábitos de debug cuando Claude te esconde el bug.

Síntoma 4: contexto ciego (relee sin razón)

El agente lee el mismo archivo múltiples veces en la misma sesión, sin haberlo editado entre lecturas:

Read: src/router.ts (turno 3)
... otros turnos sin edit a router.ts ...
Read: src/router.ts (turno 8)
... otros turnos sin edit ...
Read: src/router.ts (turno 15)

Por qué pasa: la memoria del turno se llenó, y el modelo “olvidó” que ya vio el archivo. Cada vez que necesita referencia, lo vuelve a leer. En sesiones largas es normal 1-2 relecturas por archivo importante; ≥4 es señal de que la ventana de contexto no está siendo usada bien.

Cómo diagnosticarlo: cuenta cuántas veces cada archivo aparece como target de Read en el historial. Si algún archivo pasa de 3 lecturas, es este patrón.

El fix: dos opciones según severidad:

1. Ligero: pégale un resumen manual del archivo en el prompt actual. “Ya leíste router.ts 3 veces. Aquí está el resumen: [3 líneas]. No lo vuelvas a leer en esta sesión salvo que edites.”
2. Fuerte: usa /compact o equivalente para comprimir el historial antes de continuar. Perderás algunos detalles, pero libera espacio para lo que sí importa.

En mi harness escribo hashes de los Read calls y bloqueo la relectura del mismo archivo dentro de una ventana de 10 turnos, forzando al agente a decir en voz alta por qué necesita leerlo de nuevo. En 3 semanas de uso, redujo las relecturas redundantes en un 60% sin que el agente perdiera capacidad.

Tabla resumen

Síntoma	Cómo detectar	Fix rápido
Llamada idéntica ×N	≥2 tool calls idénticas seguidas	”Explica qué esperas distinto”
Retry ciego	≥2 exit-code no-cero con mismo error	”Clasifica el error antes de reintentar”
Ping-pong ABAB	Alternancia sin progreso en últimas 4 calls	Forzar plan mode + evidencia decisora
Contexto ciego	Mismo archivo leído ≥3 veces	Resumen inyectado o /compact

Lo que no funciona (aprendido a la mala)

“Solo reinicia la sesión” — Sí funciona, pero pierdes todo el contexto y el agente probablemente vuelva al mismo bucle 5 turnos después. Reiniciar sin cambiar el prompt es tratar el síntoma, no la causa.

“Subir el modelo a uno más grande” — En mi experiencia, Sonnet 4.5 y Opus 4.7 caen en estos 4 patrones aproximadamente con la misma frecuencia. El tamaño del modelo no arregla bucle; el prompt sí. He visto Opus meterse en ping-pong exactamente igual que Haiku.

“Bajar la temperatura a 0” — Ayuda con el síntoma 1 (llamada idéntica) porque hace más determinístico, pero empeora el síntoma 3 (ping-pong) porque el agente se compromete más fuerte con hipótesis erradas. No es palanca general.

Cierre

Cuando un agente entra en bucle, el reflejo natural es matar el proceso y volver a empezar. Casi nunca es necesario. Los 4 patrones aquí cubren la mayoría de los bucles que verás en Claude Code, Cursor, o cualquier agente basado en tool-calling, y todos se cortan con un prompt de 2-3 líneas si los detectas temprano.

La clave no es evitar que el agente se equivoque — eso es imposible. La clave es notar cuándo empieza a girar en el mismo círculo, y darle una salida antes del quinto turno idéntico.

---

ken imoto · WebRTC & Voice AI engineer · kenimoto.dev