调试代理很困难：我如何为 AI Kernel 构建“Flight Recorder”

Source: Dev.to

停止猜测你的代理为何产生幻觉。查询数据库。

在我的上一篇文章中，我介绍了 Agent Control Plane——我构建的一个“内核”，用于阻止代理执行 rm -rf / 之类的幻觉命令。
当普通软件应用崩溃时，你会得到堆栈跟踪；当 AI 代理出错时，你通常只会得到一个耸肩。

• 为什么它以 $0 调用了 refund 工具？
• 是 ABAC 策略阻止了它，还是 LLM 只是忘记调用？
• 上下文窗口是否已满？

“抱歉，是 LLM 的问题”并不是工程根因——那只是借口。
如果我们想把代理视为“数字员工”，就必须把它们的执行周期当作 审计日志。我在内核中加入了一个 飞行记录仪。下面说明为什么需要它，以及为什么 print() 语句不足以满足需求。

“黑盒”问题

标准的大语言模型可观测性工具（LangSmith、Arize 等）在 提示工程 方面非常有用：它们可以告诉你 token、延迟和成本。
它们却无法告诉你 治理。

我需要了解的内容：

没有这三要素，调试只能靠猜测。

实现：SQLite 就是你所需的一切

我不想启动一个复杂的可观测性栈。我相信 通过减法实现规模化。
Flight Recorder 是一个轻量级的本地 SQLite 引擎，直接挂载在内核的拦截器链上。它能够 原子化 捕获决策逻辑。

# src/agent_control_plane/flight_recorder.py
import sqlite3, json
from datetime import datetime

class FlightRecorder:
    def __init__(self, db_path="agent_blackbox.db"):
        self.conn = sqlite3.connect(db_path)
        self._init_schema()

    def _init_schema(self):
        self.conn.execute("""
            CREATE TABLE IF NOT EXISTS flight_events (
                id INTEGER PRIMARY KEY AUTOINCREMENT,
                timestamp TEXT,
                agent_id TEXT,
                tool_name TEXT,
                arguments TEXT,
                policy_verdict TEXT,
                violation_reason TEXT
            )
        """)
        self.conn.commit()

    def log_interception(self, agent_id, tool_name, args,
                         policy_verdict, violation_reason=None):
        """
        Records the 'Black Box' data of an interception event.
        """
        self.conn.execute("""
            INSERT INTO flight_events 
            (timestamp, agent_id, tool_name, arguments, policy_verdict, violation_reason)
            VALUES (?, ?, ?, ?, ?, ?)
        """, (
            datetime.now().isoformat(),
            agent_id,
            tool_name,
            json.dumps(args),
            policy_verdict,          # 'ALLOWED' or 'BLOCKED'
            violation_reason
        ))
        self.conn.commit()

这是一种乏味的技术——这正是它的意义所在。它稳健、可查询，并且就位于你的代码旁边。

查询崩溃现场

真正的力量不在于记录数据，而在于审问它。因为这只是 SQL，我可以在毫秒内回答复杂的治理问题。

示例 1 – 查找被阻止的高价值退款

SELECT timestamp, arguments, violation_reason
FROM flight_events
WHERE agent_id = 'finance_agent'
  AND policy_verdict = 'BLOCKED'
  AND tool_name = 'process_refund'
ORDER BY timestamp DESC;

示例 2 – 检测提示更改后政策违规的激增

# kernel_v1_demo.py usage
stats = recorder.get_statistics()
print(f"Total Actions: {stats['total_actions']}")
print(f"Blocked Ratio: {stats['by_verdict'].get('blocked', 0) / stats['total_actions']:.2%}")

这将“AI 调试”从一种氛围检查转变为数据科学问题。

无负担的治理

我们常常把 AI 基础设施弄得过于复杂，认为需要向量数据库来存储记忆，且需要海量云日志来做审计追踪。Flight Recorder 表明，本地文件加上严格的模式往往更优。

• 零延迟： 与内核进程内运行。
• 零成本： 由 SQLite 提供动力。
• 完全透明： 重放导致故障的完整事件序列。

亲自尝试

Kernel v1.0 附带了已启用的 Flight Recorder。克隆仓库，运行 demo_flight_recorder() 函数，观察它生成数据库文件。随后尝试破坏代理——强制它访问受保护的路径（/etc/passwd），并观看记录器当场抓住它。

🔗 GitHub Repo: imran‑siddique/agent‑control‑plane

没有治理的智能只是等待发生的 bug。Flight Recorder 正是用来捕捉它的工具。