Todo sistema com agentes IA que entregamos tem um runbook. Seis páginas, sem diagramas além de um fluxograma, escrito no tom de um doc de SRE de 2010. É chato de propósito.
Passamos a ver o runbook como um deliverable primário, não papelada. Se um runbook não pode ser escrito para o agente que acabamos de construir, o agente não está pronto para produção. Aqui está o porquê, e o que de fato está nele.
Por que o runbook é a especificação
Um runbook força você a responder seis perguntas que de outro modo ficariam em aberto:
- Como é "funcionando corretamente"? Não vibe — uma checagem concreta. "Latência p95 abaixo de X, taxa de aprovação de evals acima de Y, custo por requisição entre A e B."
- Como é "quebrado"? Sintomas específicos com limiares, não só "usuários reclamam."
- Quem é paginado quando quebra? Um nome, uma cadeia de escalation, um número de telefone.
- Qual é o playbook para cada falha conhecida? Passo a passo, incluindo "não faça nada por 5 minutos" se essa for a resposta.
- Quando fazemos rollback? Não "se piorar." Uma condição específica que dispara rollback sem exigir uma reunião.
- Que estado sobrevive, e qual não? Se fazemos rollback do agente, o que acontece com workflows em andamento, completions parciais, requisições em fila?
Se o time não consegue responder todas as seis por escrito, o agente ainda não é production-grade. O runbook não é documentação do que já é verdade — escrevê-lo é o que torna verdade.
A estrutura
Todo runbook que entregamos tem as mesmas seis seções:
1. Resumo do serviço
Um parágrafo. O que este agente faz, do que depende, o que depende dele. Atualizado sempre que as responsabilidades do agente mudam.
2. Saúde
A URL do dashboard. As quatro ou cinco métricas que definem "saudável." Limiares para verde / amarelo / vermelho. Não mais que cinco — se você tem dez, ninguém olha.
3. Falhas comuns
Cada modo de falha ganha uma seção:
- Sintoma — o que um operador vê no dashboard.
- Diagnóstico — como confirmar que esta é a causa real, não uma parecida.
- Mitigação — os passos a tomar, em ordem, com resultados esperados.
- Resolução — como é o sucesso.
Miramos em 6–10 modos de falha documentados. A maioria dos operadores só vai precisar de três deles, mas a cauda longa é o que te salva às 3 da manhã.
4. Escalation
Quem contatar, em que ordem, para que tipos de problemas. Números de telefone, não handles de Slack. Inclua o caminho para "isto está além do escopo do on-call — escale para engenharia."
5. Rollback
As condições específicas sob as quais fazemos rollback, e o procedimento. Crucialmente: quem está autorizado a decidir fazer rollback sem reunião. Geralmente o on-call.
O procedimento de rollback em si deve ser um comando. Se são três passos e uma call de coordenação, não é procedimento de rollback — é plano de projeto.
6. Change log
Toda mudança desde a última revisão do runbook: versão de prompt, versão de modelo, versão de índice de retrieval, upgrades de dependência. Uma timeline que deixa o on-call ver "o que mudou nas últimas 24 horas" quando algo começa a se comportar mal.
O que não está nele
O runbook não é para explicar como o agente funciona. Existe um doc de arquitetura para isto. O runbook é para operá-lo quando para de funcionar.
Também não é para onboarding de novos contratados. O runbook assume que você conhece o sistema; te diz o que fazer quando ele quebra. Não dilua com prosa explicativa.
O que muda quando há um runbook
A relação do time com o agente muda. Sem runbook, todo incidente é uma incógnita — engenheiros improvisam, e o post-mortem é em grande parte invenção.
Com um runbook, incidentes se tornam exceções a uma expectativa documentada. O post-mortem se torna uma atualização do runbook: "esta falha não estava na seção 3; aqui está a nova entrada." Cada incidente ensina o runbook.
Ao longo de seis meses, um runbook bem mantido cobre 90% das falhas que o sistema de fato encontra. Os 10% restantes são os incidentes interessantes — os que precisam de engenharia de verdade, não execução de playbook.
O sinal de handoff
O runbook também é nosso documento de handoff. Quando saímos de um engagement, o time do cliente fica com um sistema e um runbook que permite operá-lo sem nós. Já vimos handovers demais darem errado porque o time que saía guardava o conhecimento operacional na cabeça.
Chato de propósito. O runbook é o que torna o agente chato de operar. E chato é como production-grade se parece.