AgentSight：基于 eBPF 的零侵入 LLM 智能体可观测性工具

English | 中文

AgentSight 是一款专为监控 LLM 智能体行为而设计的可观测性工具，通过 SSL/TLS 流量拦截和进程监控来实现。与传统的应用级插桩不同，AgentSight 使用 eBPF 技术在系统边界进行观测，以极低的性能开销提供对 AI 智能体交互的全面洞察。

零侵入 - 无需修改代码，无需引入新依赖，无需集成 SDK。开箱即用，兼容任何 AI 框架或应用。

快速开始

cargo install agentsight
# 或：wget https://github.com/eunomia-bpf/agentsight/releases/latest/download/agentsight && chmod +x agentsight
sudo agentsight top

按 model、session token、health、进程族、工具调用、文件活动和网络活动排序的实时智能体视图

如果使用下载到当前目录的二进制，请运行 sudo ./agentsight top。 AgentSight 在你忘记 sudo 时可以自动请求提权，但推荐命令仍然显式写 sudo。top 会加载 eBPF probes，也会优先读取 Claude、Codex、Gemini、OpenCode 和 OpenClaw 的本地 session 日志。

为什么选择 AgentSight？

传统可观测性 vs. 系统级监控

LangSmith、Langfuse、Phoenix 这类应用级工具很适合在你拥有应用代码时追踪 trace、prompt、token、eval 和延迟。Helicone 这类 gateway/proxy 工具则适合在你可以把 provider 流量路由到托管入口时使用。

AgentSight 关注的是这些工具经常遗漏的一层：智能体在系统边界实际做了什么。它无需 SDK 或代理，就能从应用外部观察已有二进制和 CLI 智能体，并把 LLM 流量与进程执行、文件访问和系统活动关联起来。

AgentSight 能捕获应用级工具遗漏的关键交互：

• 绕过插桩的子进程执行
• SSL/TLS 调用边界处的 LLM 明文载荷
• 文件操作和系统资源访问
• 跨 LLM、进程和文件事件的边界行为

使用方法

前置要求

• Linux 内核：4.1+ 且支持 eBPF（推荐 5.0+）
• sudo 权限：eBPF probes 会按需自动提权，智能体仍以普通用户运行

从源码构建时还需要 Rust 1.88.0+、Node.js 18+、clang、llvm 和 libelf-dev。

安装

Cargo 或 Release Binary

本地使用优先安装 CLI，然后运行 sudo agentsight top。需要记录某个具体命令或查看历史 session 时，再参考下面的使用示例。

Docker

AgentSight 通过 Docker 运行，使用 --privileged 以支持 eBPF，--pid=host 以访问宿主机进程，-v /sys:/sys:ro 用于进程监控，-v /usr:/usr:ro -v /lib:/lib:ro 用于访问 SSL 库（在共享库如 libssl.so 上附加 uprobe 所需）。示例：

# 监控 Python AI 工具
docker run --privileged --pid=host --network=host \
  -v /sys:/sys:ro -v /usr:/usr:ro -v /lib:/lib:ro \
  -v $(pwd)/logs:/logs \
  ghcr.io/eunomia-bpf/agentsight:latest \
  record --comm python --log-file /logs/record.log
 
# 监控 Claude Code（挂载 home 目录以访问二进制文件）
docker run --privileged --pid=host --network=host \
  -v /sys:/sys:ro -v /usr:/usr:ro -v /lib:/lib:ro \
  -v $HOME/.local/share/claude:/claude:ro \
  -v $(pwd)/logs:/logs \
  ghcr.io/eunomia-bpf/agentsight:latest \
  record --comm claude --binary-path /claude/versions/2.1.39 --log-file /logs/record.log

从源码构建

# 克隆仓库（含子模块）
git clone https://github.com/eunomia-bpf/agentsight.git --recursive
cd agentsight
 
# 安装系统依赖（Ubuntu/Debian）
make install
 
# 构建所有组件（前端、eBPF 和 Rust）
make build
 
# 或单独构建：
# make build-frontend  # 构建前端资源
# make build-bpf       # 构建 eBPF 程序
# make build-rust      # 构建 Rust collector

Web 界面

stat -- <command> 和 record 默认启动 Web UI。低层 debug trace 需要传入 --server：

• 时间线视图：http://127.0.0.1:7395/timeline
• 进程树：http://127.0.0.1:7395/tree
• 原始日志：http://127.0.0.1:7395/logs

进程树视图，展示智能体子进程和文件活动

时间线视图，展示 LLM、进程、文件和网络事件

指标视图，展示内存和 CPU 使用情况

支持的智能体

权限： eBPF probe 需要 root。运行实时捕获命令时使用 sudo。

record 自动发现二进制、SSL 库和容器进程，开箱即用：

使用 ./agentsight discover 发现本地已安装的智能体。

详见 docs/agents.md，了解各智能体的详细设置、SSL 注意事项、浏览器捕获、MCP stdio 和高级选项。

OpenTelemetry 导出

AgentSight 可以将捕获的 LLM 调用导出为 OpenTelemetry GenAI（gen_ai.*）span， 通过 OTLP/HTTP 发送——无需任何进程内插桩即可获得符合标准的智能体遥测数据。

sudo ./agentsight debug trace --otel --otel-endpoint http://localhost:4318

详见 docs/otel.md。

常见问题

通用问题

问：AgentSight 与传统 APM 工具有什么区别？ 答：AgentSight 使用 eBPF 在内核级运行，提供独立于应用代码的系统级监控。传统 APM 需要插桩，而插桩可能被修改或禁用。

问：性能影响如何？ 答：由于采用优化的 eBPF 内核空间数据采集，CPU 开销不到 3%。

问：智能体能否检测到自己正在被监控？ 答：检测极其困难，因为监控在内核级进行，无需修改代码。

技术问题

问：支持哪些 Linux 发行版？ 答：任何内核 4.1+（推荐 5.0+）的发行版。已在 Ubuntu 20.04+、CentOS 8+、RHEL 8+ 上测试通过。

问：能否同时监控多个智能体？ 答：可以，使用组合监控模式可以对多个智能体进行并发观测和关联分析。

问：如何过滤敏感数据？ 答：内置 Analyzer 可以移除认证头信息并过滤特定内容模式。

问：为什么 AgentSight 无法捕获 Claude Code、Node.js 或 Gemini CLI 的流量？ 答：这些应用把 SSL 库静态链接进了自己的二进制（Claude/Bun 使用 BoringSSL，所有 Node.js——NVM 和系统安装都是——使用 OpenSSL），而非使用系统 libssl.so，所以默认没有可供 sslsniff hook 的目标。AgentSight 已为你处理：record -- <command> 总会自动发现二进制，record -c node 现在也会自动发现 Node 二进制。对于 Claude attach 模式，请传 --binary-path。详见"零配置：record"和"监控 Node.js AI 工具"章节。

问：为什么 --comm claude 无法捕获 SSL 流量？ 答：Claude Code 的 SSL 流量运行在内部 "HTTP Client" 线程上，而非主 "claude" 线程。sslsniff 中的 --comm 过滤器匹配的是线程名（来自 bpf_get_current_comm()），而非进程名。使用 --binary-path 时，collector 会自动跳过 SSL 监控的 --comm 过滤。

故障排除

问："Permission denied" 错误 答：确保使用 sudo 运行或拥有 CAP_BPF 和 CAP_SYS_ADMIN 能力。

问："Failed to load eBPF program" 错误 答：验证内核版本是否满足要求（见前置要求）。如需要，请为你的架构更新 vmlinux.h。

参与贡献

欢迎贡献！克隆并构建后（见上方安装章节），你可以：

# 运行测试
make test
 
# 前端开发服务器
cd frontend && npm run dev
 
# 使用 AddressSanitizer 构建调试版本
make -C bpf debug

关键资源

• CLAUDE.md - 项目指南和架构
• docs/design/README.md - 归档的设计笔记和研究草稿

许可证

MIT 许可证 - 详见 LICENSE。

AI 可观测性的未来：随着 AI 智能体变得更加自主且具备自我修改能力，传统的可观测性方法变得力不从心。AgentSight 为大规模安全部署 AI 提供了独立的系统级监控。