agent-observability

agent-observability

オープンソースのエージェントオブザーバビリティ — エージェントが何をしたのか、なぜ失敗したのか、費用がいくらかかったのかを確認できます。ローカルで動作します。クラウドは不要です。

クイックスタート

コマンドは1つ。手動設定も、コピー＆ペーストも不要です。

npx agent-obs@latest setup

AI エージェント（opencode、Claude Code、Cursor）を自動検出し、すべてを設定します。

• MCP 設定に agent-obs を追加します
• 自己レポートの指示を追加します
• 次に行うことを案内します

その後、エージェントを再起動してください。以降、すべてのアクションが自動的にレポートされます。

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

確認できる内容

エージェントでタスクを実行すると、ダッシュボードに次の内容が表示されます。

• 各ツール呼び出しの所要時間とステータス
• セッションの評価（A〜F）（エージェントの効率を示します）
• セッションごとのトークン数とドル建てのコスト
• 読み取り、編集、実行された内容の完全な監査証跡

手動セットアップ（setup でエージェントを検出できない場合）

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-observability/ 内のローカル SQLite データベースに書き込まれます。データがマシンの外に送信されることはありません。

プロキシモード（代替手段）

自己レポートに対応していないエージェントの場合は、任意の MCP サーバーをラップすると、すべてのツール呼び出しが自動的に記録されます。

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

プロキシモードで記録されるのは MCP ツール呼び出しのみです（通常のエージェントアクションの約30％）。上記の setup／MCP サーバー方式を推奨します。

エージェント別セットアップ

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 を開いて、エージェントがタスクを完了した後にセッションが表示されていることを確認します。

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-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	すべてのツール呼び出し、トークン、判断、評価を含むセッションの詳細を取得します
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_call	sessionId, toolName, serverName, duration (ms), 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 料金に基づいて推定されます。

モデル	入力（100万トークンあたり）	出力（100万トークンあたり）
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	失敗	エラーによってタスクを完了できなかった、またはエージェントがセッションを放棄した

判断ポイント

エージェントに複数の選択肢がある場合、ある選択肢を選んだ理由を記録できます。例：

{
  "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"
}

判断ポイントによってエージェントの推論の監査証跡が作成され、何が起きたかだけでなく、その理由も把握できるようになります。

完全な監査証跡

すべてのアクションにはタイムスタンプが付与され、セッションに関連付けられます。監査証跡では、次のことを確認できます。

• 誰（どのエージェント／ユーザー）がどのデータにアクセスしたか？
• 各ツール呼び出しはいつ行われたか？
• どのデータが読み取られ、または変更されたか？
• そのアクションは許可されていたか？

評価システム

評価は、エージェントが obs_record_grade を介して手動で付けるか、セッションの統計情報に基づいてダッシュボードが自動的に付けます。

• A = 問題なし — 検出された問題はありません。すべてのツール呼び出しが成功し、タスクの複雑さに対してトークンが効率的に使われ、セッションで設定された目標が達成されました。
• B = 軽微な問題 — 非効率な点（例：同じファイルを2回読む、空の結果を返したツールを再度呼び出すなど）がいくつかあります。失敗はありません。
• C = 非効率 — 注意が必要です。ツール呼び出しの重複、過剰なトークン消費、または最終的には解決された回復可能なエラーがありました。
• D = リスクあり — 重大な問題があります。複数のツール呼び出しの失敗、タスクに対して異常に高いコスト、またはエージェントが明らかに誤ったツールを選択しました。
• F = 失敗 — タスクの完了を妨げるエラーが発生したか、エージェントがセッションを放棄しました。

評価は時間の経過とともに蓄積されます。/api/stats エンドポイントには、平均評価と評価の分布が表示されます。

これが存在する理由

AI エージェントはブラックボックスです。Claude Code や Cursor にバグの修正、モジュールのリファクタリング、機能の追加を指示すると、数分後には差分ができています。しかし、その間に実際には何が起きたのでしょうか？ツール呼び出しは何回行われたのでしょうか？トークンはいくつ消費したのでしょうか？どのファイルを読み込んだのでしょうか？最終的な方法にたどり着くまでに、3つのアプローチを試したのでしょうか？何もわかりません。

これは単なる学術的な好奇心ではありません。可観測性がなければ、次のことができません。

• コストを見積もれません。 短く感じたセッションでも、API 呼び出しに5ドルかかっているかもしれません。長く感じたセッションでも、コストは0.50ドルかもしれません。状況が見えないまま運用することになります。
• 失敗をデバッグできません。 エージェントが壊れたコードを生成しました。間違ったファイルを読んだためでしょうか？非推奨の API を使ったためでしょうか？タスクを誤解したためでしょうか？トレースがなければ、推測するしかありません。
• プロンプトを改善できません。 エージェントはファイルを読み込みすぎているでしょうか？ツールを呼び出しすぎているでしょうか？無関係なコンテキストにトークンを浪費しているでしょうか？システム指示を調整するには、データが必要です。
• アクセスを監査できません。 エージェントがシークレットや API キーを含むファイルを読み込んだ場合は、そのことを把握すべきです。予期しないネットワーク呼び出しを行った場合は、それを確認する必要があります。

Agent Observability は、すべてのエージェントセッションを記録するフライトレコーダーを提供します。何が起きたのか、なぜ起きたのか、そしてどれほどのコストがかかったのかを明らかにします。

来歴

このプロジェクトは、3つの既存プロジェクトのアイデアを組み合わせています。

AgentShelf（Shopify AI 対応状況スキャナー）

AgentShelf は、Shopify ストアのテーマ、アプリ、管理設定、カスタムコードをスキャンし、AI 対応度スコアを算出します。スキャン中に、読み込んだすべてのファイル、実行したすべての API 呼び出し、タイムスタンプとデータソースを記録したすべての検出結果を含む、完全な監査証跡を構築します。ここで採用したパターン： アクションごとのタイムスタンプ、データソースの帰属情報、セッション単位の要約を含む構造化された監査証跡。

Veros（FHIR 臨床グラウンドトゥルース）

Veros は、縦断的な合成患者記録（FHIR R4）を生成し、それを使って臨床意思決定支援エージェントを検証します。その中核となる原則は、**「トレースがなければ、回答もない」**です。AI が生成する臨床推論のすべての断片は、それを裏付ける特定のデータ要素（検査結果、薬剤、病状）までたどれる必要があります。ここで採用したパターン： 意思決定ポイントの追跡。すべてのエージェントの選択に根拠を示させることで、推論を監査可能かつ異議申し立て可能にします。

MCP Observatory

MCP Observatory は、エージェントが依存する前に、MCP サーバーの脆弱性、スキーマのドリフト、攻撃対象領域をテストして保護します。毎週850人以上の開発者に利用され、MCP サーバーのセキュリティを対象とする CI パイプラインを支えています。MCP サーバーの保護には Observatory を使い、それらに依存するエージェントのトレースには agent-obs を使ってください。 Observatory は検証し、agent-obs は観測します。

ここで採用したパターン： ツールの健全性スコア、セッション評価（A～F）、自動的な劣化フラグ。

オープンソース版とクラウド版

このオープンソースパッケージ（npm の agent-observability）は中核エンジンです。MIT ライセンスで提供され、今後も常に無料で、ローカルファーストであり続けます。

• CLI ツール（プロキシ、サーバー、ダッシュボード）
• ローカルの SQLite ストレージ
• REST API
• MCP サーバーのツール
• 完全な監査証跡、コスト見積もり、セッション評価

追加機能を備えたクラウド版（app.agentobservability.dev）を開発中です。

• セッション履歴を共有できるチームダッシュボード
• アラート（エージェントの評価が C を下回ったときの Slack／メール通知）
• 履歴分析（数か月間のコスト傾向、効率性の傾向）
• 監査証跡のロールベースアクセス制御
• SOC 2 準拠のインフラストラクチャ

オープンソースパッケージは、今後も常に単独で実行できます。クラウド版は機能を追加するものであり、置き換えるものではありません。

ライセンス

MIT