Runbook de operação para agente de IA: o que documentar

Um runbook de operação para agente de IA é um conjunto curto de notas que permite a uma pessoa qualificada, que não construiu o agente, entender o que ele faz, diagnosticar um problema, pausá-lo e restaurá-lo. Ele cobre a finalidade do agente, o responsável, os acessos, o comportamento normal, os padrões de falha conhecidos e os passos exatos para interromper e retomar o trabalho. Se um colega capaz não consegue agir com base nele sob pressão, o documento ainda não está pronto.

Principais pontos

• O runbook é escrito para quem está de plantão, não para quem construiu o agente. Ele deve funcionar sem uma ligação para o responsável pela construção.
• Documente o procedimento de pausa antes de qualquer outra coisa. Parar o agente com segurança importa mais do que explicá-lo com elegância.
• Registre como é o funcionamento normal, para que os desvios fiquem visíveis. Um guia de diagnóstico liga cada sintoma a uma primeira verificação.
• Restaurar é um procedimento diferente de corrigir. Defina o que precisa ser verdade antes de o agente voltar a trabalhar sem supervisão.
• Um runbook que não é revisado com regularidade vira ficção. Vincule a atualização a toda mudança de ferramentas, permissões, instruções ou modelo.

O que é um runbook de operação para agente de IA e para quem ele serve?

Um runbook é o manual de operação de um sistema em funcionamento. Para um agente de IA, ele responde às perguntas que as pessoas fazem quando algo parece errado: o que este agente deveria fazer? Em que ele pode mexer? Como sei se está se comportando de forma normal? Como o paro? Como o coloco de volta?

O leitor é uma pessoa qualificada, ou seja, alguém com o acesso adequado e boa noção geral de operações, mas que não é necessariamente o engenheiro que configurou o agente. Pense em um líder de operações cobrindo a ausência de um colega, ou em um contato de plantão em uma empresa parceira. Essa pessoa deve conseguir agir apenas com o runbook aberto.

Isso é diferente das instruções do agente. As instruções dizem ao agente como se comportar. O runbook diz aos humanos como operar o agente. Manter os dois separados também facilita a manutenção, tema que se conecta ao debate sobre prompt engineering ou harness engineering. O runbook deve descrever as instruções (onde ficam e quem pode alterá-las), não copiá-las.

O que deve constar na primeira página?

A primeira página é uma ficha de registro. Quem abrir o runbook durante um incidente deve encontrar o essencial sem precisar rolar a tela. Inclua estes itens:

• Finalidade: uma ou duas frases sobre o papel do agente e sobre o trabalho que ele explicitamente não faz.
• Responsável e substituto: pessoas nomeadas, com forma de contato, e quem tem autoridade para pausar o agente.
• Canais: onde o agente recebe pedidos e para onde envia o resultado, como uma caixa de e-mail compartilhada ou um espaço de chat.
• Sistemas e ferramentas: cada sistema que o agente lê ou em que escreve, indicando quais ações são somente leitura, quais são propostas e quais são gravações diretas.
• Identidade e permissões: a conta que o agente usa, o alcance do acesso e onde as credenciais são gerenciadas. Os detalhes de armazenamento de credenciais pertencem ao seu sistema de segredos, não ao runbook, mas o runbook diz onde procurar.
• Limites de aprovação: as ações que sempre exigem decisão humana e quem aprova cada uma.
• Agenda: execuções recorrentes ou disparadas por eventos, com o horário normal de cada uma.
• Dependências: o provedor do modelo, as integrações e as fontes de dados de que o agente depende, com o contato ou a página de status de cada uma.
• Critério de sucesso: o sinal observável de que o agente está cumprindo seu papel, conforme combinado quando a função foi definida.

A linha de permissões merece cuidado. Orientações de autorização, como o Authorization Cheat Sheet da OWASP, enfatizam o privilégio mínimo e a negação por padrão. Um runbook que lista as permissões reais deixa claro quando o agente tem mais acesso do que o seu papel exige.

Como escrever um procedimento de pausa que qualquer pessoa consiga seguir?

A pausa é a seção mais importante, porque o primeiro objetivo em um incidente é conter o dano, não entendê-lo. Escreva em passos numerados, em linguagem simples, e defina mais de um nível de pausa, já que um desligamento total nem sempre é necessário.

Uma estrutura viável tem três níveis:

• Nível um, parar o trabalho novo: o agente não assume nenhuma tarefa nova. As execuções agendadas ficam desativadas e os pedidos que chegam são retidos em uma fila ou encaminhados a uma pessoa.
• Nível dois, parar as ações externas: o agente ainda pode ler e redigir, mas o envio de mensagens e a gravação em sistemas ficam desativados. O resultado vai para uma lista de revisão.
• Nível três, cortar o acesso: as credenciais do agente são suspensas ou as conexões das ferramentas são desligadas, de modo que ele não consiga agir mesmo que algo mais falhe.

Depois, descreva os passos. Aqui está um roteiro que você pode adaptar:

• Passo um: confirme que você tem autoridade para pausar e anote o horário e o motivo no registro de incidentes.
• Passo dois: desative as execuções agendadas e os gatilhos. Indique o lugar exato onde cada um é controlado.
• Passo três: aplique o nível de pausa compatível com o risco. Se o agente pode estar enviando informação errada para fora da empresa, vá direto ao nível dois ou três.
• Passo quatro: capture o estado atual. Salve a atividade recente do agente, a fila e as tarefas pela metade antes de alterar qualquer coisa.
• Passo cinco: avise as pessoas afetadas. Diga quem precisa ser informado, como o dono do processo e quem aguarda o resultado do agente, e forneça um modelo curto de mensagem.
• Passo seis: encaminhe o trabalho pausado a uma pessoa. Diga para onde vão os itens pendentes e quem cuida deles enquanto isso.

O último passo é o que as equipes esquecem. Pausar um agente que carrega trabalho real sem um caminho manual apenas move a falha para um lugar menos visível. Para entregar o trabalho a uma pessoa de forma limpa, veja o princípio de enviar a decisão, não a bagunça, em escalonamento humano em IA.

Como diagnosticar um agente que se comporta mal?

O diagnóstico exige duas coisas no runbook: uma descrição do que é normal e um mapa que ligue sintomas a primeiras verificações. Normal significa o volume típico de tarefas, a faixa usual de tempo de conclusão, os resultados mais comuns e a proporção habitual de casos resolvidos sem ajuda humana. Escreva isso com suas próprias palavras, conferido com a atividade real, e não como palpite. Sem uma referência, todo dia estranho parece uma emergência ou passa despercebido.

O mapa de sintomas pode ser uma lista simples. Cada linha traz o sintoma e o primeiro lugar a olhar:

• O agente não produz resultado: verifique se ele está pausado, se a agenda ou o gatilho disparou e se as credenciais ainda são válidas.
• O agente produz resultado, mas errado ou inventado: verifique de qual fonte ele recuperou a informação, se essa fonte mudou e se as instruções ou o modelo foram atualizados recentemente.
• O agente repete a mesma ação: verifique se há um laço de repetição em andamento e se algum sistema posterior está rejeitando a ação. A política de repetição deve dizer quantas tentativas são aceitáveis.
• O agente age fora do seu papel: verifique mudanças recentes em permissões ou ferramentas e leia as entradas que ele recebeu, procurando instruções embutidas. Documentos vindos de fora da empresa podem conter texto que tenta conduzir o agente.
• O agente está lento: verifique primeiro as páginas de status das dependências, depois o tamanho das entradas e a fila.
• O agente pede ajuda humana com muito mais frequência que o normal: verifique se uma ferramenta falhou, se o formato de um documento mudou ou se alguma regra ficou ambígua.

O diagnóstico só é tão bom quanto a evidência disponível. O runbook deve informar onde ficam os logs e os rastros, como pesquisá-los e o que cada registro contém. A documentação do OpenTelemetry sobre conceitos de observabilidade explica por que rastros, métricas e logs juntos dão um quadro mais completo do que qualquer um isolado. Os eventos que vale registrar em um agente estão em Observabilidade de agentes de IA: o que registrar?.

Como restaurar um agente depois de uma pausa?

Restaurar não é o inverso de pausar. A pausa é uma ação rápida. A restauração é uma decisão deliberada, com condições. Escreva essas condições com antecedência, para que ninguém retome o agente só porque a pressão para isso é grande.

Uma lista de verificação de restauração pode ser assim:

• A causa foi identificada, ou a capacidade de risco foi desativada para que a causa não se repita.
• Toda mudança feita durante o incidente está registrada, com quem a fez e por quê.
• Os resultados afetados foram revisados, e correções ou avisos foram enviados quando necessário.
• As tarefas pela metade foram resolvidas. Decida, para cada uma, se vai retomar, refazer ou cancelar. A ideia de progresso salvo está em Checkpoints de agentes de IA: como retomar o trabalho.
• Um pequeno conjunto de casos de teste conhecidos foi executado e os resultados batem com o esperado.
• O agente volta primeiro em nível reduzido, como o nível dois com revisão humana dos resultados, antes de recuperar a autonomia plena.
• O responsável nomeado aprova a volta ao normal e registra a decisão.

Se a causa foi uma mudança de modelo ou de instruções, a decisão pode ser ajustar ou reverter, em vez de simplesmente retomar. O runbook deve dizer onde ficam as versões anteriores das instruções e das configurações e quem pode revertê-las. O raciocínio por trás dessa escolha está em O que fazer quando o modelo de IA muda: adotar, ajustar ou reverter.

Como isso funciona na prática?

Veja um cenário ilustrativo, não um caso real. Uma empresa de serviços tem um agente que redige respostas a pedidos de agendamento de clientes e propõe alterações na agenda para uma coordenadora aprovar. Em uma segunda-feira, a coordenadora percebe que vários rascunhos oferecem horários que já estão ocupados.

A coordenadora, que não configurou o agente, abre o runbook. A primeira página confirma que o agente tem acesso somente de proposta à agenda, então nenhuma reserva errada pode ter sido gravada. Ela aplica o nível dois: os rascunhos ficam retidos para revisão e nada é enviado. Os passos de pausa levam poucos instantes porque cada controle está nomeado.

O guia de diagnóstico aponta para resultado errado ou inventado, e a coordenadora confere a fonte de consulta listada na primeira página. Uma planilha compartilhada de disponibilidade havia sido reorganizada na semana anterior, e uma coluna da qual o agente dependia mudou de lugar. Ela registra isso, pede ao responsável que corrija o mapeamento da fonte e, enquanto isso, encaminha os pedidos para a fila manual.

Na restauração, o responsável corrige o mapeamento, executa os casos de teste conhecidos e recoloca o agente em operação com revisão de todos os rascunhos por alguns dias. O registro mostra quem decidiu o quê. Nada nessa sequência exigiu que o construtor original estivesse disponível.

Como manter o runbook atualizado, e como a Be Human trata isso?

Um runbook se degrada em silêncio. Ferramentas são adicionadas, permissões mudam, instruções são editadas, e o documento continua descrevendo o agente do trimestre passado. Evite isso fazendo da atualização parte do trabalho, e não uma tarefa à parte:

• Atualize o runbook na mesma mudança que altera uma ferramenta, permissão, agenda ou instrução. Nenhuma mudança está concluída até o documento refletir a realidade.
• Revise-o em um ciclo recorrente, junto com a manutenção de rotina, como a descrita em Checklist semanal de manutenção de agentes de IA.
• Depois de cada incidente, acrescente o novo sintoma, a verificação que encontrou a causa e qualquer passo que ficou confuso.
• Teste o procedimento de pausa de vez em quando com alguém que nunca o usou e corrija o que causar dúvida.
• Mantenha uma única versão atual em um único lugar, com data de revisão e responsável visíveis.

O AI Risk Management Framework do NIST trata o monitoramento contínuo e a responsabilização clara como parte da gestão de sistemas de IA, e um runbook bem mantido é uma forma prática de cumprir os dois.

A Be Human desenha um runbook como parte da configuração de cada agente, junto com identidade, memória, ferramentas, permissões e limites de aprovação. Na operação gerenciada, ele é mantido atualizado conforme integrações, permissões ou modelos mudam, e é usado no monitoramento, nas avaliações recorrentes, nas revisões de permissões e na resposta a incidentes. As pessoas da própria empresa, nomeadas, mantêm a autoridade de pausar ou aprovar, e o runbook é escrito para que elas possam usá-lo diretamente.

Perguntas frequentes

Qual deve ser o tamanho de um runbook de agente de IA? O suficiente para que quem está de plantão consiga pausar, diagnosticar e restaurar sem pedir ajuda a ninguém, e não mais que isso. Para a maioria dos agentes de uma única função, isso significa poucas páginas: uma ficha de registro, um procedimento de pausa, um guia de diagnóstico e uma lista de verificação de restauração. Coloque os detalhes em documentos vinculados e mantenha o runbook fácil de escanear.

Quem deve ser o dono do runbook? A pessoa responsável pelo papel do agente no negócio deve ser a dona, com um substituto nomeado. Os colaboradores técnicos escrevem e verificam as seções técnicas, mas a titularidade fica com alguém que pode decidir pausar ou retomar. Sem um dono nomeado, as atualizações param e o documento envelhece.

Todo agente precisa de um runbook próprio? Sim, embora possam compartilhar seções comuns. Dois agentes podem usar o mesmo provedor de modelo e os mesmos contatos de escalonamento, mas costumam diferir em permissões, ferramentas e padrões de falha. Um documento-base compartilhado, com uma página curta específica para cada agente, é uma estrutura sensata.

O que escrever primeiro se hoje não temos nada? Escreva o procedimento de pausa e, em seguida, a ficha de registro. Essas duas peças permitem que alguém pare o agente e saiba o que está parando. Monte o guia de diagnóstico a partir dos seus primeiros incidentes reais, porque as falhas de verdade ensinam mais do que as previsões.

Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.