agentwatch：AI Agent 运行时可观测性框架

从"黑箱焦虑"说起

你写了一个复杂的 AI Agent，用 LangGraph 编排了十几个工具调用，集成到生产环境跑了一周——然后问题来了：LLM 为什么在第三步突然"失语"？工具 A 传了错误参数，为什么没触发重试？用户说 AI "答非所问"，但日志里只有干巴巴的 token 计数……

这就是 AI Agent 开发者的集体痛点：LLM 调用是黑箱，传统 APM 工具无法理解 agent 的思维链和工具交互。CyberArk 旗下的 agentwatch 就是为解决这个问题而生的：一行代码接入，对整个 Agent 运行时了如指掌。

项目背景与开发者

agentwatch 由以色列网络安全公司 CyberArk（纳斯达克上市，NASDAQ: CYBR）主导开源。CyberArk 长期专注于身份安全与特权访问管理，其核心产品是堡垒机和密钥金库。2024 年大模型浪潮中，他们将安全领域的"可观测性"（Observability）理念引入 AI Agent 领域，于 2025 年 3 月正式开源 agentwatch。

项目核心作者 Shai Dvash 在 CyberArk 担任高级工程师，代码质量遵循 CyberArk 安全开发生命周期（SDL），整体代码库 Apache-2.0 许可，完全开源。

核心原理：一行代码 + 全链路拦截

agentwatch 的设计哲学是最小侵入式监控——只需在入口文件加一行 import agentwatch，框架即可自动拦截以下交互：

实现方式上，agentwatch 利用 Python 的 import hook 机制 动态 patch 主流 LLM SDK（如 langchain、openai、anthropic 的底层 HTTP 调用），在请求发出前和响应返回后插入钩子（hooks），将完整交互事件异步写入事件流（默认 NDJSON 格式）。

技术架构：事件驱动 + 图可视化

用户代码
  └─ import agentwatch
       └─ event_processor (异步 NDJSON 写入)
            ├─ normalizer (统一事件格式)
            ├─ graph (状态机建模)
            └─ visualization UI (本地 Web)

核心模块：

• event_processor.py：异步事件处理器，基于 aiofiles + aiohttp，将拦截事件写入本地文件流
• graph/graph.py：将线性事件流重建为有向图结构（节点=调用步骤，边=依赖关系），支持可视化渲染
• hooks/http/：底层 HTTP 拦截层，支持 httpx/aiohttp 的请求拦截，覆盖 OpenAI、Anthropic、Ollama 等主流 API
• visualization/：内置 React+TypeScript 可视化前端，通过 agentwatch ui 命令启动本地 Web 服务器

支持框架：主流 Agent 框架全覆盖

README 明确声明："Any other framework or library which uses an LLM :D"——只要用了 LLM，都能监控。

快速上手

# 安装（直接从 GitHub 安装）
pip install git+https://github.com/cyberark/agentwatch.git

# 主程序 main.py
import agentwatch

if __name__ == "__main__":
    # 你的 Agent 代码
    ...

# 启动可视化 UI
agentwatch ui
# 自动打开浏览器，展示交互图谱

可视化界面体验

agentwatch 内置的可视化 UI 值得单独一提：基于 React + TypeScript + Vite 构建，通过 agentwatch ui 启动本地 FastAPI 服务器托管前端界面。界面支持：

• 节点图：每个 LLM 调用/工具调用渲染为一个节点，节点间连线展示调用顺序与依赖关系
• 侧边栏详情：点击任意节点查看完整输入输出、耗时、token 消耗
• 实时刷新：运行期间自动更新图表，无需重启

UI 风格简洁现代（见上方 GIF 演示），CyberArk 品牌视觉一致。

局限与争议

1. 容器化缺失：无 Dockerfile/docker-compose，无法 Kubernetes 部署，团队协作时需要每位成员本地安装 Python 3.11+ 环境
2. 仅 Python：官方仅支持 Python，JavaScript/TypeScript 开发者无法使用
3. 生产级存储：事件目前写入本地 NDJSON 文件，无原生远程存储/分析后端（如不支持 Elasticsearch、ClickHouse），大规模生产部署需要自行对接
4. MCP 支持有限：仅支持 HTTP/SSE 传输层，不支持 stdio 协议的本地 MCP server

行业意义

AI Agent 赛道的可观测性是一个被低估的方向。随着 Agent 应用从 demo 走向生产，开发者对"Agent 调试工具"的需求正在爆发式增长。LangSmith、Helicone、Braintrust 等商业产品已验证了市场需求，agentwatch 以开源姿态填补了本地可私有部署的空缺。

CyberArk 将安全领域的可观测性方法论（eBPF 思路的简化版）引入 AI 领域，方向清晰，代码质量扎实，值得持续关注。