agent-replay

agent-replay-mcp

用于记录和回放 Agent 会话的 MCP 服务——通过会话比较和偏差检测，调试 Agent 的非确定性行为。

记录 Agent 执行的每个操作，逐步回放会话，对比两次运行以查找行为回归，并精确定位 Agent 偏离预期输出的位置。

安装

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 会话的所有操作。

参数	类型	默认值	说明
agent_id	string	必填	唯一的 Agent 标识符
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	""	Agent 在此步骤中的推理
duration_ms	number	0	操作时长，单位为毫秒

replay_session

逐步回放录制的会话，并显示完整的操作详情。

参数	类型	说明
session_id	string	要回放的会话 ID

返回：完整的操作序列，包括时间、推理、输入和输出。

compare_sessions

比较两个会话的行为差异。按步骤索引对齐操作并突出显示差异。

参数	类型	说明
session_id_1	string	第一个会话
session_id_2	string	第二个会话

返回：相似度、相同/偏差步骤数量、首次出现偏差的步骤，以及逐步差异。

find_divergence_point

查找 Agent 首次偏离预期输出的位置。

参数	类型	说明
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