agent-architecture-audit

Agent Architecture Audit

一套專為 Agent 系統設計的診斷工作流程，專門揭露隱藏在封裝外殼、過期記憶、重試迴圈或傳輸/渲染變異背後的失效問題。

啟用時機

下列情況【強制使用】：

• 將任何 Agent 或 LLM 驅動的應用程式發布至正式環境 (Production)
• 上線包含工具呼叫 (tool calling)、記憶體或多步驟工作流程的功能
• 在新增外殼封裝層後，Agent 的行為出現退化
• 使用者回報「Agent 表現越來越差」或「工具呼叫不穩定」
• 同一個模型在 Playground 中運作正常，但在你的外殼封裝內卻出錯
• 調試 Agent 行為超過 15 分鐘仍找不到根本原因

下列情況【尤為關鍵】：

• 新增了全新的 Prompt 層、工具定義或記憶系統
• 系統中不同的 Agent 行為不一致
• 模型昨天表現正常，今天卻開始產生幻覺 (hallucinating)
• 懷疑存在隱藏的修復/重試迴圈在默默變異回應內容

請勿用於：

• 一般程式碼除錯 — 請改用 agent-introspection-debugging
• 程式碼審查 (Code review) — 請改用特定語言的審查 Agent
• 安全性掃描 — 請改用 security-review 或 security-review/scan
• Agent 效能基準測試 — 請改用 agent-eval
• 撰寫新功能 — 請改用對應的工作流程 Skill

12 層 Agent 架構棧

每個 Agent 系統都包含以下層級，其中任何一層都可能導致最終回答遭破壞：

#	架構層 (Layer)	常見故障原因
1	System prompt	指示互相衝突、指令過度膨脹
2	Session history	注入來自先前對話輪次的過期上下文
3	Long-term memory	跨 Session 記憶污染、舊主題滲入新對話
4	Distillation	蒸餾壓縮後的產物重新作為假事實 (pseudo-facts) 輸入
5	Active recall	冗餘的重複摘要層浪費上下文空間
6	Tool selection	工具路由錯誤、模型跳過必要的工具
7	Tool execution	幻覺執行 — 聲稱調用了工具但實際並未執行
8	Tool interpretation	誤讀或忽略工具的輸出結果
9	Answer shaping	最終回應的格式遭受破壞
10	Platform rendering	傳輸層變異（UI、API、CLI 修改了原本有效的回答）
11	Hidden repair loops	靜默的 Fallback/重試 Agent 執行了第二次 LLM 調用
12	Persistence	過期的狀態或快取產物被當作即時證據重複使用

常見失效模式

1. 外殼封裝退化 (Wrapper Regression)

基礎模型本可給出正確回答，但外殼封裝層卻讓表現變差。

症狀：

• 模型在 Playground 或直接 API 調用中表現正常，但在你的 Agent 內卻出錯
• 新增 Prompt 層後，原有的行為表現出現退化
• Agent 聽起來極具信心，但答案卻錯得離譜
• 「在上次更新前明明還是好的」

2. 記憶污染 (Memory Contamination)

舊主題透過對話歷史、記憶檢索或蒸餾過程洩漏至新對話中。

症狀：

• Agent 主動提及無關的歷史主題
• 使用者的修正無法生效（舊記憶覆蓋了新修正）
• 同一 Session 的產物重新作為假事實輸入
• 記憶無限制增長，隨時間推移導致回應品質下降

3. 工具約束失效 (Tool Discipline Failure)

工具僅在 Prompt 中宣告，但未在程式碼層面強制執行。模型跳過工具或產生幻覺執行。

症狀：

• Prompt 中明定「必須使用工具 X」，但模型未調用工具就直接回答
• 工具結果看起來正確，但實際上從未被執行過
• 不同的工具爭奪相同的職責
• 模型在不該使用工具時調用，或在必須使用時跳過

4. 渲染/傳輸損壞 (Rendering/Transport Corruption)

Agent 內部的回答是正確的，但在遞送過程中被平台層改動變異。

症狀：

• 日誌顯示回答正確，但使用者看到的輸出卻損壞破碎
• Markdown 渲染、JSON 解析或串流 (Streaming) 切片破壞了原本有效的回應
• 隱藏的 Fallback Agent 在遞送前悄悄替換了回答
• Terminal 與前端 UI 之間的輸出不一致

5. 隱藏的 Agent 層級 (Hidden Agent Layers)

靜默運行的修復、重試、摘要或召回 Agent 在缺乏明確契約的情況下執行。

症狀：

• 內部生成與最終交付給使用者的輸出內容不符
• 「自動修復」迴圈默默執行了使用者毫不知情的第二次 LLM 調用
• 多個 Agent 在沒有協調的情況下同時修改相同的輸出
• 回答被看不見的層級「平滑化」或「修正」

稽核工作流程

階段 1：確定範圍 (Scope)

明確定義你正在稽核的對象：

• 目標系統 (Target system) — 是哪一個 Agent 應用程式？
• 入口點 (Entrypoints) — 使用者如何與其互動？
• 模型堆疊 (Model stack) — 使用了哪些 LLM 與提供商 (Providers)？
• 症狀現象 (Symptoms) — 使用者回報了什麼問題？
• 時間區間 (Time window) — 問題從何時開始出現？
• 待稽核層級 (Layers to audit) — 12 層中有哪些適用？

階段 2：收集證據 (Evidence Collection)

從程式碼庫中收集證據：

• 原始碼 — Agent 迴圈、工具路由、記憶寫入准入 (memory admission)、Prompt 組裝
• 日誌 (Logs) — 歷史 Session 追蹤紀錄、工具呼叫紀錄
• 設定檔 (Config) — Prompt 模板、工具 Schema、提供商設定
• 記憶檔案 — SOP、知識庫、Session 歸檔

使用 rg 搜尋常見的反模式 (Anti-patterns)：

# 工具需求僅在 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

階段 3：失效對映 (Failure Mapping)

針對每個發現項，記錄以下內容：

• 症狀 (Symptom) — 使用者看到的現象
• 作用機制 (Mechanism) — 外殼封裝如何引發該問題
• 來源層級 (Source layer) — 屬於 12 層中的哪一層
• 根本原因 (Root cause) — 最深層的肇因
• 證據引用 (Evidence) — file:line 或 log:row 參照
• 可信度 (Confidence) — 0.0 至 1.0

階段 4：修復策略 (Fix Strategy)

預設修復順序（程式碼優先，而非 Prompt 優先）：

1. 在程式碼層面控制工具需求 (Code-gate) — 以程式碼邏輯做門禁強制執行，而非僅靠 Prompt 文字
2. 移除或限縮隱藏的修復 Agent — 透過明確契約讓 Fallback 過程透明化
3. 減少上下文重複 — 避免同份資訊同時出現在 Prompt + 對話歷史 + 記憶 + 蒸餾結果中
4. 嚴格把關記憶寫入機制 — 使用者的修正 > Agent 自行斷言
5. 收緊蒸餾觸發條件 — 不要壓縮不該被壓縮的內容
6. 減少渲染過程中的變異 — 採用直通 (Pass-through) 模式，不要隨意轉換
7. 轉換為帶型別的 JSON 封套 (Typed JSON envelopes) — 採用結構化的內部數據流，而非自由格式散文

嚴重程度模型 (Severity Model)

等級	意涵	處置行動
critical	Agent 可能極具信心地下達錯誤的操作行為	下次發布前必須修復
high	Agent 經常降低正確性或穩定度	本 Sprint 內修復
medium	正確性通常能維持，但輸出脆弱或造成資源浪費	排入下個週期計畫
low	多為視覺外觀或可維護性問題	排入 Backlog

輸出格式

請按以下順序向使用者呈現診斷結果：

1. 按嚴重程度排序的發現項（最嚴重的排在最前面）
2. 架構診斷分析（哪一層破壞了什麼，以及背後原因）
3. 有序修復計畫（程式碼優先，而非 Prompt 優先）

切勿開頭就講客套話或套用公版摘要。如果系統有嚴重故障，請直接坦承說明。

快速診斷提問

稽核 Agent 系統時，請回答以下問題：

#	提問內容	若回答為「是」→
1	模型是否能跳過必要工具卻依然直接回答？	工具未於程式碼層面做門禁限制 (not code-gated)
2	舊對話內容是否會出現在新的對話輪次中？	記憶污染 (Memory contamination)
3	相同的資訊是否同時存在於 System prompt、記憶與對話歷史中？	上下文重複 (Context duplication)
4	平台是否在遞送前執行了第二次 LLM 調用？	隱藏修復迴圈 (Hidden repair loop)
5	內部生成與最終遞送給使用者的輸出是否不一致？	渲染損壞 (Rendering corruption)
6	「必須使用工具 X」的規則是否僅存在於 Prompt 文字中？	工具約束失效 (Tool discipline failure)
7	Agent 自行的獨白是否會轉化為持久化記憶？	記憶中毒 (Memory poisoning)

應避免的反模式 (Anti-Patterns)

• 在排除外殼封裝層退化的可能性之前，切勿直接歸咎於模型能力不足。
• 切勿在未展示污染路徑的情況下隨意歸咎於記憶問題。
• 切勿因為目前狀態乾淨就抹滅歷史上曾發生的異常紀錄。
• 切勿將 Markdown 純文字當作可靠的內部通訊協定。
• 當程式碼從未實施強制約束時，切勿接受僅在 Prompt 中寫入「必須使用工具」。
• 保持診斷結果直截了當、具備證據支持，並按嚴重程度排序。

Report Schema

Audits should produce structured reports following this shape:

{
  "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" }
  ]
}

相關 Skill

• agent-introspection-debugging — 調試 Agent 執行階段故障（迴圈、超時、狀態錯誤）
• agent-eval — 進行 Agent 效能正面的基準測試 (Benchmarking)
• security-review — 程式碼與設定檔的安全性稽核
• autonomous-agent-harness — 設定自主 Agent 的運作 Harness
• agent-harness-construction — 從零開始建構 Agent Harness