Cada sistema con agentes IA que entregamos lleva un runbook. Seis páginas, sin diagramas más allá de un flowchart, escrito en el tono de un documento SRE de la era 2010. Es aburrido a propósito.
Hemos llegado a ver el runbook como un entregable principal, no como papeleo. Si no se puede escribir un runbook para el agente que acabamos de construir, ese agente no está listo para producción. Aquí está el porqué, y qué contiene en realidad.
Por qué el runbook es la especificación
Un runbook le obliga a responder a seis preguntas que, de otro modo, dejaría abiertas:
- ¿Cómo es "funcionando correctamente"? Sin sensaciones — una verificación concreta. "Latencia p95 por debajo de X, tasa de aprobación de evals por encima de Y, coste por petición entre A y B."
- ¿Cómo es "roto"? Síntomas específicos con umbrales, no solo "los usuarios se quejan".
- ¿A quién se le pagina cuando se rompe? Un nombre, una cadena de escalado, un número de teléfono.
- ¿Cuál es el playbook para cada fallo conocido? Paso a paso, incluyendo "no hacer nada durante 5 minutos" si esa es la respuesta.
- ¿Cuándo hacemos rollback? No "si se pone mal". Una condición específica que dispara el rollback sin requerir una reunión.
- ¿Qué estado sobrevive y cuál no? Si hacemos rollback al agente, ¿qué pasa con los workflows en vuelo, las terminaciones parciales y las peticiones en cola?
Si el equipo no puede responder a las seis por escrito, el agente aún no es production-grade. El runbook no es documentación de lo que ya es cierto — escribirlo es lo que lo hace cierto.
La estructura
Cada runbook que entregamos tiene las mismas seis secciones:
1. Resumen del servicio
Un párrafo. Qué hace este agente, de qué depende, qué depende de él. Se actualiza cada vez que cambian las responsabilidades del agente.
2. Salud
La URL del dashboard. Las cuatro o cinco métricas que definen "saludable". Umbrales para verde / amarillo / rojo. No más de cinco — si tiene diez, nadie las vigila.
3. Fallos comunes
Cada modo de fallo recibe una sección:
- Síntoma — lo que ve un operador en el dashboard.
- Diagnóstico — cómo confirmar que esta es la causa real y no algo que se le parece.
- Mitigación — los pasos a dar, en orden, con los resultados esperados.
- Resolución — cómo se ve el éxito.
Apuntamos a documentar de 6 a 10 modos de fallo. La mayoría de los operadores solo necesitarán tres de ellos, pero la cola larga es la que le salva a las 3 de la mañana.
4. Escalado
A quién contactar, en qué orden, para qué tipos de incidencias. Números de teléfono, no handles de Slack. Incluya la ruta para "esto excede el alcance de on-call — escalar a ingeniería".
5. Rollback
Las condiciones específicas bajo las que hacemos rollback, y el procedimiento. Crucial: quién está autorizado a decidir hacer rollback sin reunión. Normalmente el on-call.
El propio procedimiento de rollback debería ser un único comando. Si son tres pasos y una llamada de coordinación, no es un procedimiento de rollback — es un plan de proyecto.
6. Change log
Cada cambio desde la última revisión del runbook: versión de prompt, versión de modelo, versión de índice de retrieval, upgrades de dependencias. Una línea de tiempo que permite al on-call ver "qué cambió en las últimas 24 horas" cuando algo empieza a comportarse mal.
Lo que no contiene
El runbook no sirve para explicar cómo funciona el agente. Para eso hay un documento de arquitectura. El runbook sirve para operarlo cuando deja de funcionar.
Tampoco sirve para el onboarding de nuevos empleados. El runbook asume que conoce el sistema; le dice qué hacer cuando está roto. No lo diluya con prosa explicativa.
Qué cambia cuando hay un runbook
La relación del equipo con el agente cambia. Sin runbook, cada incidente es una incógnita — los ingenieros improvisan, y el post-mortem es en su mayoría invención.
Con un runbook, los incidentes se convierten en excepciones a una expectativa documentada. El post-mortem se convierte en una actualización del runbook: "este fallo no estaba en la sección 3; aquí va la nueva entrada". Cada incidente enseña al runbook.
A lo largo de seis meses, un runbook bien mantenido cubre el 90% de los fallos que el sistema encuentra realmente. El 10% restante son los incidentes interesantes — los que necesitan ingeniería real, no la ejecución del playbook.
La señal del handoff
El runbook es también nuestro documento de handoff. Cuando dejamos un engagement, el equipo del cliente es dueño de un sistema y de un runbook que les permite operarlo sin nosotros. Hemos visto demasiados traspasos salir mal porque el equipo saliente se quedó con el conocimiento operativo en la cabeza.
Aburrido a propósito. El runbook es lo que vuelve aburrido al agente desde el punto de vista operativo. Y aburrido es lo que parece production-grade.