Checklist de produção para agentes de IA: logs, monitoramento, alertas, rollback e canary release
"OpenAI Agents SDK tracing registra LLM generations, tool calls, handoffs, guardrails e custom events, e pode ser usado para debugging, visualização e monitoramento em desenvolvimento e produção."
É sexta-feira à tarde e você está prestes a abrir o agente de suporte para 5% dos usuários. Os parâmetros do canary já estão prontos: porcentagem de tráfego, janela de observação, limites de alerta. Na última checagem, aparecem três problemas:
- Não há feature flag; para desligar, seria preciso fazer outro deploy.
- Ninguém sabe como mover tarefas da fila de aprovação humana de volta para a versão antiga.
- Não está claro se e-mails já enviados contam como efeitos colaterais de ferramenta, nem se o rollback deve tentar desfazê-los.
Esses três problemas não aparecem como HTTP 500 nem como tempo de resposta alto. Colocar um agente em produção exige oito dimensões além de um serviço web: trace, tool calls, guardrails, HITL, eval, cost, secrets e checkpoint. A checklist abaixo organiza tudo em quatro grupos: gates antes do release, observação do canary, monitoramento pós-release e rollback de incidentes.
1. Gates antes do release: dez checagens obrigatórias
1.1 Checagem de completude do Trace
Antes do release, confirme que o trace consegue reconstruir um Agent run completo; sem isso, fica difícil revisar um incidente. O OpenAI Agents SDK tem tracing embutido e registra LLM generations, tool calls, handoffs, guardrails e custom events, mas é preciso checar se essas informações ficam completas em produção.
Checklist:
- run ID, trace ID e span ID estão corretamente associados, permitindo rastrear um log de erro até a requisição específica.
- model call, tool call e guardrail result são registrados por completo, sem campos ausentes.
- campos de duração, uso de token e código de erro estão disponíveis, permitindo calcular baselines de custo e desempenho.
- política de retenção de traces e regras de mascaramento estão claras, evitando que dados úteis sumam por custo de armazenamento ou risco de compliance.
- o comportamento de exportação de traces é consistente entre desenvolvimento e produção.
Se o trace só registra o LLM call, sem tool call ou guardrail result, o canary pode parecer saudável com HTTP 200 enquanto argumentos de ferramenta estão errados ou permissões estão sendo ultrapassadas.
1.2 Política de mascaramento de dados sensíveis
Traces de produção podem conter PII, secrets e dados de clientes. Antes do lançamento, defina o que capturar e como mascarar. O OpenAI Agents SDK oferece a configuração trace_include_sensitive_data, que controla se entradas e saídas completas de LLM e tool calls são registradas.
Checklist:
- a localização e o valor padrão de
trace_include_sensitive_dataestão claros. - regras de detecção e mascaramento de PII cobrem campos comuns, como nome, e-mail e telefone.
- o isolamento de secrets está em vigor, para que API key e senhas de banco de dados não apareçam em traces ou logs.
- dados de clientes são classificados como públicos, internos ou confidenciais, com regras diferentes por nível.
- traces mascarados ainda são úteis para debugging.
Em produção, use detecção automática de PII com mascaramento por nível. Isso atende compliance sem perder a capacidade de depuração.
1.3 Gate de monitoramento de Guardrails
guardrails validam entrada do usuário e saída do agent, e podem usar um modelo mais rápido ou barato para bloquear requisições não conformes. O tool input guardrail do OpenAI Agents SDK roda antes de invocar uma ferramenta de função. Mas guardrails não são uma defesa absoluta. Antes do release, confirme que eles são observáveis, geram alertas e entram no plano de rollback.
Checklist:
- a baseline da taxa de bloqueio do input guardrail foi medida.
- as taxas de falso positivo e falso negativo do output guardrail são conhecidas.
- o tool input guardrail roda antes da chamada da ferramenta.
- limites de alerta para guardrail trip estão configurados.
- existe um caminho rápido de feedback para falsos positivos.
O gate de guardrails é simples: taxa de bloqueio com baseline, falsos positivos com feedback e alertas com limites.
1.4 Observabilidade de Tool Calls
Falhas em chamadas de ferramentas são um dos modos de falha mais comuns em agentes. A API HTTP pode retornar 200 enquanto argumentos estão errados, permissões são ultrapassadas ou um serviço externo faz timeout. O monitoramento comum do serviço não enxerga esses erros; eles aparecem no trace.
Checklist:
- a baseline de sucesso e falha de cada ferramenta foi medida.
- a distribuição de latência das tool calls (P50/P95/P99) é conhecida.
- limites de permissão estão claros, com allowlist ou denylist de quais ferramentas acessam quais recursos.
- modos de falha estão classificados: timeout, permissão, erro de argumento, falha de serviço externo, cada um com tratamento próprio.
- política de retry e limites de circuit breaker estão configurados.
Observabilidade de ferramentas exige baseline de sucesso por ferramenta, falhas classificadas e circuit breaker para timeouts.
1.5 Preparação do monitoramento da fila HITL
Acúmulo em filas Human-in-the-Loop (HITL) é um risco fácil de ignorar durante o canary. Os checkpointers do LangGraph salvam o graph state em cada super-step e dão suporte a HITL, time travel e fault tolerance, mas tamanho de fila e timeout de aprovação precisam de monitoramento separado.
Checklist:
- limites de alerta para tamanho da fila HITL estão configurados.
- a estratégia automática para timeout de aprovação está clara, com regras explícitas para rejeitar, passar para humanos ou degradar.
- o caminho de resume após interrupção foi validado.
- está definido como tratar tarefas na fila durante a troca de versão.
A fila HITL precisa ter limite, estratégia de timeout e caminho de retomada validado.
1.6 Eval Regression Suite
Antes do release, rode uma regression suite própria para evitar perda de capacidade. A suite deve conter tarefas reais, não apenas synthetic examples. Se a taxa de aprovação ficar abaixo da baseline, a nova versão pode ter problema e não deveria ir para produção.
Checklist:
- a regression suite contém tarefas reais em quantidade suficiente.
- a baseline de taxa de aprovação está clara (recomendado: ≥95%).
- casos de falha estão bem classificados.
- o tempo de execução da suite está controlado (recomendado: ≤15 minutos).
- o mecanismo para devolver amostras com falha do canary para a suite está pronto.
A regression suite é o último gate. Se a taxa de aprovação ficar abaixo de 95%, corrija antes do lançamento.
1.7 Cost Budget e Rate Limit
Limites de custo e taxa no nível da plataforma são a última barreira. A OpenAI recomenda usage tracking, billing limits, notification threshold e limites de spend/rate por projeto. Não dependa só de lógica de orçamento no código de negócio.
Checklist:
- spend limit no nível do projeto está configurado.
- usage notification threshold está definido (recomendado: 70%/90%).
- rate limit está segmentado por usuário ou tenant.
- alertas de salto de custo estão configurados, por exemplo em comparação hora a hora.
- a estratégia de degradação está clara: desligar ferramentas caras, trocar modelo ou limitar usuários ao estourar orçamento.
Cost Budget exige teto de orçamento, alertas com limites e caminho de degradação ao ultrapassar.
1.8 Isolamento de Secrets e auditoria
Vazamento de secrets é um dos incidentes de segurança mais graves em agentes. Um agente pode acessar bancos de dados, APIs de terceiros e serviços internos por meio de ferramentas. Cada chamada precisa de auditoria, e os campos actor/subject/tool/resource devem estar completos.
Checklist:
- actor/subject/tool/resource são registrados por completo.
- o armazenamento de secrets está isolado; API key e senhas de banco de dados não aparecem em variáveis de ambiente ou arquivos de configuração.
- a validação de secrets roda antes da chamada da ferramenta.
- o período de retenção de audit logs está claro (recomendado: 1 ano).
- existe um plano de rotação de chaves.
Audit logs são uma base importante para revisão de incidentes.
1.9 Validação de recuperação por Checkpoint
Um agente de longa duração precisa voltar ao estado correto após uma falha. Os checkpointers do LangGraph salvam o graph state em cada super-step e suportam time travel debugging e fault-tolerant execution, mas o caminho de recuperação precisa de teste separado.
Checklist:
- a frequência de salvamento de checkpoint está clara, em cada super-step ou nó importante.
- o teste de recuperação após falha foi executado.
- a correção do estado depois da recuperação foi verificada.
- a estratégia de limpeza de tarefas pela metade está clara.
Recuperação por checkpoint é uma capacidade básica para agentes longos.
1.10 Feature Flag e Kill Switch
Você precisa conseguir desligar o agente sem redeploy. O OpenFeature oferece um modelo padrão de feature flag, com segmentação por tenant, usuário, tipo de tarefa e rollout percentual.
Checklist:
- feature flags estão segmentadas por tenant, usuário ou tipo de tarefa.
- o kill switch faz efeito em até 1 minuto.
- rollout percentual é suportado e pode ser usado para canary release.
- monitoramento e auditoria do estado dos flags estão configurados.
Feature Flag exige controle segmentado, efeito rápido e auditoria de estado.
2. Observação do canary: o que olhar nos primeiros 10-30 minutos
Passar nos gates antes do release não significa que o canary será limpo. Um canary de agentes precisa de duas camadas de métricas: métricas de serviço (taxa de erro HTTP, tempo de resposta) e métricas do agente (tool failure rate, guardrail trip rate, cost per run, HITL queue).
2.1 Percentual de tráfego e janela de observação
Canary não se executa no feeling. Kubernetes e AWS recomendam começar com pouco tráfego, definir um período de avaliação suficiente, monitorar métricas e depois ampliar gradualmente. Parâmetros de tráfego e tempo precisam estar explícitos.
Checklist:
- o percentual inicial de tráfego está claro (recomendado: 5-10%).
- a janela mínima de observação está definida (recomendado: 10-30 minutos).
- o número mínimo de requisições dentro da janela está configurado.
- as condições para ampliar o tráfego gradualmente estão definidas.
Percentual de tráfego e janela de observação são os parâmetros básicos do canary. Se 5% do tráfego dispara alertas em 10 minutos, a nova versão tem um problema sério e deve voltar imediatamente.
2.2 Monitoramento de métricas de serviço
Taxa de erro HTTP, tempo de resposta e throughput são a primeira camada de métricas do canary, como em serviços comuns. Mas, se você olhar só essa camada, pode perder modos de falha específicos de agentes.
Checklist:
- o limite de taxa de erro HTTP 5xx está configurado (recomendado: ≤1%).
- o limite de tempo de resposta P95 está claro.
- a variação de throughput em relação à baseline é monitorada.
- uso de CPU e memória é monitorado.
- taxa de erro de rede é monitorada.
Métricas de serviço são a primeira linha de defesa, mas não são tudo. Um agente pode retornar HTTP 200 enquanto tool calls falham, guardrails são contornados ou o custo sobe de repente.
2.3 Monitoramento de métricas Agent
Métricas específicas de agentes são a segunda camada do canary. O monitoramento comum de serviços normalmente não cobre isso. Esses sinais ficam nos traces, não no HTTP log.
Checklist:
- tool failure rate é monitorado por ferramenta.
- guardrail trip rate é monitorado por tipo.
- cost per run é monitorado contra a baseline anterior.
- o tamanho da fila HITL é monitorado em tempo real.
- eval drift é monitorado quando disponível.
Métricas de agente devem ser agrupadas por ferramenta e tipo, não escondidas em uma média.
2.4 Condições de alerta e rollback automático
Um canary precisa conseguir fazer rollback automático. Não pode depender apenas de alguém olhando dashboards. A documentação da AWS recomenda usar CloudWatch alarms para disparar rollback automático, com condições e caminhos explícitos.
Checklist:
- as condições que disparam rollback automático estão definidas.
- o caminho de troca de tráfego após rollback está claro.
- a janela de observação pós-rollback está definida.
- o fluxo de confirmação humana e escalonamento está definido.
Rollback automático exige gatilhos claros, caminho de rollback claro e confirmação humana quando necessário.
3. Monitoramento pós-release: produção não termina no lançamento
Um canary aprovado não significa production readiness. Depois do release, continue monitorando qualidade de trace, uso de custo, efeito dos guardrails e eval regression para evitar queda de capacidade ou salto de custo.
3.1 Monitoramento de qualidade de Trace
Depois do release, traces podem sumir, atrasar ou perder campos, prejudicando revisão de incidentes e debugging. O monitoramento de qualidade de trace deve ser separado das métricas de serviço.
Checklist:
- a completude dos traces é monitorada, e baixa correlação de run ID frente à baseline gera alerta.
- a latência dos traces é monitorada, e gravações que demoram demais para ficar consultáveis geram alerta.
- o trace sampling rate está configurado, com downsampling em tráfego alto para reduzir custo de armazenamento.
- o custo de armazenamento de traces é monitorado.
Qualidade de trace exige baseline de completude, limite de latência e orçamento de custo.
3.2 Monitoramento contínuo de Cost e Usage
Saltos de custo são um dos incidentes de produção mais comuns em agentes. Uso anormal de tokens, mau uso de modelos e aumento repentino da frequência de tool calls podem explodir o custo. A OpenAI recomenda usage tracking e notification threshold.
Checklist:
- tendências diárias de cost são monitoradas, com comparação dia a dia e semana a semana.
- uso de token é monitorado por modelo e por usuário.
- ferramentas de alto custo estão identificadas.
- a velocidade de consumo do orçamento é monitorada.
- circuit breaker automático por estouro de orçamento está configurado.
Monitorar custo significa ter comparação de tendência, classificação por modelo e circuit breaker de orçamento.
3.3 Monitoramento contínuo de Guardrails
Mudanças na taxa de bloqueio dos guardrails podem indicar ataques ou falsos positivos. Alta no input guardrail pode significar mais prompts maliciosos; alta em falsos positivos do output guardrail pode indicar regra rígida demais.
Checklist:
- a tendência de taxa de bloqueio do input guardrail é monitorada.
- o false positive rate do output guardrail é monitorado.
- a coleta de feedback de guardrail false positive/negative está completa.
- as regras de guardrails são avaliadas regularmente.
Monitorar guardrails exige tendência de bloqueio, feedback de falsos positivos e regras atualizadas.
3.4 Eval regression contínua
Depois do release, continue verificando que a capacidade não caiu. Rode a regression suite diária ou semanalmente, alerte sobre casos com falha e adicione novas falhas à suite.
Checklist:
- execuções diárias ou semanais da regression suite são automatizadas.
- casos com falha disparam alertas automaticamente.
- novos casos com falha são adicionados à suite.
- o versionamento da regression suite está em ordem.
Eval regression significa execução regular, alerta em falhas e retorno de casos à suite.
4. Rollback de incidentes: o difícil são os efeitos colaterais das ferramentas
Rollback de agente é mais complexo que rollback de serviço comum. Em um serviço comum, muitas vezes basta voltar a versão do código. Em um agente, também é preciso tratar efeitos colaterais de ferramentas já executadas, workflows pela metade e tarefas em filas de aprovação humana.
4.1 Rollback de código
Rollback de código é o caminho mais simples. Kubernetes Deployment suporta rolling update e rollback, mas a janela de rollback deve ficar dentro de 5 minutos.
Checklist:
- o caminho de rollback da versão de código está claro.
- a troca de tráfego depois do rollback foi verificada.
- a validação pós-rollback, como smoke test, é executada.
- a janela de rollback está definida (recomendado: ≤5 minutos).
Rollback de código exige caminho claro, troca verificada e janela limitada.
4.2 Rollback de efeitos colaterais de ferramentas
A parte mais difícil do rollback de agente são os efeitos colaterais de ferramentas que já rodaram. Enviar e-mails, criar pedidos e chamar APIs externas não se desfazem porque o código voltou. É preciso separar operações idempotentes e não idempotentes e desenhar ações de compensação.
Checklist:
- operações de ferramenta já executadas estão identificadas, e todas as tool calls executadas podem ser encontradas nos traces.
- operações idempotentes podem ser repetidas com segurança.
- operações não idempotentes têm ações de compensação, como enviar e-mail corretivo, cancelar pedido ou chamar API de reversão.
- a estratégia de limpeza de tarefas pela metade está clara.
- o processo de fallback humano está definido.
Rollback de efeitos colaterais exige identificar operações executadas, julgar idempotência e desenhar compensações.
4.3 Limpeza da fila HITL
Durante o rollback, a fila de aprovação humana pode ficar com tarefas pela metade. A nova versão do agente pode ter escalado tarefas para HITL, enquanto a versão antiga talvez não precise de aprovação humana. As tarefas na fila precisam ser redistribuídas ou revertidas.
Checklist:
- tarefas na fila são identificadas por label de versão.
- a estratégia de redistribuição de tarefas está clara.
- o tratamento de timeout de aprovação está definido.
- o fluxo de confirmação humana está completo.
Limpeza da fila HITL exige identificação por versão, estratégia de redistribuição e tratamento de timeout.
4.4 Retenção de Trace e Audit logs
A revisão depois de incidentes precisa de traces e audit logs completos. O OpenTelemetry trata logs como um dos telemetry signals e pode integrá-los a logging frameworks existentes.
Checklist:
- o período de retenção de traces está claro (recomendado: 30-90 dias).
- o período de retenção de audit logs está claro (recomendado: 1 ano).
- regras de mascaramento de dados sensíveis estão completas.
- requisitos de compliance do setor são atendidos.
Retenção de Trace e Audit exige períodos adequados, regras completas de mascaramento e cobertura de compliance.
4.5 Devolver amostras com falha para a Eval Suite
Depois de um incidente, amostras com falha devem entrar na regression suite para evitar repetição. A extração deve encontrar failed cases nos traces, e humanos devem marcar o motivo da falha e o comportamento esperado.
Checklist:
- existe ferramenta ou script para extrair amostras com falha.
- a rotulagem das amostras tem confirmação humana.
- existe processo para adicionar amostras à regression suite.
- existe mecanismo para impedir que o mesmo tipo de incidente se repita.
Retornar falhas à suite exige extração, rotulagem humana, atualização da suite e correções verificadas.
Conclusão
Colocar um agente em produção exige oito dimensões além de um serviço web comum: trace, tool calls, guardrails, HITL, eval, cost, secrets e checkpoint. Essas dimensões cabem em quatro grupos de checklist:
Gates antes do release (10 checagens): completude de Trace, mascaramento de dados sensíveis, monitoramento de Guardrails, observabilidade de Tool Calls, preparação da fila HITL, Eval Regression Suite, Cost Budget e Rate Limit, isolamento de Secrets e auditoria, validação de recuperação por Checkpoint, Feature Flag e Kill Switch. Revise uma por uma antes do release. O que não passar deve bloquear o lançamento.
Observação do canary (4 checagens): percentual de tráfego e janela de observação, monitoramento de métricas de serviço, monitoramento de métricas Agent, condições de alerta e rollback automático. Um canary não olha só taxa de erro HTTP; também acompanha tool failure rate, guardrail trip rate, cost per run e HITL queue length.
Monitoramento pós-release (4 checagens): qualidade de Trace, monitoramento contínuo de Cost e Usage, monitoramento contínuo de Guardrails e Eval regression contínua. Um canary limpo não basta; o monitoramento contínuo evita queda de capacidade e saltos de custo.
Rollback de incidentes (5 checagens): rollback de código, rollback de efeitos colaterais de ferramentas, limpeza da fila HITL, retenção de Trace e Audit logs, e devolução de amostras com falha para a Eval Suite. Rollback não é só voltar a versão do código. Também envolve efeitos colaterais de ferramentas já executadas, workflows pela metade e filas de aprovação humana.
Salve esses quatro grupos de checklist como modelo e percorra todos antes de cada release. Se alguma checagem falhar, corrija antes de ir para produção, em vez de levar um problema conhecido para o canary.
Executar uma checagem de produção antes de lançar um agente
Antes de mover um agente do demo para usuários reais, verifique observabilidade, gates de release, controles de custo, segurança e rotas de rollback antes do release, durante o canary, depois do release e em incidentes.
- 1
Step 1: Correlacionar identificadores de execução
Confirme que runId, traceId, spanId, toolCallId, userId/tenantId e workflowVersion podem ser correlacionados entre logs, traces e alertas. - 2
Step 2: Checar a política de dados sensíveis
Confirme que prompts, argumentos de ferramentas, retornos de ferramentas, secrets e PII estão mascarados, com períodos de retenção e controles de acesso. - 3
Step 3: Executar avaliações de regressão
Rode a eval regression suite mais recente, cobrindo respostas finais, escolha de ferramentas, argumentos, transições de estado, permissões, custo e recuperação de falhas. - 4
Step 4: Validar rotas de falha
Valide as rotas de falha de guardrails, HITL, permissões, secret vault, cost budget, rate limit e retry budget. - 5
Step 5: Preparar chaves de rollout
Prepare feature flag, kill switch, per-tenant enablement, canary percentage, observation window e rollback conditions. - 6
Step 6: Monitorar métricas do canary
Durante o canary, monitore métricas comuns de serviço e métricas do agente juntas: tool failure, guardrail trip, cost per run, approval queue e checkpoint resume. - 7
Step 7: Confirmar a operação pós-release
Depois do release, confirme alertas, on-call, runbooks, modelos de postmortem e o processo para devolver traces com falha às avaliações. - 8
Step 8: Conter primeiro o incidente
Durante um incidente, primeiro desligue o flag ou faça rollback da versão; depois trate tarefas pela metade, efeitos colaterais externos e regression cases.
FAQ
O que devo checar antes de lançar um agente depois que o demo funciona?
Qual é a diferença entre lançar um agente e lançar um serviço web comum?
Quais métricas devo acompanhar em um canary release de agente?
Posso salvar prompts completos e argumentos de ferramentas nos traces?
Fazer rollback de um agente é só voltar a versão do código?
Guardrails podem substituir aprovação humana ou modelo de permissões?
16 min de leitura · Publicado em: 21 out 2026
Guia de engenharia de AI Agents
Se você chegou pela busca, o caminho mais rápido é ir para o post anterior ou próximo desta série.
Anterior
Como criar um dataset de avaliação de agentes: tarefas reais, trajetórias e testes de regressão
Não dependa só de benchmarks públicos. Este guia mostra como transformar tarefas reais de agentes, traces, tool calls, eventos de estado, feedback humano e casos de falha em um eval dataset para testes de regressão e release gates.
Parte 23 de 24
Próximo
Este é o post mais recente da série até agora.
Comentários
Entre com GitHub para comentar