agent-observability

agent-observability

开源 Agent 可观测性——了解 Agent 做了什么、为何失败以及花费了多少。可在本地运行，无需云服务。

快速开始

一条命令。无需手动配置。无需复制粘贴。

npx agent-obs@latest setup

此命令会自动检测你的 AI Agent（opencode、Claude Code、Cursor），并完成所有配置：

• 将 agent-obs 添加到你的 MCP 配置中
• 添加自我报告指令
• 告诉你接下来该做什么

然后重启你的 Agent。之后，每项操作都会自动报告。

agent-obs dashboard    # http://localhost:9400 — see your sessions appear

你将看到的内容

在 Agent 中运行任务后，仪表板会显示：

• 每次工具调用的耗时和状态
• A-F 级会话评分（Agent 的效率如何？）
• 每个会话的 Token 和美元成本
• 完整的审计记录，显示读取、编辑和执行的内容

手动设置（如果 setup 无法检测到你的 Agent）

opencode： 添加到 opencode.json：

{
  "mcp": {
    "agent-obs": {
      "command": "npx",
      "args": ["-y", "agent-obs@latest", "server"],
      "enabled": true
    }
  }
}

Claude Code： 创建 .mcp.json：

{
  "mcpServers": {
    "agent-obs": {
      "command": "npx",
      "args": ["-y", "agent-obs@latest", "server"]
    }
  }
}

Cursor： 添加到 Cursor Settings > MCP：

{
  "mcpServers": {
    "agent-obs": {
      "command": "npx",
      "args": ["-y", "agent-obs@latest", "server"]
    }
  }
}

请参阅下文的按 Agent 类型设置，了解各平台的详细说明，包括自我报告指令。

注意： 所有数据都会写入 ~/.agent-observability/ 中的本地 SQLite 数据库。数据不会离开你的设备。

代理模式（备用方案）

对于无法自行报告的 Agent，可包装任意 MCP 服务，自动追踪每次工具调用：

agent-obs proxy --desc "fix login bug" -- npx @modelcontextprotocol/server-filesystem /tmp

代理模式仅捕获 MCP 工具调用（约占 Agent 常见操作的 30%）。建议优先使用上文的 setup / MCP 服务方式。

按 Agent 类型设置

Claude Code

1. MCP 配置 — 在项目根目录中创建 .mcp.json：

{
  "mcpServers": {
    "agent-obs": {
      "command": "npx",
      "args": ["-y", "agent-obs@latest", "server"]
    }
  }
}

2. 自我报告指令 — 创建 .claude/instructions.md（或引用 .claude/skills/agent-obs/SKILL.md 下现有的 SKILL.md）：

After every tool call, report to agent-obs's log_tool_call.
Start each task with start_session. End with end_session.

3. 验证 — 运行 agent-obs dashboard，打开 http://localhost:9400，并在 Agent 完成任务后查找对应的会话。

Cursor

1. MCP 配置 — 添加到 Cursor 的 MCP 设置（~/.cursor/mcp.json，或 Settings → MCP → Add new global MCP server）：

{
  "mcpServers": {
    "agent-obs": {
      "command": "npx",
      "args": ["-y", "agent-obs@latest", "server"]
    }
  }
}

2. 自我报告指令 — 创建 .cursorrules（或 .cursor/rules/agent-obs.md）：

After every tool call, you MUST call the agent-obs MCP server's log_tool_call tool.
Include toolName, status (success/error), outputSummary, and durationMs.
Start each session with start_session and end with end_session.

3. 验证 — 运行 agent-obs dashboard，打开 http://localhost:9400，并在 Agent 完成任务后查找对应的会话。

架构

                   ┌──────────────────────────┐
                   │   agent-obs server       │
                   │    (self-reporting)      │
                   │                          │
                   │ Agent calls obs_record_* │
                   │ tools directly via MCP   │
                   │ • tool calls             │
                   │ • token usage            │
                   │ • decisions              │
                   │ • grades                 │
                   └──────────┬───────────────┘
                              │
                              ▼
                   ┌──────────────────────────┐
                   │     agent-obs proxy      │
                   │ (fallback — MCP-only)    │
                   │                          │
MCP Client ───────▶│ intercepts tool calls ──▶│ MCP Server
  (Claude/Cursor)   │ logs to SQLite           │  (filesystem,
                   └──────────┬───────────────┘   github, etc.)
                              │
                              ▼
                   ┌──────────────────────────┐
                   │   ~/.agent-observability │
                   │       SQLite DB          │
                   │                          │
                   │  • sessions              │
                   │  • tool_calls            │
                   │  • token_usage           │
                   │  • decisions             │
                   │  • grades                │
                   └──────────┬───────────────┘
                              │
                              ▼
                   ┌──────────────────────────┐
                   │   agent-obs dashboard    │
                   │     (port 9400)          │
                   │                          │
                   │  GET  /api/sessions      │
                   │  GET  /api/sessions/:id  │
                   │  GET  /api/search?q=     │
                   │  GET  /api/stats         │
                   │  POST /api/export        │
                   └──────────────────────────┘

API 参考

REST 端点（仪表板）

方法	路径	描述
GET	/api/sessions	列出所有会话。查询参数：?limit=20&offset=0&grade=B
GET	/api/sessions/:id	获取会话的完整详情，包括所有工具调用、Token、决策和评分
GET	/api/sessions/:id/tool-calls	列出会话的工具调用。查询参数：?status=error&server=filesystem
GET	/api/sessions/:id/tokens	获取会话的 Token 使用历史
GET	/api/sessions/:id/decisions	获取会话的决策点
GET	/api/search	对工具调用的输入/输出进行全文搜索。查询参数：?q=read_file
GET	/api/stats	汇总统计：会话总数、平均评分、Token 总数、总成本
POST	/api/export	将会话数据导出为 JSON。请求正文：{ "sessionIds": ["abc123"], "format": "json" }
GET	/api/health	健康检查。返回 { "status": "ok", "dbSize": "2.4MB", "sessionCount": 47 }

MCP 工具（服务端模式）

工具	参数	返回值
obs_record_tool_call	sessionId、toolName、serverName、duration（毫秒）、status（success/error）、input、output	{ "id": "call-uuid", "recorded": true }
obs_record_token_usage	sessionId、inputTokens、outputTokens、model	{ "totalTokens": 1850, "estimatedCost": "$0.023" }
obs_record_decision	sessionId、context、options、chosen、reasoning	{ "id": "decision-uuid", "recorded": true }
obs_record_grade	sessionId、grade（A/B/C/D/F）、reasoning	{ "grade": "B", "recorded": true }
obs_get_session_report	sessionId	包含所有调用、令牌、决策和评级的完整会话 JSON
obs_list_sessions	limit、offset	{ id, description, grade, createdAt, tokenTotal, estimatedCost } 数组

跟踪内容

每次工具调用

• 工具名称 — 例如 read_file、execute_command、search_code
• 服务 — 处理调用的 MCP 服务
• 时长 — 墙钟时间（毫秒）
• 状态 — success 或 error
• 输入 — 传递给工具的完整参数
• 输出 — 返回的完整结果（存储时截断至 64KB）

令牌消耗

• 输入令牌 — 提示词和上下文
• 输出令牌 — 生成的响应
• 令牌总数 — 每个会话的令牌总和
• 每次调用明细 — 每次 LLM 往返的令牌变化量

成本估算

成本根据公布的 API 定价估算：

模型	输入（每 1M 个令牌）	输出（每 1M 个令牌）
Claude 3.5 Sonnet	$3.00	$15.00
Claude 3 Opus	$15.00	$75.00
GPT-4o	$2.50	$10.00
GPT-4 Turbo	$10.00	$30.00

系统会按会话跟踪成本，并在仪表板中显示。你可以通过 ~/.agent-observability/models.json 添加自定义模型定价。

会话评级

每个会话都会根据效率和正确性获得字母评级：

评级	标签	标准
A	无瑕疵	零错误、令牌浪费极少、没有不必要的工具调用
B	小问题	存在一些低效之处，但没有失败
C	效率低下	令牌使用过多、工具调用冗余、出现可恢复的错误
D	有风险	存在重大问题——工具调用失败、成本高昂、选错工具
F	失败	错误导致任务无法完成，或 Agent 放弃了会话

决策点

当 Agent 有多个可能的操作时，可以记录选择某项操作而非其他操作的原因。示例：

{
  "context": "need to read a file — it could be at src/config.ts or lib/config.ts",
  "options": ["read_file src/config.ts", "glob **/config.ts", "grep 'CONFIG' *.ts"],
  "chosen": "glob **/config.ts",
  "reasoning": "File might not exist at the expected path; glob guarantees finding it regardless of location"
}

决策点会形成 Agent 推理的审计跟踪，不仅能了解发生了什么，还能了解为什么发生。

完整审计跟踪

每项操作都会标注时间戳并关联到一个会话。审计跟踪可以回答：

• 谁（哪个 Agent/用户）访问了哪些数据？
• 每次工具调用是什么时候发生的？
• 读取或修改了哪些数据？
• 操作是否获得授权？

评级系统

评级由 Agent 通过 obs_record_grade 手动指定，或由仪表板根据会话统计数据自动指定：

• A = 无瑕疵 — 未检测到问题。所有工具调用均成功；相对于任务复杂度而言，令牌使用高效；会话完成了既定目标。
• B = 小问题 — 存在一些低效之处（例如重复读取同一文件、调用工具但未返回结果后又再次尝试）。没有失败。
• C = 效率低下 — 需要关注。工具调用冗余、令牌消耗过多，或出现最终得到解决的可恢复错误。
• D = 有风险 — 存在重大问题。多次工具调用失败、任务成本异常高，或 Agent 选择了明显错误的工具。
• F = 失败 — 错误导致任务无法完成，或 Agent 放弃了会话。

评级会随时间累积。/api/stats 端点会显示平均评级和评级分布。

为什么要做这个项目

AI Agent 就像一个黑箱。你让 Claude Code 或 Cursor 修复一个 bug、重构一个模块或添加一项功能——几分钟后，你就会得到一份差异。但在这期间究竟发生了什么？它调用了多少次工具？消耗了多少个 token？读取了哪些文件？它是不是尝试了三种方法才选定一种？你一无所知。

这不只是学术上的好奇。缺乏可观测性会导致：

• 你无法估算成本。 一次看似很快的会话，可能消耗了 $5 的 API 调用费用；一次感觉很慢的会话，成本可能只有 $0.50。你只能在盲目操作。
• 你无法调试故障。 Agent 生成了有问题的代码——是因为它读取了错误的文件？使用了已弃用的 API？还是误解了任务？没有追踪记录，你只能猜。
• 你无法改进提示词。 Agent 是否读取了太多文件？调用了太多工具？把 token 浪费在无关上下文上？你需要数据来调整系统指令。
• 你无法审计访问情况。 如果 Agent 读取了包含机密或 API 密钥的文件，你应该知道。如果它发起了意料之外的网络调用，你需要能够查看。

Agent Observability 会为每次 Agent 会话提供飞行记录仪。它会回答：发生了什么、为什么发生，以及花费了多少。

项目来源

本项目融合了三个先前项目的理念：

AgentShelf（Shopify AI 就绪度扫描器）

AgentShelf 会扫描 Shopify 商店的主题、应用、管理设置和自定义代码，生成 AI 就绪度评分。扫描过程中，它会构建完整的审计记录——每个读取的文件、每次发起的 API 调用、每条发现都会附上时间戳和数据来源。**本项目借鉴的模式：**带有逐项操作时间戳、数据来源归属和会话级摘要的结构化审计记录。

Veros（FHIR 临床事实依据）

Veros 会生成合成的纵向患者记录（FHIR R4），并用它们验证临床决策支持 Agent。其核心原则是：“没有追踪记录，就没有答案。” AI 生成的每一段临床推理，都必须能够追溯到支持它的具体数据元素（化验结果、药物、病症）。**本项目借鉴的模式：**决策点追踪——Agent 的每项选择都必须注明依据，使推理过程可审计、可质疑。

MCP Observatory

MCP Observatory 可保障 MCP 服务的安全——在 Agent 依赖它们之前，检测其中的漏洞、架构漂移和攻击面。每周有 850+ 名开发者使用它，并以此为 MCP 服务安全提供 CI 流水线。使用 Observatory 保障 MCP 服务的安全。使用 agent-obs 追踪依赖这些服务的 Agent。 Observatory 负责验证；agent-obs 负责观测。

**本项目借鉴的模式：**工具健康度评分、会话评级（A-F）和自动降级标记。

开源版与云端版

这个开源包（npm 上的 agent-observability）是核心引擎。它采用 MIT 许可证，并将始终免费且以本地优先：

• CLI 工具（代理、服务、仪表板）
• 本地 SQLite 存储
• REST API
• MCP 服务工具
• 完整审计记录、成本估算和会话评级

云端版（app.agentobservability.dev）正在开发中，并将提供更多功能：

• 共享会话历史的团队仪表板
• 告警（Agent 评级低于 C 时通过 Slack/email 通知）
• 历史分析（数月内的成本趋势、效率趋势）
• 用于审计记录的基于角色的访问控制
• 符合 SOC 2 标准的基础设施

开源包始终可以独立运行。云端版是功能扩展，而非替代品。

许可证

MIT