AgentLens

🔍 AgentLens

AI エージェント向けのオープンソースの可観測性 — 改ざんを検知できる監査証跡付き
_{すべてのイベントを SHA-256 ハッシュチェーンで連結し、暗号学的に検証可能 — EU AI Act 第 12 条の記録保持要件に対応}

📖 ドキュメント · クイックスタート · ダッシュボード · ☁️ クラウド

---

📑 目次

• 設計段階から改ざんを検知
• クイックスタート
• アーキテクチャ
• 統合ガイド
• 主な機能
• ダッシュボード
• AgentLens Cloud
• パッケージ
• API の概要
• CLI
• 開発
• コントリビューション
• AgentKit エコシステム
• ライセンス

---

AgentLens はAI エージェントのフライトレコーダーです。LLM の呼び出し、ツールの実行、承認判断、エラーをすべて記録し、クエリ可能な API とリアルタイムのウェブダッシュボードで表示します。

🔒 設計段階から改ざんを検出

AgentLens が他のオブザーバビリティツールと異なる点は、各イベントが直前のイベントとSHA-256 ハッシュチェーンでつながれていることです。これは、git のコミットやブロックチェーンがつながれているのと同じ仕組みです。監査ログは追記専用で、暗号学的に検証可能です。後から単一のレコードを変更、削除、並べ替えただけでも検証に失敗し、問題の原因となったイベントが正確に示されます。EU AI Act 第12条および策定が進められているIETF Agent Audit Trailの取り組みで求められる記録保持義務に特化して設計されています。

30秒で実際に確認できます（Docker が必要です）。

git clone https://github.com/agentkitai/agentlens && cd agentlens
./demo/aha.sh

1/5  Starting AgentLens (SQLite, zero-config)…   ✓ up at http://localhost:3400
2/5  Ingesting a 5-event agent trace…            ✓ 5 events ingested
3/5  Verifying the hash chain…                    ✓ CHAIN VALID — no tampering detected
4/5  Tampering with one event in the database…   ✓ altered llm_call (changed the logged model)
5/5  Re-verifying the hash chain…                 ✗ CHAIN BROKEN — tampering detected ✅

このデモでは、実際のトレースを取り込み、チェーンを検証（成功）した後、監査ログの裏でデータベース内のレコードを直接編集し、再度検証（失敗）します。監査担当者は GET /api/audit/verify/export から署名付きの検証可能な JSON スナップショットを取得できます。

5つの連携方法から、スタックに合うものを選べます。

連携方法	言語	導入の手間	キャプチャ対象
🔭 OpenTelemetry	任意	OTLP エクスポーターの送信先を設定	gen_ai.* で計装されたあらゆるエージェント — AgentLens SDK は不要
🤖 OpenClaw プラグイン	OpenClaw	コピーして有効化	Anthropic のすべての呼び出し — プロンプト、トークン、コスト、ツール — コード不要
🐍 Python 自動計装	Python	1行	OpenAI／Anthropic／LangChain のすべての呼び出し — 決定論的
🔌 MCP サーバー	任意（MCP）	設定ブロック	Claude Desktop／Cursor からのツール呼び出し、セッション、イベント
📦 SDK	Python、TypeScript	コード	完全な制御 — イベントの記録、分析のクエリ、連携機能の構築

🚀 クイックスタート

コマンド1つで、SQLite を使ったサーバーとダッシュボードを設定不要で起動できます。

docker run -p 3400:3400 -e AUTH_DISABLED=true -e JWT_SECRET=dev-secret ghcr.io/agentkitai/agentlens
# Open http://localhost:3400

Docker を使わない場合：

npx @agentkitai/agentlens-server
# http://localhost:3400 with SQLite — zero config

AUTH_DISABLED=true は、ローカルで手早く試す場合に使用します（強化済みイメージでは、引き続き JWT_SECRET が必要です）。共有して使う場合は、AUTH_DISABLED を削除し、実際に使用する JWT_SECRET を設定して、API キーを作成してください（下記参照）。

フルスタック（Postgres + Redis、認証、TLS）— ソースから実行：

git clone https://github.com/agentkitai/agentlens && cd agentlens
cp .env.example .env
docker compose up
# production overlay (auth, restart policies):
docker compose -f docker-compose.yml -f docker-compose.prod.yml up

API キーを作成する

curl -X POST http://localhost:3400/api/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'

レスポンスに含まれる als_... キーを保存してください。表示されるのは一度だけです。その後、連携ガイドに進み、エージェントを計装してください。

📖 セットアップガイド全文 →

🏗️ アーキテクチャ

graph TB
    subgraph Agents["Your AI Agents"]
        PY["Python App<br/>(OpenAI, Anthropic, LangChain)"]
        MCP_C["MCP Client<br/>(Claude Desktop, Cursor)"]
        TS["TypeScript App"]
        OC["OpenClaw Plugin"]
    end

    PY -->|"agentlensai.init()<br/>auto-instrumentation"| SERVER
    MCP_C -->|MCP Protocol| MCP_S["@agentkitai/agentlens-mcp"]
    MCP_S -->|HTTP| SERVER
    TS -->|"@agentkitai/agentlens-sdk"| SERVER
    OC -->|HTTP| SERVER

    subgraph Server["@agentkitai/agentlens-server"]
        direction TB
        INGEST[Ingest Engine]
        QUERY[Query Engine]
        ALERT[Alert Engine]
        LLM_A[LLM Analytics]
        HEALTH[Health Scoring]
        COST[Cost Optimizer]
        REPLAY[Session Replay]
        BENCH[Benchmark Engine]
        GUARD[Guardrails]
    end

    SERVER --> DB[(SQLite / Postgres)]
    SERVER --> DASH["Dashboard<br/>(React SPA)"]

    EXT["AgentGate / FormBridge"] -->|Webhook| SERVER

🔧 連携ガイド

🔭 OpenTelemetry（あらゆる GenAI エージェントに対応 — SDK 不要）

エージェントがすでに OpenTelemetry GenAI セマンティック規約（OpenLLMetry、OpenInference、公式の OTel 計装など）で計装されている場合は、OTLP エクスポーターの送信先を AgentLens に設定するだけです。AgentLens SDK は不要です。

# Send standard OTLP/HTTP to AgentLens (JSON or protobuf, /v1/traces)
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:3400
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:3400/v1/traces

AgentLens は gen_ai.* スパンを独自のモデル形式と改ざん検出可能な監査ログにマッピングします。

OTel GenAI スパン（gen_ai.operation.name）	変換後
chat／text_completion／generate_content	対応する llm_call + llm_response（モデル、プロバイダー、メッセージ、usage.input_tokens／output_tokens、終了理由、レイテンシー、コスト）
execute_tool	tool_call（gen_ai.tool.name、gen_ai.tool.call.id、引数）
embeddings	トークン使用量を含む埋め込みイベント
invoke_agent／create_agent	エージェント呼び出しイベント

各 OTel トレースはセッションにマッピングされます（gen_ai.conversation.id がある場合はそれを使用します）。また、すべてのイベントはほかのイベントと同様にハッシュチェーンでつながれるため、あらゆる GenAI フレームワークのトレースで、同じ検証可能な監査証跡を利用できます。本番環境で OTLP エンドポイントにベアラートークンを必須にするには、OTLP_AUTH_TOKEN を設定してください。

SDK を使わない場合のコスト： OTel の GenAI 計装ではトークン数は報告されますが、コストは報告されないことがほとんどです。AgentLens は、モデルごとの100万トークンあたりの料金を使って costUsd を再構成します（モデル ID をあいまい一致で照合）。そのため、OTel のみを使うエージェントでも、SDK で計装したエージェントと同じコスト分析を利用できます。呼び出しごとのコスト属性は不要です。

🤖 OpenClaw プラグイン

OpenClaw を実行している場合、AgentLens プラグインがすべての Anthropic API 呼び出しを自動的に記録します。プロンプト、補完、トークン使用量、コスト、レイテンシ、ツール呼び出しが対象です。

cp -r packages/relay-plugin /usr/lib/node_modules/openclaw/extensions/agentlens-relay
openclaw config patch '{"plugins":{"entries":{"agentlens-relay":{"enabled":true}}}}'
openclaw gateway restart

AgentLens インスタンスが localhost:3400 で稼働していない場合は、AGENTLENS_URL を設定してください。詳細はプラグインの READMEをご覧ください。

🐍 Python 自動インストルメンテーション

1 行で、9 つのプロバイダー（OpenAI、Anthropic、LiteLLM、AWS Bedrock、Google Vertex AI、Google Gemini、Mistral AI、Cohere、Ollama）にわたるすべての LLM 呼び出しを自動的に記録します。

pip install agentlensai[all-providers]

import agentlensai

agentlensai.init(
    url="http://localhost:3400",
    api_key="als_your_key",
    agent_id="my-agent",
)
# Every LLM call is now captured automatically

主な保証事項： ✅ 決定的 · ✅ フェイルセーフ · ✅ ノンブロッキング · ✅ プライバシー保護（init(redact=True)）

📖 Python SDK の全ドキュメント →

🔌 MCP 統合

Claude Desktop、Cursor、または任意の MCP クライアントでは、設定に以下を追加してください。

{
  "mcpServers": {
    "agentlens": {
      "command": "npx",
      "args": ["@agentkitai/agentlens-mcp"],
      "env": {
        "AGENTLENS_API_URL": "http://localhost:3400",
        "AGENTLENS_API_KEY": "als_your_key_here"
      }
    }
  }
}

AgentLens には、コアの可観測性、インテリジェンスと分析、運用を網羅する22 個の MCP ツールが付属しています。MCP ツールの全リファレンス →

📖 MCP セットアップガイド →

📦 プログラムから利用する SDK

Python：

pip install agentlensai

from agentlensai import AgentLensClient
client = AgentLensClient("http://localhost:3400", api_key="als_your_key")
sessions = client.get_sessions()
analytics = client.get_llm_analytics()

TypeScript：

npm install @agentkitai/agentlens-sdk

import { AgentLensClient } from '@agentkitai/agentlens-sdk';
const client = new AgentLensClient({ baseUrl: 'http://localhost:3400', apiKey: 'als_your_key' });
const sessions = await client.getSessions();

📖 SDK リファレンス →

✨ 主な機能

• 🐍 Python 自動インストルメンテーション — agentlensai.init() が、9 つのプロバイダーにわたるすべての LLM 呼び出しを自動的に記録します。決定的なため、LLM の動作に依存しません。
• 🔌 MCP ネイティブ — MCP サーバーとして提供されます。Claude Desktop、Cursor、任意の MCP クライアントで利用できます。
• 🔭 OpenTelemetry GenAI — あらゆる OTel インストルメンテーション済みエージェント（OpenLLMetry、OpenInference、公式 OTel）から gen_ai.* OTLP トレースを取り込みます。AgentLens SDK は不要です。
• 🧠 LLM 呼び出しの追跡 — プロンプトと補完の完全な可視化、トークン使用量、コスト集計、レイテンシ測定、プライバシー保護のための秘匿化に対応します。
• 📊 リアルタイムダッシュボード — セッションのタイムライン、イベントエクスプローラー、LLM 分析、コスト追跡、アラート機能を備えています。
• 🔒 改ざん検知可能な監査証跡 — セッションごとの SHA-256 ハッシュチェーンを用いた追記専用のイベントストレージです。
• 💰 コスト追跡 — セッション、エージェント、モデルごとにトークン使用量と推定コストを追跡します。コストの急増時にアラートを通知します。
• 🚨 アラート — エラー率、コストのしきい値、レイテンシの異常、非アクティブ状態に対するルールを設定できます。
• ❤️‍🩹 ヘルススコア — トレンド追跡機能を備えた、5 つの側面からのヘルススコアリングです。
• 💡 コスト最適化 — タスクの複雑さを考慮したモデル推奨エンジンで、予測される節約額を提示します。
• 📼 セッション再生 — 過去のセッションを、コンテキストを完全に再構築しながらステップごとに再生できます。
• ⚖️ A/B ベンチマーク — Welch の t 検定とカイ二乗分析を用いて、エージェントのバリアントを統計的に比較します。
• 🛡️ ガードレール — 安全なテストのためのドライランモードを備えた、自動安全ルールです。
• 🔌 フレームワークプラグイン — LangChain、CrewAI、AutoGen、Semantic Kernel に対応し、自動検出、フェイルセーフ、ノンブロッキングを実現します。
• 🔗 AgentKit エコシステム — AgentGate、FormBridge、Lore、AgentEval と統合できます。
• 🔒 テナント分離 — テナントごとのデータスコープ設定と API キーの紐付けにより、マルチテナントに対応します。
• 🏠 セルフホスト可能 — デフォルトで SQLite を使用し、外部依存関係はありません。MIT ライセンスです。

📸 ダッシュボード

AgentLens には、エージェントを監視するためのリアルタイム Web ダッシュボードが付属しています。

📸 ダッシュボードのスクリーンショット（クリックして展開）

概要 — 主要指標を一目で確認

概要ページには、セッション、イベント、エラー、アクティブなエージェントのリアルタイム指標が表示されます。24 時間のイベントタイムラインチャート、ステータスバッジ付きの最近のセッション、最近のエラー一覧も確認できます。

セッション — すべてのエージェント実行を追跡

すべてのエージェントセッションを、エージェント名、ステータス、開始時刻、所要時間、イベント数、エラー数、総コストの列で並べ替えて確認できます。

### セッション詳細 — タイムラインとハッシュチェーン

改ざんを検知できるハッシュチェーン検証機能を備えた、イベントの全タイムラインです。イベントタイプで絞り込み、コストの内訳を確認できます。

イベントエクスプローラー — あらゆるイベントを検索・絞り込み

すべてのセッションにわたる全イベントを検索・絞り込みできるビューです。

🧠 LLM 分析 — プロンプトとコストの追跡

すべてのエージェントにわたる LLM 呼び出しの合計数、コスト、レイテンシー、トークン使用量をモデル比較とともに確認できます。

🧠 セッションタイムライン — LLM 呼び出しのペアリング

セッションのタイムラインで、モデル、トークン数、コスト、レイテンシーとともに LLM 呼び出しを確認できます。

💬 プロンプト詳細 — チャットバブルビューアー

メタデータパネルを備えたチャットバブル形式のビューアーで、プロンプトと完了内容の全体を確認できます。

❤️‍🩹 ヘルス概要 — エージェントの信頼性

すべてのエージェントについて、推移を追跡できる 5 次元のヘルススコアを表示します。

💡 コスト最適化 — モデルの推奨

LLM 呼び出しのパターンを分析し、信頼度とともに、より低コストな代替モデルを推奨します。

📼 セッションリプレイ — ステップ実行デバッガー

過去のセッションをイベントごとにステップ実行し、コンテキストを完全に再構成できます。

⚖️ ベンチマーク — エージェントの A/B テスト

統計的有意性検定を備えた A/B 実験を作成・管理できます。

🛡️ ガードレール — 自動安全ルール

トリガー履歴とアクティビティフィードを備えた自動安全ルールを作成・管理できます。

☁️ AgentLens Cloud

セルフホストしたくない場合は、AgentLens Cloud をご利用ください。インフラストラクチャー不要で、同じ SDK を使えるフルマネージド SaaS です。

import agentlensai
agentlensai.init(cloud=True, api_key="als_cloud_your_key_here", agent_id="my-agent")

• 同じ SDK で、パラメーターを 1 つ変更するだけ — url= を cloud=True に切り替えます
• マネージド Postgres — 行レベルセキュリティを備えたマルチテナント構成
• チーム向け機能 — 組織、RBAC、監査ログ
• サーバーの実行は不要 — ダッシュボードは app.agentlens.ai で利用できます

📖 クラウドセットアップガイド · 移行ガイド · トラブルシューティング

📦 パッケージ

Python（PyPI）

パッケージ	説明	PyPI
agentlensai	9 種類の LLM プロバイダー向け Python SDK と自動インストルメンテーション

TypeScript / Node.js（npm）

パッケージ	説明	npm
@agentkitai/agentlens-server	Hono API サーバーとダッシュボードの配信
@agentkitai/agentlens-mcp	エージェントのインストルメンテーション用 MCP サーバー
@agentkitai/agentlens-sdk	プログラムから利用する TypeScript クライアント
@agentkitai/agentlens-core	共有型、スキーマ、ハッシュチェーンユーティリティー
@agentkitai/agentlens-cli	コマンドラインインターフェース
@agentkitai/agentlens-dashboard	React ウェブダッシュボード（サーバーに同梱）	private

🔌 API の概要

エンドポイント	説明
POST /api/events	イベントを取り込みます（一括）
GET /api/events	フィルターを指定してイベントをクエリします
GET /api/sessions	セッションの一覧を表示します
GET /api/sessions/:id/timeline	ハッシュチェーン検証に対応したセッションのタイムライン
GET /api/analytics	時系列のバケット化されたメトリクス

API リファレンス全文 →

⌨️ CLI

npx @agentkitai/agentlens-cli health                          # Overview of all agents
npx @agentkitai/agentlens-cli health --agent my-agent          # Detailed health with dimensions
npx @agentkitai/agentlens-cli optimize                          # Cost optimization recommendations

どちらのコマンドも、機械可読な出力を得るための --format json に対応しています。すべてのオプションについては、agentlens health --help を参照してください。

🛠️ 開発

git clone https://github.com/agentkitai/agentlens.git
cd agentlens
pnpm install

pnpm typecheck && pnpm test && pnpm lint  # Run all checks
pnpm dev                                   # Start dev server

要件： Node.js ≥ 20.0.0 · pnpm ≥ 10.0.0

🤝 コントリビューション

コントリビューションを歓迎します。セットアップ手順、コーディング規約、PR の手順については、CONTRIBUTING.md を参照してください。

🧰 AgentKit エコシステム

プロジェクト	説明
AgentLens	AI エージェント向けの可観測性と改ざん検知可能な監査証跡	⬅️ こちらです
AgentGate	ヒューマン・イン・ザ・ループ承認ゲートウェイとリアクティブなガードレール
Lore	エージェント間のメモリーと教訓の共有
AgentEval	テストおよび評価フレームワーク
FormBridge	エージェントと人間が混在するモードのフォーム

📄 ライセンス

MIT © Amit Paz