Cómo Depurar un Agente de IA en Producción (Guía de Campo)

Tabla de contenidos

Actualizado junio 2026.

TL;DR: Depurar un agente de IA en producción consiste sobre todo en aislar qué capa falló — prompt, llamada a herramienta, salida del modelo u orquestación. Registro cada paso con un ID de traza, reproduzco las entradas exactas y biseco a partir de ahí. En mis agentes, aproximadamente el 70% de lo que parece un “bug de IA” resulta ser fontanería: un resultado de herramienta malformado, una entrada truncada, una excepción silenciosamente tragada.

Lectura del operador: Ejecuto más de 100 agentes en producción — flujos de reserva para Pickleland, pipelines de contenido, clasificadores de bandeja de entrada. Se rompen como se rompe todo el software, más unas cuantas formas nuevas. Esta es la guía de campo que ojalá hubiera tenido: cómo encontrar la capa que falla sin mirar fijamente un muro de tokens.

Cuando un agente se comporta mal en producción, el instinto es culpar al modelo. “Claude alucinó.” A veces es cierto. Normalmente no. El modelo es una capa en una pila de cinco o seis, y el bug está mucho más a menudo en la capa que escribiste tú que en la que envió Anthropic. Esta publicación es la forma sistemática en que lo encuentro.

Haz cada ejecución trazable antes de depurar nada

No puedes depurar lo que no puedes ver. Lo de mayor apalancamiento que puedes hacer — antes de que aparezca cualquier bug específico — es adjuntar un ID de traza a cada ejecución del agente y registrar cada paso que da.

Un “paso” es cualquier cosa que cruza un límite: el disparador entrante, cada llamada al modelo (con el array completo de mensajes), cada llamada a herramienta (con argumentos), cada resultado de herramienta y la salida final. Regístralos como JSON estructurado indexado por el ID de traza.

function logStep(traceId: string, step: string, payload: unknown) {
  console.log(JSON.stringify({
    traceId,
    step,            // "trigger" | "model_call" | "tool_call" | "tool_result" | "output"
    ts: Date.now(),
    payload,
  }));
}

En Cloudflare Workers los envío a una cola y a una tabla; localmente van a stdout. La regla es absoluta: si un paso no está registrado, no ocurrió en lo que respecta a la depuración. Esto refleja la instrumentación que describo en el stack de agentes que uso — el ID de traza es la columna vertebral de la que cuelga todo lo demás.

Aísla la capa: prompt, herramienta, modelo u orquestación

Una vez que tienes una traza, depurar se convierte en una bisección. Hay cuatro capas y el bug vive en exactamente una de ellas la mayor parte del tiempo.

1. La capa de entrada (el culpable más común)

Extrae el array messages exacto que entró en la llamada al modelo que falló. No una reconstrucción — el payload literal del registro. Luego léelo como lo haría un extraño. La mitad de mis bugs de “el modelo ignoró las instrucciones” en realidad son:

• Un resultado de herramienta que volvió como "[object Object]" porque algo se serializó mal a string.
• Una entrada truncada a media frase porque reventó la ventana de contexto y un corte ingenuo la partió.
• Una variable que se interpoló como undefined y envenenó silenciosamente el prompt.

Si la entrada está mal, el modelo hizo su trabajo a la perfección sobre basura. Arregla la fontanería.

2. La capa de herramientas

Si la entrada se ve limpia, comprueba si una herramienta devolvió un error que el agente trató como éxito. Un clásico: una API devuelve 200 con un cuerpo de { "error": "rate limited" }, tu wrapper de herramienta no comprueba el cuerpo, y el agente actúa con confianza sobre un mensaje de error. Registra los resultados de herramienta en crudo y verifica su forma.

3. La capa del modelo

Solo después de descartar 1 y 2 sospecho del modelo. Incluso entonces, “bug del modelo” normalmente significa “mi prompt es ambiguo.” Toma la entrada exacta que falló, ponla en un script puntual contra el mismo modelo y temperatura, y mira si se reproduce. Si lo hace, el arreglo es trabajo de prompt o una eval más ajustada, no un cambio frenético de modelo.

4. La capa de orquestación

Si un solo paso está bien de forma aislada pero la ejecución multipaso falla, el bug está en el traspaso — estado perdido entre pasos, una condición de carrera, un reintento que volvió a ejecutar una acción no idempotente. Estos son los más desagradables y cubro los patrones en patrones de orquestación multiagente.

Reproduce el no-determinismo en lugar de pelearte con él

Lo que hace que los agentes se sientan indepurables es el no-determinismo: la misma entrada produce salidas diferentes entre ejecuciones. Puedes domarlo.

Primero, fija lo que puedas. Pon temperature: 0 mientras depuras. No hará a Claude totalmente determinista, pero estrecha mucho la varianza para que puedas distinguir un bug real del ruido de muestreo.

Segundo, ejecútalo N veces. Si un fallo se reproduce 1 de cada 20 ejecuciones, repite la entrada exacta 50 veces y captura cada salida. Ahora tienes una muestra, no una anécdota. Un bug que se dispara el 5% de las veces es un bug real — solo necesitas volumen para verlo.

for i in $(seq 1 50); do
  node replay.mjs --trace=abc123 >> runs.jsonl
done
# luego cuenta los fallos
grep -c '"status":"fail"' runs.jsonl

Tercero, compara las ejecuciones que pasan y las que fallan. Con la temperatura fijada y la misma entrada, una diferencia en la salida significa una diferencia en la entrada que aún no has detectado — una marca de tiempo en el prompt, un resultado de herramienta que varía, un documento recuperado que cambió.

Construye un arnés de reproducción para dejar de depurar en producción

Depurar reactivando el agente en vivo es lento y arriesgado — envía correos reales, reserva pistas reales. En su lugar, captura la traza y reprodúcela offline.

El arnés de reproducción carga una traza registrada, reconstruye las entradas exactas de cualquier paso y vuelve a ejecutar solo ese paso contra el modelo. Como registraste el array completo messages, no necesitas el sistema aguas arriba en absoluto. Esto convierte un ida y vuelta de 10 minutos en producción en un bucle local de 2 segundos, y es la mayor aceleración de mi flujo de depuración.

Un buen arnés de reproducción también te deja mutar y reejecutar: cambia una línea del prompt del sistema, reproduce las mismas 50 trazas que fallaron y mira cuántas pasan ahora. Ese es el puente de la depuración a la eval — una vez que tienes un corpus de trazas que fallan, tienes el inicio de un conjunto de regresión.

Vigila las métricas que de verdad predicen las roturas

Algunos fallos nunca lanzan una excepción. El agente se ejecuta, devuelve algo plausible y hace silenciosamente lo incorrecto. Para atrapar esos vigilas métricas de comportamiento, no solo tasas de error:

• Tasa de éxito de llamadas a herramienta por herramienta. Una caída aquí a menudo precede a un fallo visible.
• Validez del esquema de salida — qué % de salidas parsean contra la estructura esperada. Valido cada salida con Zod y alerto cuando la validez baja.
• Longitud del bucle — número medio de pasos por ejecución. Un pico repentino normalmente significa que el agente está atascado reintentando.
• Coste por ejecución — un bucle desbocado aparece como un pico de coste antes de aparecer como una queja. (Cuando el coste importa, vale la pena conocer las matemáticas de Haiku vs Sonnet.)

Sigo estas igual que sigo todo lo demás — mira cómo mido si un agente de IA realmente funciona. La métrica que atrapa un fallo silencioso vale por diez que atrapan los ruidosos.

La lista de triaje de 5 minutos

Cuando un agente se rompe y voy contra reloj, ejecuto esto en orden:

1. Consigue el ID de traza de la ejecución que falló.
2. Lee la entrada exacta del paso que falló. ¿Está bien formada? (Resuelve ~50% de los casos aquí.)
3. Comprueba los resultados de herramienta en esa traza buscando errores disfrazados de éxito.
4. Reproduce el paso offline a temperature: 0. ¿Se reproduce?
5. Si se reproduce, es un problema de prompt/modelo — arregla y reejecuta el corpus de trazas. Si no, es no-determinismo o un bug de estado/orquestación — repítelo 50× para caracterizarlo.

El aislamiento disciplinado le gana al prompting ingenioso siempre. El modelo rara vez es el problema; el sistema a su alrededor normalmente sí lo es.

FAQ

¿Cómo depuro un agente de IA que falla solo a veces?

Captura la entrada exacta de una traza registrada y reprodúcela más de 50 veces a temperatura 0. Los fallos intermitentes son bugs reales con bajas tasas de disparo — el volumen convierte la anécdota en una muestra reproducible que puedes comparar y arreglar.

¿El bug suele estar en el modelo o en mi código?

En mis agentes de producción, aproximadamente el 70% de los aparentes “bugs de IA” son fontanería: resultados de herramienta malformados, entradas truncadas, excepciones tragadas o estado perdido entre pasos. Descarta las capas de entrada y herramienta antes de sospechar del modelo.

¿Cuál es el mínimo de registro que necesito para depurar agentes?

Un ID de traza en cada ejecución, más registros estructurados del disparador, cada llamada al modelo (array completo de mensajes), cada llamada a herramienta y su resultado en crudo, y la salida final. Si un paso no está registrado, no puedes depurarlo.

¿Cómo dejo de depurar contra la producción en vivo?

Construye un arnés de reproducción que cargue una traza registrada y vuelva a ejecutar cualquier paso individual offline usando las entradas capturadas. Convierte un ida y vuelta lento y arriesgado en producción en un bucle local rápido y se convierte en la semilla de tu conjunto de regresión.