Runbook operacional para agentes de IA: como criar

O agente funciona, mas poucas pessoas sabem operá-lo

A implantação terminou. O agente recebe entradas, consulta fontes, chama ferramentas e entrega resultados. Quando surge uma fila incomum, uma fonte vencida ou um alerta de custo, a equipe procura quem participou do projeto. As decisões estão em mensagens antigas, no histórico do fornecedor e na memória de uma pessoa.

Esse cenário cria uma dependência difícil de enxergar. A automação está disponível, mas a capacidade de operá-la continua artesanal.

Um runbook operacional para agentes de IA reúne os procedimentos necessários para observar, orientar, limitar, apoiar e evoluir uma capacidade em produção. Ele mostra o que verificar, qual decisão tomar, quem possui autoridade, onde registrar evidência e quando escalar.

O documento precisa servir durante o trabalho. Se exige interpretação do autor sempre que alguém abre a página, virou arquivo histórico com nome de procedimento.

Runbook, arquitetura e contingência cumprem funções diferentes

Esses artefatos se conectam, mas respondem a perguntas próprias.

Arquitetura explica a composição

Mostra modelos, fontes, memória, ferramentas, identidades, integrações, filas, controles e sistemas de destino. Ajuda a entender como a capacidade foi construída.

Runbook orienta a operação

Explica como verificar saúde, tratar sinais conhecidos, confirmar efeitos, executar rotinas, acionar responsáveis e registrar decisões.

Plano de contingência preserva o serviço durante indisponibilidade

Define modos degradados, capacidade manual, prioridades, filas temporárias, comunicação e reconciliação. O plano de contingência para agentes de IA cobre esse período de redução ou suspensão.

O runbook deve apontar para arquitetura e contingência sem copiá-las integralmente. Sua função central é converter conhecimento operacional em ação segura e repetível.

Comece pelo serviço prestado pelo agente

Um runbook centrado apenas no nome do aplicativo fica difícil de usar. Descreva a unidade de trabalho que precisa terminar.

Exemplos:

oportunidade comercial com próxima ação registrada;
chamado classificado e encaminhado;
documento conferido com divergências visíveis;
pedido validado antes da separação;
reunião preparada com fontes e pendências;
cobrança acompanhada até um estado confirmado.

A abertura do runbook deve informar:

nome da capacidade;
processo e área atendidos;
unidade de trabalho;
evento de entrada;
conclusão válida;
sistemas oficiais;
classes fora do escopo;
dono operacional;
responsável técnico;
versão ativa e última revisão.

Essa ficha permite que uma pessoa entenda rapidamente qual resultado está protegendo. Agente comercial online é um estado técnico. Oportunidades elegíveis recebem briefing até duas horas antes da reunião é uma condição operacional.

Defina o público e o limite de cada procedimento

Um único documento pode atender pessoas com responsabilidades diferentes, desde que as fronteiras estejam claras.

Operador ou usuário de negócio

Precisa saber enviar entradas válidas, conferir saídas, corrigir campos permitidos, reconhecer exceções e pedir ajuda.

Suporte N1

Precisa identificar a unidade, consultar estado conhecido, aplicar solução documentada de baixo risco e encaminhar o pacote correto.

Suporte N2

Precisa reconstruir a execução, verificar fontes, filas, credenciais e integrações, além de reconciliar estados.

Responsável técnico ou N3

Precisa reproduzir defeitos, corrigir componentes, criar regressão e preparar uma mudança controlada.

Dono do processo

Precisa decidir regra ambígua, prioridade, qualidade aceitável, restrição temporária e retorno ao serviço normal.

O artigo sobre suporte N1, N2 e N3 para agentes de IA detalha as rotas. No runbook, cada procedimento deve declarar quem pode executá-lo e que ação está proibida para aquele papel.

Estruture o runbook em oito blocos

1. Visão rápida do serviço

Coloque no topo o que ajuda durante os primeiros minutos:

status e painel principal;
canal de suporte;
dono e substituto;
links para filas;
versão ativa;
dependências críticas;
caminho de interrupção;
próxima janela de revisão.

Evite começar com histórico do projeto. Em uma página operacional, a pessoa procura estado e ação.

2. Fluxo normal

Descreva o caminho esperado da unidade:

entrada recebida;
identidade ou objeto confirmado;
contexto reunido;
decisão ou preparação executada;
ferramenta chamada;
aprovação obtida quando exigida;
efeito confirmado no destino;
conclusão registrada.

Para cada etapa, indique o sinal de sucesso e a fonte de confirmação. Uma resposta 200 da integração pode mostrar que a API aceitou a chamada, mas o procedimento deve confirmar se o registro correto mudou no sistema oficial.

3. Rotinas de verificação

Separe por cadência.

Verificação diária

entradas recebidas e unidades concluídas;
tarefas em estado incerto;
idade da fila;
aprovações vencidas;
falhas por dependência;
custo e latência fora da faixa;
alertas sem responsável;
divergência entre execução e sistema final.

Verificação semanal

qualidade por classe de caso;
correções humanas;
escalonamentos;
incidentes e quase incidentes;
fontes ou regras próximas da revisão;
consumo por unidade válida;
mudanças realizadas;
procedimentos usados ou desatualizados.

Verificação mensal ou por ciclo

resultado comparado à linha de base;
autonomia e permissões;
acesso de usuários e contas técnicas;
aderência ao SLA;
capacidade de suporte;
dependência de fornecedor;
necessidade de ampliar, restringir ou encerrar a capacidade.

A cadência deve acompanhar volume e risco. Um agente de alto impacto pode exigir observação contínua. Uma rotina interna de baixo volume pode usar revisão semanal.

4. Tabela de sinais e decisões

Alertas precisam indicar comportamento. Organize uma tabela como esta:

| Sinal | Como confirmar | Ação permitida | Escalar para | Evidência de encerramento | |---|---|---|---|---| | fila acima da faixa | painel e idade por classe | priorizar e limitar novas entradas | dono do processo e N2 | backlog dentro do limite | | fonte vencida | versão e data oficial | bloquear classes dependentes | dono da fonte | fonte vigente publicada e testada | | confirmação ausente | consultar sistema final | marcar estado incerto, sem repetir | N2 | efeito confirmado ou reconciliado | | custo por unidade elevado | consumo e unidades válidas | reduzir rota cara dentro da política | responsável técnico | custo volta à faixa aprovada | | saída fora da política | caso, versão e fonte | conter classe afetada | dono do processo e N3 | correção testada e mudança aprovada |

Não use investigar como única ação. O operador precisa saber se preserva a fila, restringe escopo, consulta o destino, aciona contingência ou interrompe uma capacidade.

5. Procedimentos conhecidos

Cada procedimento deve caber em uma sequência curta e verificável.

Use este formato:

Condição: qual sinal autoriza o procedimento.
Pré-requisitos: acesso, papel e dados necessários.
Risco: o que pode acontecer se a ação for aplicada incorretamente.
Passos: sequência numerada.
Bloqueios: situações em que a pessoa deve parar.
Confirmação: como provar o resultado no sistema final.
Registro: onde salvar decisão, horário e evidência.
Escalonamento: quem assume quando o procedimento falha.

Um procedimento de reprocessamento, por exemplo, deve exigir consulta ao destino antes da nova tentativa. Quando o efeito anterior é incerto, repetir pode duplicar mensagem, tarefa, cobrança ou alteração. O guia sobre idempotência em agentes de IA explica como preservar a unidade de efeito entre tentativas.

6. Escalonamento por consequência

O runbook precisa indicar quando sair do caminho comum.

Escalone imediatamente quando houver:

exposição ou mistura de dados;
ação sobre cliente ou registro errado;
valor, contrato ou comunicação fora da alçada;
incapacidade de interromper execuções perigosas;
perda de evidência necessária;
repetição em lote;
divergência sem fonte de autoridade;
mudança não autorizada;
falha com alcance crescente.

Casos críticos não devem percorrer uma fila cronológica de níveis. Acione o responsável capaz de conter o efeito e preserve o registro. O plano de resposta a incidentes de IA assume coordenação quando existe dano ou risco relevante.

7. Mudanças e versões

O runbook deve mostrar a versão à qual cada procedimento se aplica. Modelo, instrução, fonte, ferramenta, permissão e fila podem mudar o comportamento esperado.

Inclua:

versão ativa por ambiente;
data da última mudança;
resumo do que foi alterado;
procedimentos afetados;
testes executados;
aprovadores;
período de observação;
caminho de rollback.

Atualizar o runbook não autoriza a mudança. O controle de mudanças em agentes de IA organiza hipótese, regressão, aprovação, implantação gradual e reversão.

8. Histórico útil

Registre apenas decisões que ajudam a operar:

procedimento criado ou removido;
mudança de responsável;
incidente que alterou uma regra;
nova dependência;
restrição temporária;
teste de contingência;
versão incompatível;
data e resultado da revisão.

Um histórico gigantesco prejudica a consulta. Mantenha a página atual curta e direcione detalhes para registros de mudança, incidente ou post-mortem.

Como escrever um procedimento que outra pessoa consegue executar

A qualidade aparece quando o autor sai da sala. Faça três testes.

Teste de linguagem

Troque frases abstratas por sinais observáveis.

Evite: verifique se o agente está normal.

Prefira: confirme entradas nos últimos 15 minutos, idade da fila abaixo do limite, ausência de erros impeditivos e gravação no sistema final.

Teste de autoridade

Cada verbo precisa de permissão clara. Consultar, pausar, reprocessar, alterar prioridade, revogar acesso e publicar versão pertencem a papéis diferentes.

Teste de encerramento

A sequência precisa terminar em evidência. Reiniciar workflow descreve atividade. Unidade concluída no CRM sem duplicidade e fila voltou à faixa descreve encerramento.

Exemplo: runbook de um agente de preparação comercial

Considere um agente que reúne histórico do CRM, agenda, e-mails autorizados e compromissos para preparar reuniões.

Condição normal

reuniões elegíveis identificadas;
briefing gerado dentro do prazo;
conta e participantes corretos;
fontes recentes ligadas ao resumo;
divergências marcadas;
nenhuma alteração comercial executada.

Sinais de atenção

reunião sem conta associada;
histórico do CRM desatualizado;
briefing entregue depois da janela útil;
conflito entre proposta e cadastro;
e-mail sem permissão de consulta;
duplicidade de oportunidade;
aprovador ausente para informação sensível.

Decisões do operador

corrigir vínculo permitido antes de nova execução;
marcar fonte ausente;
entregar pacote parcial com limite visível;
escalar conflito de valor ao responsável;
preservar a reunião na fila manual;
impedir atualização automática quando a identidade é incerta.

Evidência de conclusão

briefing vinculado à reunião correta;
fontes e horário registrados;
pendências atribuídas;
vendedor notificado no canal previsto;
estado final pesquisável.

O exemplo mostra por que o runbook precisa acompanhar a unidade. Uma tela verde não garante que o vendedor recebeu contexto útil antes da conversa.

Onde o runbook deve viver

O melhor lugar combina acesso, versão, busca e proximidade com o trabalho.

Pode ser:

base de conhecimento operacional;
repositório versionado;
sistema de service desk;
portal interno;
catálogo de agentes;
documentação ligada ao painel.

Evite depender de arquivo local, conversa privada ou link que somente o fornecedor consegue abrir. A equipe de plantão, os substitutos e os donos precisam acessar a versão vigente sem pedir permissão durante a ocorrência.

Use links para painéis e sistemas, mas não coloque credenciais no documento. O procedimento deve apontar para o cofre e para o processo de acesso aprovado.

Como manter o runbook vivo

Documentação operacional envelhece quando a revisão depende de boa vontade. Crie gatilhos.

Revise quando ocorrer:

mudança de modelo ou configuração;
nova fonte ou integração;
alteração de permissão;
mudança no processo;
incidente ou falha recorrente;
nova classe de caso;
troca de dono ou fornecedor;
teste de contingência;
aumento relevante de volume;
procedimento que falhou durante uso.

Defina também uma revisão periódica. O responsável deve confirmar links, acessos, contatos, limites, versão e aderência aos sistemas atuais.

Toda correção relevante precisa produzir um dos seguintes ativos:

procedimento novo;
procedimento revisado;
alerta melhor;
automação de diagnóstico;
teste de regressão;
mudança de arquitetura;
decisão de encerrar uma rota insegura.

Assim, o suporte acumula capacidade em vez de acumular histórias.

Métricas para avaliar o runbook

Não conte apenas páginas publicadas. Observe uso e resultado.

tempo para localizar o procedimento correto;
percentual de casos conhecidos resolvidos dentro do limite;
reabertura após aplicação;
escalonamentos com pacote completo;
procedimentos que falharam;
ações sem confirmação no destino;
recorrência da mesma causa;
tempo até contenção;
idade desde a última revisão;
links ou acessos inválidos;
concentração de procedimentos em uma única pessoa;
correções transformadas em regressão.

Uma taxa alta de resolução pode esconder procedimentos perigosos. Leia junto com duplicidade, incidente, retrabalho e confirmação operacional.

Checklist do runbook operacional

[ ] O serviço e a unidade de trabalho estão definidos?
[ ] Entrada e conclusão válida são verificáveis?
[ ] Sistema oficial e fontes de autoridade estão claros?
[ ] Dono operacional, técnico e substitutos estão nomeados?
[ ] A versão ativa aparece no documento?
[ ] Fluxo normal mostra sinais de sucesso por etapa?
[ ] Rotinas diárias, semanais e periódicas estão separadas?
[ ] Alertas indicam decisão, responsável e encerramento?
[ ] Cada procedimento declara condição, risco e limite?
[ ] Reprocessamento exige confirmação do efeito anterior?
[ ] Casos críticos desviam da fila comum?
[ ] Contingência, incidente e mudança possuem links próprios?
[ ] Credenciais permanecem fora do documento?
[ ] Histórico preserva decisões úteis sem esconder a versão atual?
[ ] Eventos de mudança disparam revisão?
[ ] Outra pessoa consegue executar o procedimento sem chamar o autor?

Documentar a operação reduz dependência invisível

Agentes de IA introduzem modelos, contexto e ferramentas em processos que já dependem de regras, pessoas e sistemas. A operação precisa saber como esses elementos se encontram em cada unidade de trabalho.

Um runbook útil transforma conhecimento disperso em sinais, decisões, passos, autoridades e evidências. Ele encurta suporte, reduz improviso e permite que a empresa sustente a capacidade depois da implantação.

A maturidade aparece quando a equipe consegue operar, limitar, corrigir e revisar o agente sem depender da lembrança de quem construiu a primeira versão. O documento faz parte dessa passagem, desde que permaneça ligado ao trabalho real e seja testado por quem precisa usá-lo.