AgentSight 是基于 eBPF 的 AI Agent 可观测性工具，在零侵入业务逻辑的前提下，实现对 Agent 运行全链路的细粒度数据采集与关联分析。
如何使用 AgentSight
产品简介
AgentSight 是基于 eBPF 的 AI Agent 可观测性工具，在零侵入业务逻辑的前提下，实现对 Agent 运行全链路的细粒度数据采集与关联分析。无需修改 Agent 代码或配置代理，安装后即可自动发现系统上运行的 AI Agent，采集其大模型调用、Token 消耗与进程行为。
核心能力
AgentSight 主要包含以下能力：
Token 消耗分析：对 Agent 运行过程中的 Token 消耗进行全方位度量与归因。支持按时间段或最近 N 小时灵活查询，可自动环比对比。支持按智能体、任务、角色等多维度拆分消耗来源，分析粒度可精确至单次 LLM 调用，并支持缓存 Token（cached tokens）的单独核算。
行为审计：对 Agent 的 LLM 调用及进程执行行为的全链路记录与追踪。在数据采集中，完整留存每次 LLM 调用的提供商、模型版本等关键元数据，并同步捕获进程的命令行参数。此外，系统支持按时间维度、进程标识及事件类型进行多维度灵活筛选，并提供可视化的汇总统计分析能力。
会话中断诊断：自动检测并归因会话异常，覆盖限流、鉴权失败、流式响应截断、上下文超限、进程崩溃、重试风暴、死循环等 18 种类型，并标注严重级别，可在 Dashboard 处理或通过 CLI 查询。
优化分析：内置优化分析工作区，对指定会话运行准确性、性能、成本三个维度的深度分析（部分维度需配置分析用大模型），输出问题定位与优化建议，分析历史可持久化回看。
轨迹采集与导出：支持将 Agent 会话轨迹转换为标准 ATIF 格式（v1.7）入库与导出，供离线分析、回放与评测使用；Dashboard 提供轨迹列表与子智能体拓扑视图。
资源使用监控：按秒采集 Agent 进程的 CPU 使用率与 RSS 内存，并在 Session 中结合大模型调用、工具调用和空闲区间展示运行上下文。
因果归因：基于可复核证据辅助定位轨迹中的失败根因；证据不足时返回“无法判断”，避免强行定责。
安全审计保护：可在 Agent 卡片上配置保护目录和敏感文件，记录凭据外发风险证据。当前为审计模式，不阻断 Agent 行为。
Dashboard 可视化：Web 可视化界面，提供 Token 消耗趋势、Agent 状态监控、会话中断处理、Session 详情、优化分析与 Token 节省的直观展示。默认启用令牌认证，可安全地部署在远程服务器上，通过本地浏览器直接访问。界面支持中英双语，按浏览器首选语言自动匹配。
使用范围
AgentSight 通过内置规则自动发现并追踪以下 Agent：OpenClaw、Copilot Shell（cosh 与 cosh-ng，非 AK/SK 认证场景）、Claude Code、Codex CLI、QwenCode、Hermes、AgentScope 等。如需追踪其他 Agent，可通过配置文件自定义进程匹配规则。
对于以 Bun 构建的 Claude Code，需 2.1.113 及以上版本方可捕获其 LLM 流量。
安装方式
详情请参考快速入门。系统服务安装后，eBPF 追踪（trace）与 API 服务（serve）默认已随系统启动，无需手动执行。
对话式交互使用方式
AgentSight 提供了对话式交互 Skill，支持在各类 AI Agent 中安装使用，用户无需记忆 CLI 命令，直接通过自然语言即可完成操作：
查看 Token 消耗：如"今天 Token 用了多少？"
查询审计日志：如"帮我查一下今天的 LLM 调用记录"
排查会话异常：如“最近有没有会话中断？帮我看下原因”
如果你使用的是 Copilot Shell（cosh），该 Skill 已内置，可直接使用以上自然语言指令，系统会自动调用 AgentSight 完成查询并返回分析结论。
CLI 命令详细说明
agentsight trace — 启动 eBPF 追踪
注：该服务已在系统中默认启动，无需手动执行。
启动基于 eBPF 的 AI Agent 活动追踪。
sudo agentsight traceagentsight serve — 启动 API 及 Dashboard
注：该服务已在系统中默认启动，默认绑定 0.0.0.0:7396，无需手动执行。
启动 HTTP API 服务器，提供嵌入式 Dashboard UI。
sudo agentsight serve --host 0.0.0.0 --port 7396 该命令将绑定所有网络接口，可通过服务器公网 IP 访问：http://<服务器公网IP>:7396
请确保服务器防火墙 / 安全组已放行 7396 端口。
agentsight summary — 一站式状态概览
一条命令汇总最近时间窗内的会话与 Token 用量、按严重级别统计的中断事件、Token 节省数据，适合每日巡检或快速了解机器上 Agent 的整体运行状况。任一数据源不可用时独立降级，不影响整体输出。
agentsight summary # 最近 24 小时概览
agentsight summary --last 48 # 最近 48 小时
agentsight summary --json # JSON 输出agentsight token — 查询 Token 用量
查询 Token 用量数据。
# 查看今日用量
agentsight tokenagentsight audit — 查询审计事件
查询审计事件（LLM 调用、进程操作）。
# 查看最近事件
agentsight audit
# 按 PID 和类型过滤
agentsight audit --pid 12345 --type llm
# 汇总统计
agentsight audit --summaryagentsight discover — 扫描 Agent
发现系统上运行的 AI Agent。
# 扫描 Agent
agentsight discover
# 列出已知类型
agentsight discover --list-knownagentsight interruption — 查询与管理会话中断
agentsight interruption list # 列出最近 24 小时中断事件
agentsight interruption list --severity high # 按严重级别过滤
agentsight interruption stats # 按类型统计
agentsight interruption get <ID> # 查看单个中断详情
agentsight interruption resolve <ID> # 标记为已解决agentsight dashboard — 获取 Dashboard 访问信息
显示 Dashboard 访问地址、认证状态与登录令牌；在 ECS 环境下还会输出安全组放行指引。
agentsight dashboardDashboard 可视化界面
Dashboard 是AgentSight 的 Web 可视化界面，用于查看对话历史、Trace 详情和 Token 统计数据。Dashboard 默认启用令牌认证，首次访问需通过 agentsight dashboard 命令获取登录令牌；
Dashboard 功能
Dashboard 提供以下核心功能：
Token 消耗总览：查看当前机器在所选时间段内的 token 消耗情况。Dashboard 顶部提供时间范围选择器，可切换不同时间段；下方以统计卡片形式分别展示输入 Token、输出 Token 及总 Token 用量
Agent 状态：右侧状态栏可以查看当前 Agent 进程状态，并提供 Agent 进程 hang 住重启功能。健康卡片同时展示该 Agent 的 LLM 响应延迟指标，并保留历史活动记录，并提供进程无响应时的重启能力。安装
agentsight-enforcer后，可在运行中的 Agent 卡片上开启安全审计保护；Agent 重启后需重新开启。会话中断诊断：独立的中断处理页面，会话列表以标签形式标识异常，中断详情面板展示类型、严重级别与错误信息，支持 Resolve 或 Hide 处理。
会话语义搜索：会话列表支持用自然语言描述检索目标会话，例如“昨天报鉴权失败的那次”，由配置的分析用大模型完成语义匹配，无需精确记忆 Session ID。
Session 详情：点击"详情"查看每个 session 和 trace的 token 使用详细情况。开启资源采样后，展开 Session 可查看关联进程的 CPU 与 RSS 曲线。
优化分析：选择会话运行准确性、性能、成本维度分析，成本维度支持基于“绥路”（detour）的浪费分析，分析历史可回看。
Token 节省：与 Tokenless 组件联动（两者都安装后自动生效），展示总消耗、已降低 Token 与降低率，支持基线对比、按优化策略分解与优化前后行级对比。
数据管理
数据库管理
自动限容与清理：为防止数据库无限增长占用过多磁盘空间，系统默认设置数据库最大容量为 200 MB。当数据库大小达到上限时，会自动触发清理流程。
用户可通过环境变量 AGENTSIGHT_GENAI_DB_MAX_SIZE_MB 自定义最大容量（单位：MB），例如设置为 500 MB。
export AGENTSIGHT_GENAI_DB_MAX_SIZE_MB=500 容量超限时按行比例裁剪最旧数据，而非整库清空，历史数据不会被一次性丢弃。中断事件库默认保留 30 天、上限 100 MB，超限后同样按上限裁剪，可在配置文件中调整。
清理历史数据
如需清理历史数据，执行以下操作：
rm -rf /var/log/sysak/.agentsight然后重启 AgentSight 即可。
配置管理
默认路径：/etc/agentsight/config.json（可通过运行时 --config 指定其他路径）。
配置区块 | 说明 |
cmdline.allow / cmdline.deny | Agent 进程命令行匹配规则，决定追踪哪些进程 |
https | 域名过滤规则，仅抓取匹配域名的大模型流量 |
features | 功能开关，中断检测、轨迹采集、审计等能力按需启停 |
runtime_limits | 内存与缓冲区上限，防止资源占用无限增长 |
资源监控默认关闭。如需在 Session 中查看 CPU 与 RSS 曲线，请启用：
{
"features": {
"resource_sampling": true
}
}AgentSight 已支持 DashScope/百炼文本生成与多模态生成的原生协议。默认 https 规则应包含 dashscope.aliyuncs.com、*.maas.aliyuncs.com 与 api.openai.com。从旧版本升级时配置文件会被保留，请手动确认已包含 *.maas.aliyuncs.com。
注意：用户配置文件会完全替换内置默认规则，而非合并追加。如果自定义配置中缺少某个 Agent 的规则，该 Agent 将不会被发现；修改前请确保保留所有需要监控的 Agent 规则。配置格式升级由 schema_version 字段自动管理，程序会在版本过旧时自动备份并迁移。
常见问题
Q1：为何无法获取 OpenClaw 的 Token 消耗数据？
A： AgentSight 监控的是 openclaw-gateway 守护进程。请检查客户端与 Gateway 的连接状态是否正常。若出现以下异常日志，表明配对未成功：Gateway agent failed; falling back to embedded: Error: gateway closed (1008): pairing required
建议执行命令 openclaw devices approve 完成设备配对。
Q2：为何 Token 节省页面未显示当前 Session ID，或显示的 Token 节省量为 0？
A： 可能由以下两种原因导致：
1.当前版本暂不支持 Cosh 的 AK/SK 认证方式；
2.Session ID 格式非标准 UUID，导致系统匹配失败。
Q3：为何 Token 节省页面显示的“优化项节省量”大于“优化前 Token 数”减去“优化后 Token 数”的差值？
A： 这是因为 Agent 在每次对话时会将历史消息纳入上下文。因此，当前对话的统计结果中包含了历史消息的优化收益，导致累计节省量大于单次对话的即时差值。
Q4：为何浏览器打开 Dashboard 提示需要登录？
A：新版本默认启用令牌认证以保护数据安全。在服务器上执行 agentsight dashboard 获取登录令牌，在登录页输入即可。
Q5：Agent 已在运行，但采集不到任何 LLM 调用数据？
A：请按以下顺序排查：确认当前未使用 --no-ebpf；确认该 Agent 的命令行能被 cmdline.allow 规则命中；确认其调用的大模型域名已在 https 规则中；若使用 Bun 构建的 Claude Code，需升级到 2.1.113 及以上版本；若使用 cosh-ng，需升级到 0.24.1 及以上版本。。