agent-architecture-audit

Auditoria de Arquitetura de Agente

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

Quando Ativar

OBRIGATÓRIO para:

• Lançar qualquer aplicação de agente ou baseada em LLM em produção
• Lançar funcionalidades com chamada de ferramentas, memória ou fluxos de múltiplas etapas
• O comportamento do agente degrada após adicionar camadas de 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
• Depuração do 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 mutam silenciosamente as 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 agente — use agent-eval
• Escrever novas funcionalidades — use a skill de fluxo de trabalho apropriada

A Stack de 12 Camadas

Todo sistema de agente possui 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 obsoleto 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 pseudofatos
5	Recordação ativa	Camadas de resumo redundantes desperdiçando contexto
6	Seleção de ferramentas	Roteamento errado da ferramenta, modelo ignora ferramentas necessárias
7	Execução de ferramentas	Execução alucinada — alega chamar, mas não chama
8	Interpretação de ferramentas	Saída da 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 altera respostas válidas)
11	Loops de reparo ocultos	Agentes de fallback/repetição silenciosos executando segunda passagem do LLM
12	Persistência	Estado expirado ou artefatos em cache reutilizados como evidência viva

Padrões Comuns de Falha

1. Regressão de Wrapper

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

Sintomas:

• O modelo funciona bem no playground ou chamada direta da 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 pseudofatos
• A memória cresce sem limites, degradando a qualidade da resposta ao longo do tempo

3. Falha de Disciplina de Ferramentas

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

Sintomas:

• "Deve usar 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 ignora quando deve usá-la

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

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

Sintomas:

• Logs mostram resposta correta, o usuário vê saída quebrada
• Renderização de Markdown, análise JSON ou fragmentos de streaming corrompem respostas válidas
• 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 recordação 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 "alisadas" ou "corrigidas" por camadas invisíveis

Fluxo de Trabalho de Auditoria

Fase 1: Escopo

Defina o que 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

Colete evidências da base de código:

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

Use rg para procurar antipadrões:

# Requisitos de ferramenta expressos apenas no texto do prompt (não no código)
rg "deve.*usar.*ferramenta|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 para correções 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 da 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 de 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 (primeiro o código, não o prompt):

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 o 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 os gatilhos de destilação — não comprimir o que não deve ser comprimido
6. Reduzir a 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 Gravidade

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 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 cosméticas ou de manutenibilidade	Backlog

Formato de Saída

Apresente as descobertas ao usuário nesta ordem:

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

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

Perguntas de Diagnóstico Rápido

Ao auditar um sistema de agente, responda:

#	Pergunta	Se Sim →
1	O modelo pode ignorar uma ferramenta necessá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	Regras "deve usar ferramenta X" estão apenas no texto do prompt?	Falha de disciplina de ferramentas
7	O monólogo do próprio agente pode se tornar memória persistente?	Envenenamento de memória

Antipadrões a Evitar

• Evite culpar o modelo antes de falsear regressões nas camadas de wrapper.
• Evite culpar a memória sem mostrar o caminho da 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 gravidade.

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 do agente (loops, timeouts, erros de estado)
• agent-eval — Comparar desempenho de agentes frente a frente
• security-review — Auditoria de segurança para código e configuração
• autonomous-agent-harness — Configurar operações de agente autônomo
• agent-harness-construction — Construir harnesses de agente do zero