Agent Architecture Audit

Agent Architecture Audit

A diagnostic workflow for agent systems that hide failures behind wrapper layers, stale memory, retry loops, or transport/rendering mutations.

When to Activate

MANDATORY for:

• Releasing any agent or LLM-powered application to production
• Shipping features with tool calling, memory, or multi-step workflows
• Agent behavior degrades after adding wrapper layers
• User reports "the agent is getting worse" or "tools are flaky"
• Same model works in playground but breaks inside your wrapper
• Debugging agent behavior for more than 15 minutes without finding root cause

Especially critical when:

• You've added new prompt layers, tool definitions, or memory systems
• Different agents in your system behave inconsistently
• The model was fine yesterday but is hallucinating today
• You suspect hidden repair/retry loops silently mutating responses

Do not use for:

• General code debugging — use agent-introspection-debugging
• Code review — use language-specific reviewer agents
• Security scanning — use security-review or security-review/scan
• Agent performance benchmarking — use agent-eval
• Writing new features — use the appropriate workflow skill

The 12-Layer Stack

Every agent system has these layers. Any of them can corrupt the answer:

Common Failure Patterns

1. Wrapper Regression

The base model produces correct answers, but the wrapper layers make it worse.

Symptoms:

• Model works fine in playground or direct API call, breaks in your agent
• Added a new prompt layer, existing behavior degraded
• Agent sounds confident but is confidently wrong
• "It was working before the last update"

2. Memory Contamination

Old topics leak into new conversations through history, memory retrieval, or distillation.

Symptoms:

• Agent brings up unrelated past topics
• User corrections don't stick (old memory overwrites new)
• Same-session artifacts re-enter as pseudo-facts
• Memory grows without bound, degrading response quality over time

3. Tool Discipline Failure

Tools are declared in the prompt but not enforced in code. The model skips them or hallucinates execution.

Symptoms:

• "Must use tool X" in prompt, but model answers without calling it
• Tool results look correct but were never actually executed
• Different tools fight over the same responsibility
• Model uses tool when it shouldn't, or skips it when it must

4. Rendering/Transport Corruption

The agent's internal answer is correct, but the platform layer mutates it during delivery.

Symptoms:

• Logs show correct answer, user sees broken output
• Markdown rendering, JSON parsing, or streaming fragments corrupt valid responses
• Hidden fallback agent quietly replaces the answer before delivery
• Output differs between terminal and UI

5. Hidden Agent Layers

Silent repair, retry, summarization, or recall agents run without explicit contracts.

Symptoms:

• Output changes between internal generation and user delivery
• "Auto-fix" loops run a second LLM pass the user doesn't know about
• Multiple agents modify the same output without coordination
• Answers get "smoothed" or "corrected" by invisible layers

Audit Workflow

Phase 1: Scope

Define what you're auditing:

• Target system — what agent application?
• Entrypoints — how do users interact with it?
• Model stack — which LLM(s) and providers?
• Symptoms — what does the user report?
• Time window — when did it start?
• Layers to audit — which of the 12 layers apply?

Phase 2: Evidence Collection

Gather evidence from the codebase:

• Source code — agent loop, tool router, memory admission, prompt assembly
• Logs — historical session traces, tool call records
• Config — prompt templates, tool schemas, provider settings
• Memory files — SOPs, knowledge bases, session archives

Use rg to search for anti-patterns:

# Tool requirements expressed only in prompt text (not code)
rg "must.*tool|必须.*工具|required.*call" --type md

# Tool execution without validation
rg "tool_call|toolCall|tool_use" --type py --type ts

# Hidden LLM calls outside main agent loop
rg "completion|chat\.create|messages\.create|llm\.invoke"

# Memory admission without user-correction priority
rg "memory.*admit|long.*term.*update|persist.*memory" --type py --type ts

# Fallback loops that run additional LLM calls
rg "fallback|retry.*llm|repair.*prompt|re-?prompt" --type py --type ts

# Silent output mutation
rg "mutate|rewrite.*response|transform.*output|shap" --type py --type ts