Manual do Operador de Agentes: Supervisionando o Que Você Não Consegue Ver

Operar agentes autônomos de IA é uma nova disciplina: não é engenharia, não é gestão, não é operações, mas um híbrido que exige as três. O papel do operador surge quando agentes rodam por tempo suficiente para que a supervisão se torne o gargalo, não a geração de código. Cinco responsabilidades definem o papel. Uma pilha de supervisão as implementa. Um framework de intervenção decide quando agir.

Ninguém foi treinado para essa função. Nenhum departamento universitário a ensina. Nenhuma vaga de emprego a descreve com precisão. Em um mês você escreve Python. No mês seguinte você gerencia um sistema autônomo que escreve Python, chama APIs, modifica seu sistema de arquivos e toma decisões arquiteturais enquanto você dorme. O loop Ralph criou esse papel na minha infraestrutura: um shell script que reinicia o Claude Code com contexto limpo, lê o estado do sistema de arquivos e continua o trabalho ao longo de sessões noturnas. Toda equipe que roda agentes de forma autônoma descobriu o mesmo papel de forma independente, porque os mesmos problemas aparecem sempre que um agente opera por mais tempo do que uma única sessão interativa.

O papel não tem um nome estabelecido. Algumas equipes chamam de “AI ops.” Outras o incorporam à engenharia de plataforma. Algumas atribuem a gerentes de engenharia que nunca escreveram um hook. A ambiguidade importa porque identificar o papel incorretamente leva a alocar o trabalho de forma errada. Um gerente de engenharia sem conhecimento de sistemas não consegue depurar um estado corrompido de agente. Um engenheiro de plataforma sem senso de produto não consegue avaliar se a saída do agente atende à intenção da especificação. O papel do operador exige ambos: decisões de especificação (o que o agente deve construir, quais restrições impor) e execução operacional (monitorar sessões, recuperar falhas, manter infraestrutura).

Cinco Responsabilidades do Operador

1. Delegação

Delegação significa escrever especificações que restringem o comportamento do agente antes do início da execução. A qualidade da delegação determina a qualidade da saída autônoma mais do que qualquer outro fator.

Um arquivo CLAUDE.md é um artefato de delegação. Ele codifica convenções do projeto, padrões proibidos, comportamentos obrigatórios e padrões de qualidade em um documento que o agente lê no início da sessão.¹ Um PRD é um artefato de delegação. Ele especifica critérios de aceite que o agente verifica antes de reportar a conclusão. Uma descrição de tarefa é um artefato de delegação. A especificidade da descrição da tarefa delimita o espaço de decisão do agente.

Delegação deficiente produz a Espiral de Atalhos: o agente pula etapas porque a especificação não as listou como obrigatórias. Boa delegação torna as etapas necessárias explícitas. Meus PRDs incluem critérios de aceite numerados, e cada critério mapeia para um artefato observável (um caminho de arquivo, um resultado de teste, um comportamento específico). O agente não pode marcar um critério como concluído sem produzir o artefato. Delegação que especifica resultados observáveis elimina toda uma classe de conclusões fantasma.

A habilidade está em saber o que especificar e o que deixar em aberto. Especificação excessiva produz agentes frágeis que não conseguem se adaptar quando encontram código inesperado. Especificação insuficiente produz agentes que tomam decisões arquiteturais que você não autorizou. O limite se move com a confiança: um agente bem testado com hooks robustos ganha mais liberdade do que uma nova configuração rodando sua primeira sessão noturna.

2. Supervisão

Supervisão significa monitorar sessões ativas, revisar diffs e detectar desvios antes que se acumulem.

Desvio é o risco central. Um agente começa alinhado com a especificação, toma uma microdecisão razoável que desvia levemente, e depois toma decisões subsequentes que se baseiam no desvio. Na oitava iteração, o agente está resolvendo um problema diferente daquele que você delegou. Cada decisão individual parecia razoável isoladamente. A trajetória acumulada errou o alvo.

Eu detecto desvios por dois mecanismos. Primeiro, hooks impõem limites rígidos: comandos bloqueados, padrões obrigatórios, modificações de arquivo proibidas. Hooks capturam violações em tempo real, antes que o agente prossiga. Segundo, revisão periódica de logs captura desvios sutis que nenhum hook consegue detectar: o agente escolhendo uma abordagem desnecessariamente complexa, ou construindo um recurso que a especificação não solicitou, ou otimizando um caminho de código que não era o gargalo. Desvios sutis exigem julgamento humano porque nenhuma verificação automatizada consegue determinar se a trajetória do agente corresponde à intenção do operador.

Supervisão escala mal com o número de agentes. Um agente produzindo uma sessão por noite é revisável durante o café da manhã. Cinco agentes produzindo oito iterações cada geram quarenta janelas de contexto de trabalho. Priorização se torna obrigatória: revise falhas primeiro, depois sessões que tocaram caminhos críticos, depois conclusões limpas em tarefas de baixo risco.

3. Intervenção

Intervenção significa saber quando parar, redirecionar ou reiniciar um agente no meio de uma tarefa.

Quatro padrões exigem intervenção:

O agente está preso em um loop. O mesmo erro aparece em iterações consecutivas. O agente tenta a mesma correção com variações mínimas. Cada iteração consome uma janela de contexto inteira e não produz progresso. Intervenção: pare a sessão, diagnostique a causa raiz manualmente, atualize o documento de handoff com o diagnóstico, reinicie.

O agente produziu saída incorreta que passa nos testes. O código compila, os testes estão verdes, mas o comportamento não corresponde à intenção da especificação. O evidence gate captura alguns casos, mas um agente pode produzir uma justificativa plausível para comportamento errado. Intervenção: escreva um teste que falhe e que capture o comportamento correto, depois reinicie.

O agente está prestes a tocar produção ou sistemas externos. Qualquer operação com consequências irreversíveis (deploy em produção, envio de emails, modificação de banco de dados, chamada a uma API paga) exige um gate. Meus hooks bloqueiam comandos bash destrutivos e chamadas de rede externas. O operador decide quais gates abrir e quando.²

O agente está progredindo, mas na direção errada. O trabalho é competente, porém desalinhado. Intervenção: pare, esclareça a especificação no documento de handoff, reinicie. Não tente redirecionar no meio da sessão por conversa. O agente já construiu modelos mentais em torno da interpretação errada, e correção de curso na mesma janela de contexto produz saída inconsistente.

O padrão em que você não intervém: o agente progredindo lentamente em direção ao objetivo correto. Deixe rodar.

4. Recuperação

Recuperação significa lidar com falhas depois que ocorrem: estado corrompido, branches errados, builds quebrados e perda de dados.

Falhas de agente deixam artefatos. Uma sessão que travou pode ter escrito arquivos parciais, feito commit no branch errado, deixado arquivos temporários no diretório de trabalho ou modificado configurações que sessões subsequentes herdam. A recuperação exige reverter esses artefatos antes de reiniciar.

Meu protocolo de recuperação: inventarie o dano (git status, git log, git diff), preserve o log da sessão como dado diagnóstico, reverta para o último commit verificado como correto, atualize o documento de handoff com o que falhou e por quê, depois reinicie com restrições corrigidas. Não tente salvar trabalho parcial de uma sessão que falhou, a menos que o trabalho parcial esteja claramente correto e isolável. O handoff carrega contexto de falha através dos limites de sessão para que o próximo agente não repita os mesmos erros.

O cenário de recuperação mais perigoso é uma falha que parece sucesso. O agente reporta conclusão, os testes passam, o build está verde, mas a implementação está sutilmente errada. O modo de falha Miragem de Confiança produz exatamente essa situação. A recuperação exige ler o código, não apenas o relatório de conclusão.

5. Governança

Governança significa definir políticas, orçamentos, permissões e requisitos de auditoria que se aplicam a todas as sessões de agente.

Políticas definem o que agentes podem e não podem fazer. Minha camada de governança inclui: um orçamento de spawn (máximo de iterações por execução noturna), um teto de custo (gasto máximo de API por sessão), uma lista de permissão de comandos bash permitidos, uma lista de bloqueio de padrões de arquivo proibidos e um conjunto de critérios de conclusão obrigatórios.³ Cada política remonta a uma falha específica. O orçamento de spawn existe porque uma sessão inicial rodou 47 iterações sem convergir. O teto de custo existe porque uma sessão de depuração queimou $200 em chamadas de API perseguindo uma pista falsa. Cada política é uma cicatriz de uma lição aprendida da maneira cara.

Permissões seguem o princípio do menor privilégio. Um agente que gera conteúdo de blog não precisa de acesso de escrita ao sistema de arquivos fora do diretório de conteúdo. Um agente que roda testes não precisa de acesso à rede. Meus hooks impõem esses limites no nível da chamada de ferramenta, bloqueando operações que excedem o escopo de permissão da sessão.²

Requisitos de auditoria completam a camada de governança. Toda sessão produz um log estruturado: comandos executados, arquivos modificados, testes rodados, critérios de conclusão avaliados. A taxonomia de sete modos de falha emergiu da revisão de seis meses desses logs e da categorização de toda falha que exigiu intervenção humana.

A Pilha de Supervisão

Cinco componentes de infraestrutura implementam as cinco responsabilidades.

Hooks implementam supervisão automatizada. Os eventos de ciclo de vida do Claude Code (PreToolUse, PostToolUse, Notification) disparam shell scripts que impõem políticas em tempo real.² Um hook que bloqueia rm -rf é uma política de governança codificada como verificação PreToolUse. Um hook que exige execução de testes antes da conclusão é uma restrição de delegação codificada como verificação PostToolUse. Os 95 hooks no meu sistema codificam 95 decisões sobre o que agentes podem e não podem fazer, cada um rastreável a uma falha específica que o hook agora previne.

O evidence gate implementa verificação estruturada. Seis critérios (segue padrões, solução mais simples, casos extremos tratados, testes passam, sem regressões, resolve o problema) devem produzir artefatos específicos antes que o agente marque o trabalho como concluído.⁴ O gate transforma a supervisão de “o agente fez um bom trabalho?” (subjetivo, inverificável) para “o agente produziu evidência para todos os seis critérios?” (objetivo, auditável). Toda palavra evasiva em um relatório de conclusão dispara reverificação.

O quality loop implementa refinamento iterativo. Sete etapas (implementar, revisar, avaliar, refinar, ampliar a visão, repetir, reportar) forçam o agente a fazer múltiplas passagens sobre seu próprio trabalho.⁵ O loop compensa uma limitação estrutural da geração em passagem única: modelos produzem primeiros rascunhos plausíveis que contêm erros visíveis apenas na releitura. O quality loop torna a releitura obrigatória.

Logs de sessão implementam auditoria posterior. O sistema captura toda chamada de ferramenta, modificação de arquivo e relatório de conclusão em formato estruturado. Seis meses de logs de sessão produziram a taxonomia de falhas. Sem os logs, cada falha teria permanecido uma anedota isolada.

Gates de custo implementam controle orçamentário. Orçamentos de spawn limitam a contagem de iterações. Tetos de custo de API limitam o gasto de tokens. Um agente que não convergiu dentro do orçamento de spawn provavelmente está preso, e mais iterações não vão ajudar. O orçamento força o operador a diagnosticar e intervir em vez de esperar que a próxima iteração resolva o problema.

Quando Intervir vs. Quando Deixar Rodar

A decisão de intervenção é o julgamento mais consequente do operador. Intervir cedo demais desperdiça trabalho do agente. Intervir tarde demais permite que desvios se acumulem. Um framework ajuda.

O metaprincípio: intervenha na assimetria de informação, não na velocidade. Quando você sabe algo que o agente não sabe (o caminho correto no código, o requisito real, o modo de falha de uma sessão anterior), a intervenção transfere esse conhecimento. Quando o agente sabe tudo que você sabe e está simplesmente trabalhando no problema, deixe-o trabalhar.

Checklist do Operador

Antes de Começar

• [ ] Especificação revisada: critérios de aceite são específicos, observáveis e completos
• [ ] Hooks ativos: hooks de política estão habilitados e testados para o tipo de tarefa
• [ ] Orçamento definido: limite de spawn e teto de custo estão configurados
• [ ] Sandbox confirmado: o agente não pode alcançar produção, enviar requisições externas ou modificar arquivos fora do escopo
• [ ] Handoff atualizado: se continuando trabalho anterior, o documento de handoff reflete as últimas correções
• [ ] Branch limpo: diretório de trabalho está no branch correto sem alterações não commitadas

Durante

• [ ] Verificar logs em intervalos definidos (a cada 2-3 iterações para execuções noturnas)
• [ ] Verificar se a trajetória corresponde à intenção da especificação, não apenas à letra
• [ ] Monitorar uso de recursos: gasto de tokens, contagem de iterações, mudanças no sistema de arquivos
• [ ] Observar escalação de permissões: solicitações de acesso que a tarefa não deveria exigir
• [ ] Anotar qualquer desvio sutil para a revisão pós-sessão

Depois

• [ ] Revisar todas as mudanças de arquivo, não apenas o relatório de conclusão
• [ ] Rodar a suíte de testes completa de forma independente (não confie nos resultados de teste reportados pelo agente)
• [ ] Verificar regressões em código adjacente que o agente não modificou explicitamente
• [ ] Verificar o evidence gate: todo critério tem um artefato específico, não uma garantia genérica
• [ ] Atualizar o documento de handoff com resultados da sessão e quaisquer correções
• [ ] Registrar a sessão: modos de falha encontrados, hooks que dispararam, decisões de intervenção tomadas
• [ ] Atualizar governança: se um novo padrão de falha surgiu, escreva um hook ou política para prevenir recorrência

O Operador como Artesão

O papel do operador de agentes existe na interseção entre habilidade de engenharia e senso de produto. Escrever hooks exige conhecimento de sistemas. Escrever especificações exige compreensão de produto. Revisar a saída do agente exige ambos: a capacidade de avaliar se o código está correto e se código correto resolve o problema certo.

Chat é a interface errada para a metade operacional do papel. Percorrer transcrições de conversa para supervisionar trabalho autônomo não escala além de um único agente rodando uma única sessão. A pilha de supervisão descrita acima (hooks, evidence gates, quality loops, logs de sessão, gates de custo) compensa a lacuna de interface ao codificar supervisão em infraestrutura. A infraestrutura não substitui o operador. A infraestrutura multiplica o alcance do operador.

Taste é um sistema técnico descreve a metade de julgamento. Saber o que delegar, o que verificar e o que rejeitar exige reconhecimento de padrões construído a partir de experiência. Cada sessão ensina algo ao operador sobre o comportamento do agente. A habilidade do operador se acumula por meio de prática deliberada, reflexão e infraestrutura que codifica lições permanentemente.

A dark factory representa o ponto final teórico, Nível 5, onde nenhum humano lê o código. A prática atual se encontra no Nível 3 ou 4 para a maioria das equipes: o agente faz o trabalho, o operador supervisiona e intervém. A distância entre o Nível 4 e o Nível 5 é a camada de verificação. A distância entre o Nível 2 e o Nível 4 é o operador.

Toda equipe que roda agentes autônomos vai desenvolver operadores. A questão é se elas desenvolvem o papel deliberadamente (com responsabilidades definidas, suporte de infraestrutura e treinamento explícito) ou acidentalmente, atribuindo o trabalho a quem estiver acordado quando a sessão noturna falhar. O ofício se desenvolve a partir daí.