auditoria-de-arquitetura-de-agente

Auditoria de Arquitetura de Agente

Um fluxo de trabalho de diagnóstico para sistemas de agente que escondem falhas por trás de camadas wrapper, memória desatualizada, loops de repetição ou mutações de transporte/renderização.

Quando Ativar

OBRIGATÓRIO para:

• Lançar qualquer aplicação baseada em agente ou LLM em produção
• Enviar funcionalidades com chamada de ferramentas, memória ou fluxos de múltiplas etapas
• O comportamento do agente degrada após adicionar camadas wrapper
• O usuário relata "o agente está piorando" ou "as ferramentas estão instáveis"
• O mesmo modelo funciona no playground, mas quebra dentro do seu wrapper
• Depurar o comportamento do agente por mais de 15 minutos sem encontrar a causa raiz

Especialmente crítico quando:

• Você adicionou novas camadas de prompt, definições de ferramentas ou sistemas de memória
• Diferentes agentes no seu sistema se comportam de forma inconsistente
• O modelo estava bem ontem, mas está alucinando hoje
• Você suspeita de loops de reparo/repetição ocultos que estão silenciosamente mutando respostas

Não use para:

• Depuração geral de código — use agent-introspection-debugging
• Revisão de código — use agentes de revisão específicos da linguagem
• Varredura de segurança — use security-review ou security-review/scan
• Benchmarking de desempenho de agentes — use agent-eval
• Escrever novas funcionalidades — use a skill de fluxo de trabalho apropriada

As 12 Camadas da Stack

Todo sistema de agente tem essas camadas. Qualquer uma delas pode corromper a resposta:

#	Camada	O Que Dá Errado
1	Prompt do sistema	Instruções conflitantes, inchaço de instruções
2	Histórico da sessão	Injeção de contexto desatualizado de turnos anteriores
3	Memória de longo prazo	Poluição entre sessões, tópicos antigos em novas conversas
4	Destilação	Artefatos comprimidos reentrando como pseudo-fatos
5	Recall ativo	Camadas de resumo redundantes desperdiçando contexto
6	Seleção de ferramenta	Roteamento de ferramenta errado, modelo pula ferramentas obrigatórias
7	Execução de ferramenta	Execução alucinada — alega chamar mas não chama
8	Interpretação de ferramenta	Saída de ferramenta mal interpretada ou ignorada
9	Modelagem da resposta	Corrupção de formato na resposta final
10	Renderização da plataforma	Mutação na camada de transporte (UI, API, CLI muta respostas válidas)
11	Loops de reparo ocultos	Agentes de fallback/repetição silenciosos executando uma segunda passagem do LLM
12	Persistência	Estado expirado ou artefatos em cache reutilizados como evidência ativa

Padrões Comuns de Falha

1. Regressão de Wrapper

O modelo base produz respostas corretas, mas as camadas wrapper as pioram.

Sintomas:

• O modelo funciona bem no playground ou chamada direta à API, mas quebra no seu agente
• Adicionou uma nova camada de prompt, o comportamento existente degradou
• O agente parece confiante, mas está confiantemente errado
• "Estava funcionando antes da última atualização"

2. Contaminação de Memória

Tópicos antigos vazam para novas conversas através do histórico, recuperação de memória ou destilação.

Sintomas:

• O agente traz à tona tópicos passados não relacionados
• Correções do usuário não persistem (memória antiga sobrescreve a nova)
• Artefatos da mesma sessão reentram como pseudo-fatos
• A memória cresce sem limites, degradando a qualidade da resposta ao longo do tempo

3. Falha de Disciplina de Ferramenta

Ferramentas são declaradas no prompt, mas não são impostas no código. O modelo as pula ou alucina a execução.

Sintomas:

• "Deve usar a ferramenta X" no prompt, mas o modelo responde sem chamá-la
• Os resultados da ferramenta parecem corretos, mas nunca foram realmente executados
• Diferentes ferramentas disputam a mesma responsabilidade
• O modelo usa a ferramenta quando não deveria, ou a pula quando deve

4. Corrupção de Renderização/Transporte

A resposta interna do agente está correta, mas a camada da plataforma a muta durante a entrega.

Sintomas:

• Logs mostram a resposta correta, o usuário vê saída quebrada
• Renderização Markdown, parsing JSON ou fragmentos de streaming corrompem respostas válidas
• Um agente de fallback oculto substitui silenciosamente a resposta antes da entrega
• A saída difere entre terminal e UI

5. Camadas de Agente Ocultas

Agentes de reparo, repetição, sumarização ou recall silenciosos são executados sem contratos explícitos.

Sintomas:

• A saída muda entre a geração interna e a entrega ao usuário
• Loops de "correção automática" executam uma segunda passagem do LLM que o usuário desconhece
• Múltiplos agentes modificam a mesma saída sem coordenação
• As respostas são "suavizadas" ou "corrigidas" por camadas invisíveis

Fluxo de Trabalho de Auditoria

Fase 1: Escopo

Defina o que você está auditando:

• Sistema alvo — qual aplicação de agente?
• Pontos de entrada — como os usuários interagem com ele?
• Stack de modelo — qual(is) LLM(s) e provedores?
• Sintomas — o que o usuário relata?
• Janela de tempo — quando começou?
• Camadas para auditar — quais das 12 camadas se aplicam?

Fase 2: Coleta de Evidências

Reúna evidências do código-fonte:

• Código-fonte — loop do agente, roteador de ferramentas, admissão de memória, montagem de prompt
• Logs — rastreamentos de sessão histórica, registros de chamadas de ferramenta
• Config — templates de prompt, esquemas de ferramenta, configurações do provedor
• Arquivos de memória — POPs, bases de conhecimento, arquivos de sessão

Use rg para pesquisar antipadrões:

# Requisitos de ferramenta expressos apenas no texto do prompt (não no código)
rg "must.*tool|必须.*工具|required.*call" --type md

# Execução de ferramenta sem validação
rg "tool_call|toolCall|tool_use" --type py --type ts

# Chamadas LLM ocultas fora do loop principal do agente
rg "completion|chat\.create|messages\.create|llm\.invoke"

# Admissão de memória sem prioridade de correção do usuário
rg "memory.*admit|long.*term.*update|persist.*memory" --type py --type ts

# Loops de fallback que executam chamadas LLM adicionais
rg "fallback|retry.*llm|repair.*prompt|re-?prompt" --type py --type ts

# Mutação silenciosa de saída
rg "mutate|rewrite.*response|transform.*output|shap" --type py --type ts

Fase 3: Mapeamento de Falhas

Para cada descoberta, documente:

• Sintoma — o que o usuário vê
• Mecanismo — como o wrapper o causa
• Camada de origem — qual das 12 camadas
• Causa raiz — a causa mais profunda
• Evidência — referência arquivo:linha ou log:linha
• Confiança — 0.0 a 1.0

Fase 4: Estratégia de Correção

Ordem de correção padrão (código primeiro, não prompt primeiro):

1. Impor requisitos de ferramenta no código — impor no código, não apenas no texto do prompt
2. Remover ou restringir agentes de reparo ocultos — tornar fallback explícito com contratos
3. Reduzir duplicação de contexto — mesma informação através de prompt + histórico + memória + destilação
4. Apertar a admissão de memória — correções do usuário > afirmações do agente
5. Apertar gatilhos de destilação — não comprimir o que não deve ser comprimido
6. Reduzir mutação de renderização — passagem direta, não transformar
7. Converter para envelopes JSON tipados — fluxo interno estruturado, não prosa livre

Modelo de Severidade

Nível	Significado	Ação
critical	O agente pode produzir com confiança comportamento operacional errado	Corrigir antes do próximo lançamento
high	O agente degrada frequentemente a correção ou a estabilidade	Corrigir nesta sprint
medium	A correção geralmente sobrevive, mas a saída é frágil ou desperdiçadora	Planejar para o próximo ciclo
low	Principalmente questões estéticas ou de manutenibilidade	Backlog

Formato de Saída

Apresente as descobertas ao usuário nesta ordem:

1. Descobertas classificadas por severidade (mais críticas primeiro)
2. Diagnóstico de arquitetura (qual camada corrompeu o quê e por quê)
3. Plano de correção ordenado (código primeiro, não prompt primeiro)

Não comece com elogios ou resumos. Se o sistema está quebrado, diga-o diretamente.

Perguntas Rápidas de Diagnóstico

Ao auditar um sistema de agente, responda a estas:

#	Pergunta	Se Sim →
1	O modelo pode pular uma ferramenta obrigatória e ainda responder?	Ferramenta não imposta no código
2	O conteúdo de conversas antigas aparece em novos turnos?	Contaminação de memória
3	A mesma informação está no prompt do sistema E na memória E no histórico?	Duplicação de contexto
4	A plataforma executa uma segunda passagem do LLM antes da entrega?	Loop de reparo oculto
5	A saída difere entre a geração interna e a entrega ao usuário?	Corrupção de renderização
6	As regras "deve usar ferramenta X" estão apenas no texto do prompt?	Falha de disciplina de ferramenta
7	O próprio monólogo do agente pode se tornar memória persistente?	Envenenamento de memória

Antipadrões a Evitar

• Evite culpar o modelo antes de falsificar regressões de camada wrapper.
• Evite culpar a memória sem mostrar o caminho de contaminação.
• Não deixe um estado atual limpo apagar um incidente histórico sujo.
• Não trate prosa Markdown como um protocolo interno confiável.
• Não aceite "deve usar ferramenta" no texto do prompt quando o código nunca o impõe.
• Mantenha as descobertas diretas, baseadas em evidências e classificadas por severidade.

Esquema de Relatório

As auditorias devem produzir relatórios estruturados seguindo este formato:

{
  "schema_version": "ecc.agent-architecture-audit.report.v1",
  "executive_verdict": {
    "overall_health": "high_risk",
    "primary_failure_mode": "string",
    "most_urgent_fix": "string"
  },
  "scope": {
    "target_name": "string",
    "model_stack": ["string"],
    "layers_to_audit": ["string"]
  },
  "findings": [
    {
      "severity": "critical|high|medium|low",
      "title": "string",
      "mechanism": "string",
      "source_layer": "string",
      "root_cause": "string",
      "evidence_refs": ["file:line"],
      "confidence": 0.0,
      "recommended_fix": "string"
    }
  ],
  "ordered_fix_plan": [
    { "order": 1, "goal": "string", "why_now": "string", "expected_effect": "string" }
  ]
}

Skills Relacionadas

• agent-introspection-debugging — Depurar falhas de tempo de execução de agentes (loops, timeouts, erros de estado)
• agent-eval — Comparar desempenho de agentes lado a lado
• security-review — Auditoria de segurança para código e configuração
• autonomous-agent-harness — Configurar operações de agentes autônomos
• agent-harness-construction — Construir harnesses de agentes do zero