Auditorias — detecção de melhorias por agente

Auditorias são jobs recorrentes que analisam os logs do seu agente entre sessões para identificar pontos de melhoria. Enquanto um alerta monitora uma métrica específica que você já conhece em tempo quase real, uma auditoria investiga: num agendamento definido por você, ela executa uma passagem de políticas determinística sobre a janela de tempo e, em seguida, solta um agente de confiabilidade com IA sobre suas sessões — o agente consulta os dados diretamente, lê transcrições suspeitas e (quando necessário) executa pequenos scripts de análise, produzindo recomendações de melhoria com as evidências por trás de cada uma. Use auditorias para responder “o que devo corrigir ou melhorar nos meus agentes?” — e alertas para ser notificado no momento em que um limite específico é ultrapassado. Cada melhoria aponta para as sessões exatas e consultas que a embasam, e um único clique cria um alerta pré-preenchido para capturar recorrências. A superfície do dashboard é /<org-slug>/audits (barra lateral → analyze → audits), protegida pelas permissões audits:read / audits:write.

---

​

Como uma execução funciona

Cada execução tem duas camadas — uma base determinística e uma investigação por agente.

​

1. A passagem de políticas (determinística)

Antes de qualquer modelo ser executado, a auditoria realiza um pequeno catálogo de verificações de política em SQL sobre a janela de tempo: consultas de agregação delimitadas que identificam padrões problemáticos conhecidos e reportam quantos eventos / quais sessões corresponderam — nunca o texto correspondente em si. O catálogo inclui:

• Vazamento de segredos / credenciais em payloads de eventos — chaves de acesso AWS, chaves de API sk-…, chaves privadas PEM, tokens JWT / bearer e atribuições de credenciais do tipo KEY=….
• Marcadores de injeção de prompt — “ignore previous instructions”, “reveal your system prompt” e similares.
• PII — números com formato de CPF/SSN (heurística).
• Negações de permissão de ferramentas e loops descontrolados de chamadas a ferramentas.

Ocorrências de política são persistidas como findings (tipo policy) que sempre aparecem (nunca são cortados pelo limite por execução) e são repassados ao agente de IA como pistas iniciais. Como essa camada não requer nenhum modelo, uma auditoria ainda produz seus sinais de segurança mais importantes mesmo que o agente de IA esteja indisponível.

​

2. A investigação por agente (IA)

A auditoria então executa um agente de confiabilidade autônomo (o mesmo serviço Claude Agent SDK que alimenta o assistente do dashboard, com um prompt específico para auditoria). Com base no escopo da auditoria (agentes selecionados × ambientes) e na janela de tempo, o agente:

• executa consultas SQL somente leitura nas suas tabelas de analytics,
• lê um conjunto de transcrições de sessões representativas,
• opcionalmente escreve e executa pequenos scripts Python em um sandbox isolado dentro do pod (sem rede, sem acesso ao sistema de arquivos, segredos removidos) para análises que o SQL não consegue expressar — agrupamento de erros, cálculo de distribuições, varredura de payloads já obtidos,
• e registra cada melhoria bem fundamentada que encontrar.

O agente trabalha em várias linhas investigativas — agrupamento de erros, desvio em relação a uma linha de base, falha de objetivo em transcrições, uso inadequado de ferramentas, trade-offs de qualidade/custo e lacunas de cobertura — de acordo com a sensibilidade da auditoria (baixa / média / alta). Cada melhoria deve citar evidências: os IDs das sessões que o agente efetivamente inspecionou e/ou o SQL que executou. O servidor valida que as sessões citadas existem e descarta qualquer melhoria sem evidências válidas, garantindo que o agente investiga mas nunca inventa. Cada melhoria inclui:

• uma recomendação (a mudança concreta a ser feita — um ajuste de prompt, uma correção no schema de ferramenta, uma política de retry, um guardrail, mais cobertura de avaliação),
• um impacto esperado e uma estimativa de esforço (baixo / médio / alto),
• uma magnitude — big (um operador deve ser alertado), medium (pertence ao relatório de execução) ou small (contexto do dashboard),
• um fingerprint estável (baseado na categoria + escopo do problema, não nas sessões desta execução) para que o mesmo problema seja rastreado de execução em execução mesmo quando as evidências mudam,
• e, quando um observador determinístico simples pode capturar recorrências, um alerta sugerido que você pode criar com um clique.

A camada de IA é opcional, mas recomendada. Se nenhum agente de IA estiver configurado para o pipeline de auditoria, as execuções ainda acontecem, persistem os findings de política e reportam honestamente “análise indisponível” para a camada agêntica — em vez de passar silenciosamente sem resultados.

​

Modos de falha

Melhorias são classificadas no catálogo de modos de falha duráveis da sua organização (ou propõem um novo modo). Os modos dão aos padrões uma identidade estável entre execuções e permitem rastreamento de recorrência no longo prazo.

​

Ciclo de vida da triagem

Em uma página de finding (/audits/<id>/findings/<finding-id>): O ruído de baixo sinal é controlado por auditoria com um limite de findings por execução (top_k) sobre as melhorias agênticas. Findings de política ignoram esse limite (são relevantes para segurança e sempre exibidos). Tudo que for cortado pelo limite é contabilizado nas estatísticas da execução — nada é descartado silenciosamente.

​

Agendamento

• Cadência (schedule_interval_secs): de horária a semanal; diária é o padrão. Auditorias são deliberadamente mais espaçadas do que alertas — uma investigação agêntica varre janelas inteiras e leva minutos para executar.
• Janela: ou um lookback fixo e contínuo (ex.: “cada execução analisa os últimos 7 dias”) ou desde-a-última-execução (o padrão) — cada execução retoma de onde a anterior bem-sucedida parou, com uma pequena sobreposição para que eventos de fronteira nunca sejam perdidos.
• A próxima execução é agendada um intervalo completo após a conclusão da anterior, garantindo que uma execução lenta nunca empilhe uma segunda execução concorrente da mesma auditoria.
• Run now na página da auditoria a torna imediatamente elegível para execução.

​

Seleção de modelo

Ao criar uma auditoria, você pode escolher qual modelo a investigação utiliza, dentre a lista de modelos configurados pelo seu operador para o serviço de agente. Com um único modelo configurado, o seletor o exibe como legenda; com vários, você escolhe. Deixar sem definir utiliza o padrão configurado.

​

Notificações

Quando uma execução encontra findings novos, a auditoria notifica os canais configurados da sua organização — os mesmos canais do alerts.enabled_channels e configurações que o pipeline de alertas utiliza:

• Slack — um resumo dos novos itens significativos (big) com um link direto.
• Email — um relatório de auditoria formatado listando as novas melhorias (maior severidade, recomendações por item, link direto), enviado quando a auditoria tem um canal de email configurado e há pelo menos um finding novo.

Findings recorrentes já conhecidos não geram novas notificações.

​

Referência de configuração

As definições de auditoria são gerenciadas no dashboard (/audits/new) ou via API. As configurações por auditoria incluem a cadência e a janela de agendamento, o escopo ({"environments": [...], "agent_ids": [...]}), a sensibilidade (low / medium / high), os canais de notificação, o limite de findings por execução (top_k) e o modelo (via llm_budget.model). Configurações de servidor no nível do operador (timeouts, sandbox, URL do serviço de agente) estão documentadas em deployment.md.

​

API

Todos os endpoints têm escopo de organização e seguem a autenticação padrão por bearer key (veja api-keys.md). Para “auditoria executou mas não encontrou nada”, “o sandbox de código está desativado” e “email de auditoria não foi entregue”, veja troubleshooting.md.