Agent Architecture Audit â€?12 层架构审è®?

诊断 Agent 系统中隐藏故障的审计工作流ã€?

触发条件

**必须使用**ï¼?- Agent 行为退化（"Agent 变差äº?ã€?工具不稳å®?ï¼?- 模型åœ?playground 正常，但åœ?wrapper 中失è´?- 添加æ–?prompt å±?工具定义/记忆系统后，现有行为退åŒ?- 调试 Agent 行为超过 15 分钟未找到根å›?- 发布 Agent 应用å‰? **不适用**ï¼?- 通用代码调试 â†?ç”?agent-introspection-debugging

• 代码审查 â†?ç”?code-review
• 安全扫描 â†?ç”?security-and-hardening
• 性能基准测试 â†?ç”?performance-optimization

12 层架构栈

每个 Agent 系统都有这些层。任何一层都可能损坏答案ï¼?

5 种常见失败模�

1. Wrapper 回归

基础模型产生正确答案，但 wrapper 层使其变差ã€? **症状**ï¼?- 模型åœ?playground 或直æŽ?API 调用中正常，åœ?Agent 中失è´?- 添加æ–?prompt 层后，现有行为退åŒ?- Agent 听起来自信但自信地错è¯?- "之前还能用，更新后就不行äº?

2. 记忆污染

旧话题通过 history、memory retrieval æˆ?distillation 泄漏到新对话ã€? **症状**ï¼?- Agent 提起不相关的过去话题

• 用户纠正不持久（旧记忆覆盖新的）
• 同会话产物作为伪事实重新进入
• 记忆无限增长，降低响应质é‡?

3. 工具纪律失败

工具åœ?prompt 中声明但未在代码中强制执行。模型跳过或幻觉执行ã€? **症状**ï¼?- Prompt è¯?必须用工å…?X"，但模型不调用就回答

• 工具结果看起来正确但从未实际执行
• 不同工具争夺同一职责
• 模型不该用工具时用了，该用时跳过äº?

4. 渲染/传输损坏

Agent 内部答案正确，但平台层在传递时变异ã€? **症状**ï¼?- 日志显示正确答案，用户看到损坏输å‡?- Markdown 渲染、JSON 解析或流式传输片段损坏有效响åº?- 隐藏 fallback agent 在传递前静默替换答案

• 终端å’?UI 输出不同

5. 隐藏 Agent å±?

静默修复、重试、摘要或召回 agent 在没有明确契约的情况下运行ã€? **症状**ï¼?- 输出在内部生成和用户传递之间变åŒ?- "自动修复"循环运行用户不知道的第二æ¬?LLM 调用

• 多个 agent 在没有协调的情况下修改同一输出
• 答案被不可见å±?平滑"æˆ?纠正"

审计工作æµ?

Phase 1: Scope（范围）

定义审计目标ï¼?

• 目标系统 â€?哪个 Agent 应用ï¼?- *入口ç‚? â€?用户如何交互ï¼?- *模型æ ? â€?哪些 LLM 和提供商ï¼?- 症状 â€?用户报告什么？
• 时间窗口 â€?何时开始？
• *要审计的å±? â€?12 层中哪些适用ï¼?

Phase 2: Evidence Collection（证据收集）

从代码库收集证据ï¼?

• *源代ç ? â€?Agent 循环、工具路由、记忆准入、prompt 组装
• 日志 â€?历史会话追踪、工具调用记å½?- 配置 â€?prompt 模板、工å…?schema、提供商设置
• 记忆文件 â€?SOP、知识库、会话归æ¡? 搜索反模式：

# 工具要求仅在 prompt 文本中表达（未在代码中强制）
rg "must.*tool|必须.*工具|required.*call" --type md

# 工具执行无验è¯?rg "tool_call|toolCall|tool_use" --type py --type ts

# ä¸?Agent 循环外的隐藏 LLM 调用
rg "completion|chat\.create|messages\.create|llm\.invoke"

# 记忆准入无用户纠正优å…?rg "memory.*admit|long.*term.*update|persist.*memory" --type py --type ts

# 运行额外 LLM 调用çš?fallback 循环
rg "fallback|retry.*llm|repair.*prompt|re-?prompt" --type py --type ts

# 静默输出变异
rg "mutate|rewrite.*response|transform.*output|shap" --type py --type ts

Phase 3: Failure Mapping（失败映射）

对每个发现，记录ï¼?

• 症状 â€?用户看到什ä¹?- 机制 â€?wrapper 如何导致
• 源层 â€?12 层中的哪一å±?- **根因** â€?最深层原因
• 证据 â€?file:line æˆ?log:row 引用
• *置信åº? â€?0.0 åˆ?1.0

Phase 4: Fix Strategy（修复策略）

默认修复顺序（代码优先，é?prompt 优先）：

1. 代码门控工具要求 â€?在代码中强制，不仅在 prompt 文本
2. 移除或收窄隐藏修å¤?agent â€?ä½?fallback 明确带契çº?3. *减少上下文重å¤? â€?同一信息通过 prompt + history + memory + distillation
3. 收紧记忆准入 â€?用户纠正 > Agent 断言
4. 收紧 distillation 触发 â€?不压缩不应压缩的内容
5. 减少渲染变异 â€?直通，不转æ?7. 转换为类型化 JSON 信封 â€?结构化内部流，非自由文本

严重度模åž?

输出格式

按此顺序呈现发现ï¼?

1. **严重度排序的发现**（最严重优先ï¼?2. 架构诊断（哪层损坏了什么，为什么）
2. 排序修复计划（代码优先，é?prompt 优先ï¼? 不要以赞美或摘要开头。如果系统坏了，直接说ã€?

7 个快速诊断问é¢?

报告 Schema

审计应产出结构化报告ï¼?

{
  "schema_version": "agent-architecture-audit.report.v1",
  "executive_verdict": {
    "overall_health": "high_risk | moderate | healthy",
    "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 (1-12)",
      "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"
    }
  ]
}

与现有技能的关系

反模�

• 在证ä¼?wrapper 层回归前，不要责怪模åž?- 不要在没有显示污染路径的情况下责怪记å¿?- 不要让干净的当前状态抹去脏的历史事ä»?- 不要å°?Markdown 文本视为可信的内部协è®?- 不要接受"必须用工å…?仅在 prompt 文本中而代码从未强åˆ?- 保持发现直接、证据支持、严重度排序

*12 层架构审计：系统化诊æ–?Agent 系统的隐藏故障ã€?