内容
# 代理可观测性
> 开源代理可观测性 — 看清你的代理做了什么，为什么失败，成本多少。在本地运行，不需要云服务。
## 快速开始
以下是在 2 分钟内连接你的代理的方法：安装软件包，将 agent-obs 添加为你的代理平台的 MCP 服务器，告诉代理自我报告，然后在仪表盘中查看会话。
### 安装
```bash
npm install -g agent-observability
```
### 1. 开放代码
将 MCP 服务器添加到你的 `opencode.json` 中：
```json
{
"mcp": {
"agent-obs": {
"type": "local",
"command": ["node", "/Users/williamweishuhn/Documents/New OpenCode Project/agent-observability/cli.js", "server"],
"enabled": true
}
}
}
```
然后将以下内容添加到你的系统提示中（例如，在 `AGENTS.md` 中）：
> 每次工具调用后，调用 agent_obs_log_tool_calls，传入工具名称、持续时间、状态、输入摘要和输出摘要。在每个任务开始时，使用 agent_obs_start_session 启动会话。
### 2. 克劳德代码
将以下内容添加到你的项目的 `.mcp.json` 中：
```json
{
"mcpServers": {
"agent-obs": {
"command": "agent-obs",
"args": ["server"]
}
}
}
```
然后添加一个项目级技能，以便克劳德自我报告。创建 `.claude/skills/agent-obs/SKILL.md`：
```markdown
---
name: agent-obs
description: 将每个工具调用报告给 agent-obs 以进行可观测性跟踪。
---
在每个任务开始时，使用 agent_obs_start_session 调用，并附上任务描述。
每次工具调用后，使用 agent_obs_log_tool_calls 调用，传入工具名称、持续时间、状态、输入摘要和输出摘要。
当任务完成后，使用 agent_obs_end_session 调用，并附上最终状态和令牌计数。
```
### 3. 光标
将以下内容添加到光标的 MCP 设置中（`~/.cursor/mcp.json` 或 设置 → MCP → 添加新的全局 MCP 服务器）：
```json
{
"mcpServers": {
"agent-obs": {
"command": "agent-obs",
"args": ["server"]
}
}
}
```
然后将相同的自我报告指令添加到你的光标规则中（`.cursorrules` 或 设置 → 规则）：
> 每次工具调用后，调用 agent_obs_log_tool_calls，传入工具名称、持续时间、状态、输入摘要和输出摘要。在每个任务开始时，使用 agent_obs_start_session 启动会话。
### 4. 自我报告模式（推荐）
上述 MCP 服务器模式是使用 agent-obs 的主要方式。代理自我报告其采取的每个操作 — 包括内置工具（读取、写入、编辑、Bash 等）这些工具从不通过 MCP，因此无法被代理捕获。自我报告还捕获了线缆协议从未见过的推理上下文：为什么选择工具、代理试图完成什么以及如何评估会话。
对于仅限 MCP 的工作负载，还有一种透明的代理模式，不需要代理协作。包装任何 MCP 服务器命令，通过它包装的每个工具调用都会自动跟踪：
```bash
agent-obs proxy --desc "fix login bug" -- npx @modelcontextprotocol/server-filesystem /tmp
```
代理捕获工具名称、参数、结果、持续时间和成功/失败状态 — 但仅限于对包装服务器的调用。使用它作为自我报告的补充，而不是替代。
所有数据都写入 `~/.agent-observability/` 中的本地 SQLite 数据库。没有数据离开你的机器。
### 5. 验证是否正常工作
```bash
agent-obs dashboard
# 打开 http://localhost:9400
# 你应该看到一个会话在你的代理运行一个任务后出现
```
仪表盘显示：
- 会话列表，带有评分徽章（A-F）、时间戳和令牌总数
- 每个会话的详细视图，显示每个工具调用、持续时间和状态
- 成本估算明细
- 跨所有工具调用输入和输出的全文搜索
- 导出为 JSON 以进行外部分析
## 架构
```
┌──────────────────────────┐
│ agent-obs 代理 │
│ （透明捕获） │
│ │
MCP 客户端 ───────▶│ 拦截工具调用 ──▶│ MCP 服务器
(克劳德/光标) │ 记录到 SQLite │ （文件系统、
└──────────┬───────────────┘ GitHub 等）
│
▼
┌──────────────────────────┐
│ agent-obs 服务器 │
│ （自我报告） │
│ │
│ 代理直接调用 obs_record_* │
│ 工具通过 MCP │
│ • 工具调用 │
│ • 令牌使用 │
│ • 决策 │
│ • 评分 │
└──────────┬───────────────┘
│
▼
┌──────────────────────────┐
│ ~/.agent-observability │
│ SQLite 数据库 │
│ │
│ • 会话 │
│ • 工具调用 │
│ • 令牌使用 │
│ • 决策 │
│ • 评分 │
└──────────┬───────────────┘
│
▼
┌──────────────────────────┐
│ agent-obs 仪表盘 │
│ （端口 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` | 获取完整的会话详情，包括所有工具调用、令牌、决策和评分。 |
| `GET` | `/api/sessions/:id/tool-calls` | 列出会话的工具调用。查询参数：`?status=error&server=filesystem` |
| `GET` | `/api/sessions/:id/tokens` | 获取会话的令牌使用历史。 |
| `GET` | `/api/sessions/:id/decisions` | 获取会话的决策点。 |
| `GET` | `/api/search` | 跨工具调用输入/输出的全文搜索。查询参数：`?q=read_file` |
| `GET` | `/api/stats` | 聚合统计：总会话、平均评分、总令牌、总成本。 |
| `POST` | `/api/export` | 将会话数据导出为 JSON。请求体：`{ "sessionIds": ["abc123"], "format": "json" }` |
| `GET` | `/api/health` | 健康检查。返回 `{ "status": "ok", "dbSize": "2.4MB", "sessionCount": 47 }` |
### MCP 工具（服务器模式）
| 工具 | 参数 | 返回 |
|------|-----------|---------|
| `obs_record_tool_calls` | `sessionId`, `toolName`, `serverName`, `duration` (毫秒), `status` (成功/错误), `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 定价估算：
| 模型 | 输入（每 100 万令牌） | 输出（每 100 万令牌） |
|-------|----------------------|------------------------|
| 克劳德 3.5 索尼特 | $3.00 | $15.00 |
| 克劳德 3 欧普斯 | $15.00 | $75.00 |
| GPT-4o | $2.50 | $10.00 |
| GPT-4 涡轮 | $10.00 | $30.00 |
成本按会话跟踪，并在仪表盘中显示。你可以通过 `~/.agent-observability/models.json` 添加自定义模型定价。
### 会话评分
每个会话根据效率和正确性获得一个字母评分：
| 评分 | 标签 | 标准 |
|-------|-------|----------|
| **A** | 清洁 | 零错误，最小令牌浪费，无不必要工具调用 |
| **B** | 次要问题 | 存在一些低效，但无失败 |
| **C** | 低效 | 过度令牌使用，冗余工具调用，可恢复错误 |
| **D** | 风险 | 存在重大问题 — 工具调用失败，高成本，错误工具选择 |
| **F** | 失败 | 错误阻止任务完成，或代理放弃会话 |
### 决策点
当代理有多个可能的操作时，它可以记录为什么选择一个而不是另一个。例如：
```json
{
"context": "需要读取文件 — 它可能位于 src/config.ts 或 lib/config.ts",
"options": ["read_file src/config.ts", "glob **/config.ts", "grep 'CONFIG' *.ts"],
"chosen": "glob **/config.ts",
"reasoning": "文件可能不在预期路径；glob 保证无论位置如何都能找到它"
}
```
决策点创建了一个审计 trail，使人们可以了解代理不仅做了什么，还可以了解为什么。
### 完整审计 trail
每个操作都有时间戳，并链接到会话。审计 trail 回答：
- 谁（哪个代理/用户）访问了什么数据？
- 每个工具调用何时发生？
- 读取或修改了什么数据？
- 操作是否获得授权？
## 评分系统
评分由代理通过 `obs_record_grade` 手动分配，或由仪表盘根据会话统计数据自动分配：
- **A = 清洁** — 未检测到问题。每个工具调用都成功，令牌使用相对任务复杂度而言是高效的，会话完成了其预期目标。
- **B = 次要问题** — 存在一些低效（例如，读取同一个文件两次，调用返回空结果的工具，然后再次尝试）。无失败。
- **C = 低效** — 需要关注。冗余工具调用，过度令牌消耗，或最终解决的可恢复错误。
- **D = 风险** — 存在重大问题。多个工具调用失败，任务成本异常高，或代理选择明显错误工具。
- **F = 失败** — 发生阻止任务完成或代理放弃会话的错误。
评分会随时间累积。`/api/stats` 端点显示您的平均评分和评分分布。
## 为什么存在
AI 代理是一个黑盒。你告诉克劳德代码或光标修复一个错误，重构一个模块，或添加一个功能 — 几分钟后你会得到一个差异。但在此期间发生了什么？它做了多少工具调用？消耗了多少令牌？读取了哪些文件？它是否尝试了三种方法后才找到一种？您完全不知道。
这不仅仅是学术好奇心。没有可观测性：
- **您无法估算成本。** 一个感觉快速的会话可能花费了 5 美元的 API 调用费用。一个感觉慢的会话可能花费了 0.50 美元。您在盲目操作。
- **您无法调试失败。** 代理生成了损坏的代码 — 是因为它读取了错误的文件？使用了废弃的 API？误解了任务？没有跟踪信息，您只能猜测。
- **您无法改进您的提示。** 代理是否读取了太多文件？调用了太多工具？在不相关的上下文上浪费了令牌？您需要数据来调整您的系统指令。
- **您无法审计访问。** 如果代理读取了包含机密或 API 密钥的文件，您应该知道。如果它进行了意外的网络调用，您需要看到它。
代理可观测性为您提供每个代理会话的飞行记录器。它回答了：发生了什么，为什么发生，及花费了多少。
## 来源
该项目结合了三个前项目的想法：
### AgentShelf（Shopify AI 就绪度扫描器）
AgentShelf 扫描 Shopify 商店的主题、应用、管理员设置和自定义代码，以生成 AI 就绪度评分。在扫描过程中，它会生成一个完整的审计 trail — 每个读取的文件、每个 API 调用、每个发现都记录有时间戳和数据源。 **采用的模式：** 具有每个操作的时间戳、数据源归属和会话级汇总的结构化审计 trail。
### Veros（FHIR 临床真相）
Veros 生成合成的纵向患者记录（FHIR R4），并使用它们来验证临床决策支持代理。其核心原则是：**“没有跟踪，就没有答案。”** AI 生成的每个临床推理片段都必须可追溯到支持它的特定数据元素（实验室结果、药物、病症）。 **采用的模式：** 决策点跟踪 — 每个代理选择都必须引用其依据，使推理可审计和有争议。
### MCP 天文台
MCP 天文台位于模型上下文协议服务器之上，评估其健康状况：正常运行时间、响应延迟、工具成功率、错误率。它实现了通过/失败门控 — 如果服务器的健康评分低于某个阈值，则会自动从代理的可用工具中排除。 **采用的模式：** 工具健康评分、会话评分（A-F）和自动降级标志。
## 开源 vs 云
此开源软件包（npm 上的 `agent-observability`）是核心引擎。它采用 MIT 许可，并将始终保持免费和本地优先：
- CLI 工具（代理、服务器、仪表盘）
- 本地 SQLite 存储
- REST API
- MCP 服务器工具
- 完整的审计 trail、成本估算和会话评分
云版本（`app.agentobservability.dev`）正在开发中，具有附加功能：
- 具有共享会话历史的团队仪表盘
- 警报（当代理的评分低于 C 时发送 Slack/电子邮件）
- 历史分析（成本趋势、效率趋势随时间变化）
- 审计 trail 的基于角色的访问控制
- SOC 2 合规的基础设施
开源软件包将始终能够独立运行。云版本是附加的，而不是替代品。
## 许可证
MIT
