AgentWatch

agentwatch

午前2時にエージェントの群れがクラッシュしました。10体のエージェントのログはありますが、どのエージェントが連鎖を引き起こしたのか分かりません。AgentWatchが突き止めます。

ハートビートを追跡し、エージェント間のアクションを関連付け、あらゆる障害から根本原因まで遡り、シーケンス全体を再生します。あらゆるエージェントフレームワーク（CrewAI、AutoGen、LangGraph、PocketFlow、カスタム）で動作します。すべてローカルのSQLiteファイルに保存します。

開発初期段階です。問題の報告やフィードバックを歓迎します：https://github.com/nicofains1/agentwatch/issues

---

動作を見る

インストールは不要です：

npx @nicofains1/agentwatch demo

5体のエージェントで構成されるフリートを準備し、連鎖障害を発生させて、トレース全体を表示します：

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());

---

機能

ハートビート - 各エージェントは定期的に aw.report(name, status) を呼び出します。AgentWatchは稼働状況を経時的に追跡し、設定可能なしきい値に基づいてエージェントを古い状態またはオフラインとしてマークします。

エージェント間トレーシング - アクションはトレースIDと、任意の親イベントIDで関連付けられます。agent-bがagent-aから受け取った不正なデータを送信したためにagent-cが失敗した場合、チェーン全体を照会できます。

連鎖検出 - correlate(failureEventId) はあらゆる障害から根本原因まで遡り、各ステップのタイミングと出力を含むチェーン全体を返します。

アラートの重複排除 - 同じエージェントから同じ種類のアラートが一定時間内に発生した場合、1件にまとめられ、カウントが増加します。重大度は自動的に引き上げられます：info（1回） -> warning（3回） -> critical（10回）。

フォレンジック再生 - replay(traceId) は、トレース内のすべての連鎖を返します。1つのトレースが複数のエージェントにまたがった場合の事後分析に役立ちます。

OpenTelemetryエクスポート - トレースをOTELスパン（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