agent-replay

agent-replay-mcp

エージェントのセッション記録と再生に対応する MCP サーバーです。セッションの比較と逸脱検出により、非決定的なエージェントの動作をデバッグできます。

エージェントが実行するすべてのアクションを記録し、セッションをステップごとに再生し、2 つの実行を比較して動作のリグレッションを検出し、エージェントが期待される出力から逸脱した箇所を正確に特定できます。

インストール

npx agent-replay-mcp

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "agent-replay": {
      "command": "npx",
      "args": ["agent-replay-mcp"]
    }
  }
}

ソースから

git clone https://github.com/mdfifty50-boop/agent-replay-mcp.git
cd agent-replay-mcp
npm install
node src/index.js

ツール

record_session

エージェントセッションのすべてのアクションの記録を開始します。

パラメーター	型	デフォルト	説明
agent_id	string	必須	一意のエージェント識別子
metadata	object	{}	任意のメタデータ（タスク、モデル、環境）

他のツールで使用する session_id を返します。

stop_recording

記録を停止し、セッションの概要を返します。

パラメーター	型	説明
session_id	string	record_session で取得したセッション ID

返される内容：アクション数、合計所要時間、アクション種別ごとの内訳。

log_action

記録中のセッションで単一のアクションを記録します。

パラメーター	型	デフォルト	説明
session_id	string	必須	アクティブなセッション ID
action_type	string	必須	種別（tool_call、llm_response、decision、error）
input	any	必須	アクションへの入力
output	any	必須	アクションの出力
reasoning	string	""	このステップにおけるエージェントの推論
duration_ms	number	0	アクションの所要時間（ミリ秒）

replay_session

記録されたセッションを、すべてのアクションの詳細とともにステップごとに再生します。

パラメーター	型	説明
session_id	string	再生するセッション ID

返される内容：タイミング、推論、入力、出力を含む完全なアクションシーケンス。

compare_sessions

2 つのセッション間の動作の差分を表示します。ステップインデックスでアクションを揃え、違いを強調表示します。

パラメーター	型	説明
session_id_1	string	1 つ目のセッション
session_id_2	string	2 つ目のセッション

返される内容：類似度、同一／逸脱したステップ数、最初の逸脱ステップ、ステップごとの差分。

find_divergence_point

エージェントが期待される出力から最初に逸脱した箇所を特定します。

パラメーター	型	説明
session_id	string	分析するセッション
expected_output	any	期待される最終出力、またはステップごとの期待される出力の配列

expected_output が配列の場合、ステップごとに比較します。単一の値の場合、一致する最後の出力を見つけ、次のステップを逸脱箇所として示します。

export_session

共有やオフライン分析用にセッションをエクスポートします。

パラメーター	型	デフォルト	説明
session_id	string	必須	エクスポートするセッション
format	string	"json"	"json" または "markdown"

Markdown 形式では、ステップ見出し、推論、コードブロックを含む読みやすいトランスクリプトを生成します。

リソース

URI	説明
agent-replay://sessions	ステータスとアクション数を含む、記録済みのすべてのセッション

使用パターン

1. record_session — start recording at agent launch
2. For each agent action:
   - log_action — capture input, output, reasoning, timing
3. stop_recording — finalize the session
4. Debug:
   - replay_session — review what happened step by step
   - compare_sessions — diff today's run vs yesterday's
   - find_divergence_point — pinpoint where it went wrong
5. Share:
   - export_session — JSON for tooling, markdown for humans

テスト

npm test

ライセンス

MIT