eunomia-bpf/agentsight

# AgentSight：使用 eBPF 进行系统级 AI agent 追踪与监控 [](https://opensource.org/licenses/MIT) [](https://github.com/eunomia-bpf/agentsight/actions/workflows/ci.yml) [](https://arxiv.org/abs/2508.02736) [](https://dl.acm.org/doi/10.1145/3766882.3767169) **English** | [中文](https://github.com/eunomia-bpf/agentsight/blob/master/README.zh-CN.md) 你的本地优先的、类似 `perf`/`top`/`strace`/`nsight` 的 AI agent 工具。查看 agent 实际上对你的机器做了什么，并将这些操作与触发它们的 prompt、模型调用和工具决策联系起来。 在 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 或任何命令周围运行 `agentsight`。AgentSight 会记录以下内容的本地 trace： - 进程和子进程、shell 命令、cwd、argv、退出状态和持续时间 - 创建、写入、截断、重命名或删除的文件 - 联系的网络目标 - prompt、响应、工具意图以及 LLM/模型/token 无需 SDK，无需代理，无需供应商集成。AgentSight 通过 eBPF 和 TLS 流量追踪进行观察，因此即使 agent 是闭源的 CLI 它也能正常工作。**✨ 无需任何代码插桩** ## 快速开始 ``` cargo install agentsight # 或：wget https://github.com/eunomia-bpf/agentsight/releases/latest/download/agentsight && chmod +x agentsight sudo agentsight top ``` 如果你将二进制文件下载到了当前目录，请运行 `sudo ./agentsight top`。 `top` 会加载 eBPF 探针，发现本地 agent，并实时将系统活动与 agent 行为关联起来。请查阅[用法](#usage)部分以获取更多示例和详细信息。 ## 🚀 为什么选择 AgentSight？ ### 传统可观测性与系统级监控 当你拥有应用程序代码时，[LangSmith](https://docs.langchain.com/langsmith/observability-concepts)、[Langfuse](https://langfuse.com/docs/observability/overview) 和 [Phoenix](https://arize.com/docs/phoenix/) 等应用级工具非常适合用于 trace、prompt、token、评估和延迟分析。当你可以通过托管端点路由 provider 流量时，[Helicone](https://docs.helicone.ai/getting-started/integration-method/gateway) 等 gateway/代理工具非常有用。 AgentSight 专注于这些工具经常遗漏的层面：agent 在系统边界实际做了什么。它无需 SDK 或代理即可观察现有的二进制文件和 CLI agent，然后将 LLM 流量与进程执行、文件访问和系统活动关联起来。 | **挑战** | **应用级工具** | **AgentSight 解决方案** | |---------------|----------------------------|------------------------| | **框架采用** | ❌ 每个应用都需要 SDK、callback 或 gateway 集成 | ✅ 开箱即用的系统 tracer，无需修改代码 | | **闭源 CLI** | ❌ 仅限于工具暴露或记录的内容 | ✅ 从外部观察现有的二进制文件和 CLI agent | | **Agent 控制的日志** | ❌ 日志可能不完整、被禁用或被修改 | ✅ 独立于应用日志的内核级事件 | | **TLS LLM 流量** | ❌ 仅当通过 SDK/代理路由时才可见 | ✅ 无需代理即可在 SSL/TLS 调用中捕获明文 | | **系统操作** | ❌ 经常遗漏子进程和本地文件活动 | ✅ 追踪进程执行、文件访问和资源使用情况 | | **跨边界行为** | ❌ trace 通常在框架/进程边界处停止 | ✅ 将 LLM 流量与进程和文件事件关联起来 | AgentSight 捕获了应用级工具遗漏的关键交互： - 绕过插桩的子进程执行 - SSL/TLS 调用边界处的明文 LLM payload - 文件操作系统资源访问 - 跨 LLM、进程和文件事件的跨边界行为 ## 用法 ### 前置条件 - **Linux 内核**：4.1+ 且支持 eBPF（推荐 5.0+） - **sudo 权限**：eBPF 探针会自动提权；你的 agent 保持非特权状态 关于源码构建，请参阅 [docs/build.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/build.md)。 ### 安装 #### Cargo 或发布二进制文件 对于本地使用，请使用 `cargo install agentsight` 安装或下载最新的 release 二进制文件，然后使用 `sudo agentsight top` 启动。当你想要记录特定命令或检查已保存的会话时，请使用下面的示例。 #### Docker Docker 对于容器、CI 或隔离的 Linux 环境很有用，但它仍然需要主机的特权访问权限才能使用 eBPF。请参阅 [docs/docker.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/docker.md)。 #### 从源码构建 构建要求和源码构建命令位于 [docs/build.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/build.md) 中。 ### 查询过往会话 每个 `stat -- ` 或 `record` 会话都会自动保存到 SQLite 中。从 perf 风格的命令开始，然后使用 `agentsight report` 进行结构化查询： ``` agentsight stat # counters for the latest saved session sudo agentsight top # live ranked view of current agent sessions agentsight top --db run.db --once # ranked view of a saved session sudo agentsight record -- claude # record a command agentsight report # high-level run summary (default) agentsight report list # all recorded sessions agentsight report prompts --json # full LLM request/response JSON agentsight report token # token usage (auto-finds latest session) agentsight report audit --json # process spawns, file opens, API calls agentsight report serve --db run.db # open the web UI for a saved session agentsight report export -o snapshot.json # export for web dashboard ``` ### Web 界面 在会话期间，访问 [http://127.0.0.1:7395](http://127.0.0.1:7395) 以查看实时流量、进程树和指标： - **时间轴视图**：http://127.0.0.1:7395/timeline - **进程树**：http://127.0.0.1:7395/tree - **事件日志**：http://127.0.0.1:7395/logs - **指标视图**：http://127.0.0.1:7395/metrics 对于已保存的 SQLite 会话，运行 `agentsight report serve --db run.db` 并打开相同的路由。

Process tree visualization for agent subprocesses and file activity

Timeline visualization for LLM, process, file, and network events

Metrics visualization for memory and CPU usage

尝试 在线演示，在浏览器中探索真实录制的 Claude Code 会话。

### 支持的 Agent `record` 会自动发现二进制文件、SSL 库和容器进程。开箱即用支持： | Agent | 命令 | |-------|---------| | Claude Code | `sudo ./agentsight record -- claude` | | Gemini CLI | `sudo ./agentsight record -- gemini` | | Python (aider, open-interpreter, …) | `sudo ./agentsight record -c python` | | Docker 容器 (OpenClaw, …) | `sudo ./agentsight record -c node --binary-path docker://openclaw` | | 任意命令 | `sudo ./agentsight record -- ` | 使用 `./agentsight discover` 发现本地已安装的内容。 有关特定于 agent 的设置、SSL 怪癖、浏览器捕获、MCP stdio 和高级标志，请参阅 [docs/agents.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/agents.md)。 ### OpenTelemetry 导出 AgentSight 可以将捕获的 LLM 调用通过 OTLP/HTTP 导出为 OpenTelemetry **GenAI** (`gen_ai.*`) span —— 为任何 agent 提供符合标准的 agent 遥测，且无需进程内插桩。 ``` sudo ./agentsight debug trace --otel --otel-endpoint http://localhost:4318 ``` 有关 collector 设置和后端集成，请参阅 [docs/otel.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/otel.md)。 ## ❓ 常见问题 **问：AgentSight 需要什么权限？** 答：eBPF 探针需要 root 权限，因此 AgentSight 可能会提示输入 `sudo`。使用 `record -- ` 或 `stat -- ` 时，受监控的 agent 仍以你的普通用户身份运行；只有探针被提权。 **问：对性能有什么影响？** 答：我们的评估报告显示，对于典型的被追踪 agent 工作负载，CPU 开销不到 3%。 **问：捕获的数据去了哪里？** 答：`record` 和 `stat -- ` 默认将会话本地存储在 SQLite 中。使用 `agentsight stat`、`agentsight top`、`agentsight report`、`agentsight report list`、`agentsight report audit --json` 和 `agentsight report token` 检查之前的运行。捕获的数据可能包含 prompt、响应、路径、header 和网络目标，因此请将日志和数据库视为敏感信息。 **问：为什么 AgentSight 没有捕获到 Claude Code、Node.js 或 Gemini CLI 的流量？** 答：这些应用程序将它们的 SSL 库（Claude/Bun 使用 BoringSSL，**所有** Node.js —— 无论是 NVM 还是系统安装 —— 都使用 OpenSSL）静态链接到自己的二进制文件中，而不是使用系统的 `libssl.so`，因此默认情况下 sslsniff 没有任何可以 hook 的东西。AgentSight 为你处理了这个问题：`record -- ` 始终会发现二进制文件，而 `record -c node` 现在也会自动发现 Node 二进制文件。对于 Claude attach 模式，请传递 `--binary-path`。请参阅“零配置：record”和“监控 Node.js AI 工具”部分。 **问：如果追踪失败，我应该检查什么？** 答：验证你使用的是支持 eBPF 的 Linux，拥有 `sudo` 或 `CAP_BPF`/`CAP_SYS_ADMIN` 权限，并且正在使用 `record -- ` 或针对静态链接 agent 使用正确的 `--binary-path`。 ### 核心资源 - [CLAUDE.md](https://github.com/eunomia-bpf/agentsight/blob/master/CLAUDE.md) - 项目指南和架构 - [docs/design/README.md](https://github.com/eunomia-bpf/agentsight/blob/master/docs/design/README.md) - 归档的设计说明和研究草稿 ## 📄 许可证 MIT 许可证 - 详见 [LICENSE](https://github.com/eunomia-bpf/agentsight/blob/master/LICENSE)。 **💡 AI 可观测性的未来**：随着 AI agent 变得更加自主并具备自我修改能力，传统的可观测性方法变得捉襟见肘。AgentSight 为大规模的 AI 安全部署提供了独立的、系统级的监控。

标签：AI代理监控, API集成, Docker镜像, LLM, Rust, Unmanaged PE, 可观测性, 可视化界面, 客户端加密, 用户代理, 系统追踪, 网络流量审计, 请求拦截