Incidentes con agentes IA: runbooks de recuperación que funcionan
Actualizado: 2026-05-03
Tras año y medio con agentes en producción, lo que distingue a una operación seria no es la sofisticación del modelo, es la capacidad de contener incidentes en minutos en lugar de horas. Los agentes rompen de formas inesperadas, y la respuesta maduró más despacio que la tecnología.
Este runbook recoge el patrón que funciona: la secuencia de acciones que los equipos experimentados ejecutan cuando salta la alarma, en el orden que más reduce daño.
Puntos clave
- La clasificación de severidad en los primeros dos minutos determina la respuesta: SEV-1 y SEV-2 disparan paging inmediato; SEV-3 y SEV-4 no.
- El impulso natural es mirar logs primero. El patrón correcto es aislar primero, entender después.
- Si el agente tiene memoria persistente o vector store, el rollback del código no basta: hay que purgar la ventana sospechosa.
- Un comunicado honesto que admite «hubo comportamiento inesperado, estamos investigando» envejece mejor que una narrativa que se desmonta.
- Un incidente que no entra en la batería de evaluaciones como prueba de regresión no se ha cerrado; solo se ha enmascarado.
Clasificación por severidad en los primeros dos minutos
Una taxonomía clara evita sobrerreacción y subestimación:
- SEV-1: exposición de datos personales o acciones no autorizadas con consecuencias externas (pagos, emails enviados, registros alterados). Paging inmediato, respuesta 24×7.
- SEV-2: degradación de calidad que afecta a todos los usuarios sin exposición de datos. Paging inmediato, respuesta 24×7.
- SEV-3: regresiones acotadas a una categoría de entrada. Se atiende en horario laboral.
- SEV-4: deriva lenta detectada por métricas sin impacto visible en usuario. Entra en backlog con SLA semanal.
Esta clasificación no es burocracia; es la diferencia entre despertar al equipo a las 3 AM por algo que puede esperar al lunes y no despertar a nadie cuando algo crítico está pasando.
Aislar antes de investigar
El impulso natural es mirar logs. El patrón correcto es aislar primero, entender después.
Para SEV-1 y SEV-2, la primera acción es retirar la versión actual y volver a la anterior estable. El rollback no cierra el incidente pero lo congela: el sistema deja de producir daño mientras el equipo analiza.
Si el agente tiene memoria persistente o vector store, el rollback del código no basta. Hay que purgar memoria para la ventana sospechosa. Herramientas como LangSmith[1] y Braintrust[2] permiten marcar trazas como tóxicas. Si no, la opción nuclear es vaciar memoria y aceptar que el agente «olvida» las últimas horas.
Comunicación al usuario sin inventar
Mensajería en capas que funciona:
- Banner en el producto: indica servicio degradado con ETA estimado.
- Notificación específica: los usuarios directamente afectados reciben comunicación individual.
- Canal interno: stakeholders (legal, soporte, comercial) ven la situación en el canal de incidentes en tiempo real.
Lo que no se hace:
- Prometer detalles técnicos antes de tenerlos.
- Atribuir el fallo al proveedor del modelo sin evidencia.
- Minimizar el alcance.
Un comunicado honesto que admite «hubo comportamiento inesperado, estamos investigando» siempre envejece mejor que una narrativa que se desmonta.
Análisis en frío: la traza es todo
Con el agente aislado, empieza el análisis. La herramienta imprescindible es la traza completa:
- Entrada del usuario.
- Contenido recuperado (RAG, herramientas).
- Llamadas a herramientas con sus resultados.
- Estado interno del agente.
- Respuesta final.
Equipos sin este nivel pasan horas especulando; equipos que lo tienen reproducen el fallo en minutos.
La práctica: codificar cada traza con hash estable y archivarla con retención mínima de 30 días. Cuando se reporta una anomalía, se puede buscar casos similares sin reinventar el trabajo.
Mitigación permanente: el caso entra como regresión
Una vez identificado el modo de fallo, la tentación es «arreglar y seguir». El paso que distingue madurez es escribir el caso como prueba de regresión antes de desplegar el fix.
Si el incidente no entra en la batería de evaluaciones, no se ha cerrado; solo se ha enmascarado hasta la próxima vez.
El fix se valida contra la prueba. Si pasa, se promociona. Si no, se itera. Este circuito obliga a entender el fallo realmente.
Post-mortem accionable sin culpables
Dentro de 48 horas del cierre se escribe el post-mortem. Formato:
- Línea de tiempo minuto a minuto.
- Modo de fallo en una frase.
- Causa raíz (o «pendiente» explícitamente, si aún no está claro).
- Acciones correctivas con responsable y fecha.
- Acciones preventivas para evitar recurrencia.
Lo que no se hace: atribuir a personas, omitir aspectos incómodos, cerrar sin fecha de seguimiento.
Un post-mortem bien hecho a los seis meses es un activo; uno mal hecho es un documento que nadie revisita.
Conclusión
Operar agentes en producción es operación, en el sentido clásico de SRE: métricas, runbooks, post-mortems, mejora continua. La diferencia con servicios tradicionales es que la superficie de fallo es más amplia y más impredecible, lo que hace la disciplina operativa más importante, no menos. Los equipos que interiorizan esto duermen tranquilos.
