AgentWatch

agentwatch

你的 Agent 集群在凌晨 2 点崩溃了。你有 10 个 Agent 的日志，却不知道是哪个 Agent 引发了连锁故障。AgentWatch 会告诉你。

它会跟踪心跳、关联不同 Agent 的操作、从任意故障反向追溯根本原因，并重放完整序列。适用于任何 Agent 框架（CrewAI、AutoGen、LangGraph、PocketFlow、自定义框架）。所有数据都存储在本地 SQLite 文件中。

目前仍处于早期阶段。欢迎提交问题和反馈：https://github.com/nicofains1/agentwatch/issues

---

查看实际效果

无需安装：

npx @nicofains1/agentwatch demo

这会初始化一个由 5 个 Agent 组成的集群、触发连锁故障，并显示完整追踪记录：

AgentWatch Fleet Dashboard
============================================================
Agents: 5 total | 3 healthy | 1 degraded | 1 error | 0 offline

Cascade Failure (4 steps, root cause: scheduler/dispatch-batch)
============================================================
[ROOT] scheduler/dispatch-batch [ok] 15ms
       {"assigned_to": "fetcher"}
       |
[  1 ] fetcher/call-api [error] 30000ms
       TIMEOUT after 30000ms
       |
[  2 ] processor/transform [error] 120ms
       Error: input is null - expected array from fetcher
       |
[FAIL] notifier/send-alert [error] 8ms
       Error: no processed data to report

---

安装

npm install @nicofains1/agentwatch

需要 Node 18+。使用 better-sqlite3（原生绑定，无需外部数据库）。

---

快速开始

import { AgentWatch } from '@nicofains1/agentwatch';

const aw = new AgentWatch(); // creates agentwatch.db in the current directory

// Report heartbeats from your agents
aw.report('agent-a', 'healthy');
aw.report('agent-b', 'healthy');

// Trace an action in agent-a
const traceId = aw.createTraceId();
const e1 = aw.trace(traceId, 'agent-a', 'fetch-data',
  'url=https://api.example.com', 'rows=150');

// Trace a dependent action in agent-b that fails
const e2 = aw.trace(traceId, 'agent-b', 'process',
  JSON.stringify({ rows: 150 }), 'Error: out of memory', {
    parentEventId: e1.id,
    status: 'error',
    durationMs: 4200,
  });

// Walk back to the root cause
const chain = aw.correlate(e2.id);
console.log(chain?.root_cause);
// -> { agent: 'agent-a', action: 'fetch-data', ... }

// Print fleet status
console.log(aw.dashboardText());

---

功能

心跳 - 每个 Agent 按计划调用 aw.report(name, status)。AgentWatch 会持续跟踪健康状况，并根据可配置的阈值将 Agent 标记为过期或离线。

跨 Agent 追踪 - 操作通过追踪 ID 和可选的父事件 ID 关联起来。如果 agent-a 提供了错误数据，agent-b 将其发送出去，导致 agent-c 失败，就可以查询完整链路。

连锁故障检测 - correlate(failureEventId) 会从任意故障反向追溯根本原因，返回完整链路，以及每一步的时间信息和输出。

告警去重 - 同一 Agent 在一段时间内发出的相同类型告警会合并为一条记录，并递增计数。严重程度会自动升级：信息（1 次）-> 警告（3 次）-> 严重（10 次）。

取证重放 - replay(traceId) 会返回某个追踪中所有连锁故障链。适用于单个追踪涉及多个 Agent 时的事后分析。

OpenTelemetry 导出 - 将追踪导出为 OTEL spans（GenAI 语义约定）。适用于 Jaeger、Grafana 或任何兼容 OTEL 的后端。需要安装可选的对等依赖。

---

CLI

npx @nicofains1/agentwatch demo                   # run the demo
npx @nicofains1/agentwatch dashboard              # fleet health overview
npx @nicofains1/agentwatch cascade <event-id>     # trace cascade from a failure
npx @nicofains1/agentwatch failures [agent]       # list recent failures
npx @nicofains1/agentwatch alerts [agent]         # list active alerts
npx @nicofains1/agentwatch replay <trace-id>      # replay all cascades in a trace
npx @nicofains1/agentwatch mcp                    # start MCP server (stdio)

设置 AGENTWATCH_DB 以指定数据库文件。默认值：当前目录下的 agentwatch.db。

---

MCP 服务

AgentWatch 可作为 MCP 服务运行。将其添加到 Claude Code 或 Cursor 配置中：

Claude Code（~/.claude/claude_desktop_config.json 或 .claude/settings.json）：

{
  "mcpServers": {
    "agentwatch": {
      "command": "npx",
      "args": ["@nicofains1/agentwatch", "mcp"],
      "env": {
        "AGENTWATCH_DB": "/absolute/path/to/agentwatch.db"
      }
    }
  }
}

Cursor（.cursor/mcp.json）：

{
  "mcpServers": {
    "agentwatch": {
      "command": "npx",
      "args": ["@nicofains1/agentwatch", "mcp"],
      "env": {
        "AGENTWATCH_DB": "/absolute/path/to/agentwatch.db"
      }
    }
  }
}

这会提供 13 个工具：agentwatch_dashboard、agentwatch_report_heartbeat、agentwatch_trace、agentwatch_cascade、agentwatch_replay、agentwatch_get_alerts、agentwatch_get_failures、agentwatch_get_trace、agentwatch_fleet_health、agentwatch_create_trace_id、agentwatch_alert、agentwatch_resolve_alert、agentwatch_dashboard_text。

---

API 参考

构造函数

const aw = new AgentWatch({
  db_path: 'agentwatch.db',        // SQLite file path
  alert_window_minutes: 30,         // de-dup window for alerts
  heartbeat_stale_minutes: 30,      // when to mark agents as offline
});

心跳

aw.report(agent, status, context?)     // status: 'healthy' | 'degraded' | 'error' | 'offline'
aw.getLatestHeartbeat(agent)           // -> Heartbeat | undefined
aw.getFleetHealth()                    // -> AgentHealth[]

追踪

aw.createTraceId()                                // -> string (UUID)
aw.trace(traceId, agent, action, input, output, {
  parentEventId?: number,
  status?: 'ok' | 'error',                        // default: 'ok'
  durationMs?: number,
})                                                // -> TraceEvent
aw.getTraceEvents(traceId)                        // -> TraceEvent[]
aw.getRecentFailures(agent?, limit?)              // -> TraceEvent[]

连锁故障检测

aw.correlate(failureEventId)    // -> CascadeChain | null
aw.replay(traceId)              // -> CascadeChain[]

告警

aw.alert(agent, alertType, message)
aw.resolveAlert(alertId)
aw.activeAlerts(agent?)         // -> Alert[]

仪表板

aw.dashboard()      // -> DashboardOutput (structured)
aw.dashboardText()  // -> string (formatted for terminal)

OpenTelemetry 导出

需要安装可选的对等依赖 @opentelemetry/api 和 @opentelemetry/sdk-trace-base。

await aw.exportTraceToOtel(traceId, { serviceName: 'my-agents' });
await aw.exportRecentToOtel(1); // last 1 hour

---

存储

通过 better-sqlite3 使用 SQLite。首次使用时会自动创建数据库文件。已启用 WAL 模式以支持并发读取。

数据表：heartbeats、trace_events、alerts。

---

许可证

MIT