agent-guard

agent-guard-mcp

用于检测和防止 Agent 陷入无限循环的 MCP 服务——这是 Agent 系统中首要的可靠性问题。

通过模型上下文协议提供断路器、模式检测、Agent 卡住分析和恢复建议。

安装

npx agent-guard-mcp

Claude Desktop

添加到 claude_desktop_config.json：

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

从源代码安装

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

工具

register_agent

注册要监控的 Agent。

参数	类型	默认值	描述
agent_id	string	必填	唯一的 Agent 标识符
max_iterations	number	100	强制停止前的最大迭代次数
progress_threshold	number	0.3	被视为“正在取得进展”的最小唯一操作数／总操作数比率

log_action

记录 Agent 操作以检测循环。维护最近 50 次操作的滚动窗口。

参数	类型	默认值	描述
agent_id	string	必填	Agent 标识符
tool_name	string	必填	正在调用的工具
args	object	必填	传入的参数
result_preview	string	""	简要的结果预览（最多 200 个字符）

检测到重复模式时会提前发出警告。

detect_loop

检查 Agent 是否陷入无限循环。

参数	类型	描述
agent_id	string	要检查的 Agent

返回：

• is_stuck — 布尔值
• confidence — 0.0 到 1.0
• pattern — healthy、exact_repeat、low_diversity 或 exact_repeat_and_low_diversity
• suggestion — 易于理解的恢复建议
• repeated_actions — 包含重复签名及其次数的列表

set_circuit_breaker

配置在操作模式重复时自动干预。

参数	类型	默认值	描述
agent_id	string	必填	Agent 标识符
max_repeats	number	3	在 N 次相同操作后触发
action	string	"warn"	"warn"、"block" 或 "suggest_alternative"

check_circuit_breaker

执行工具前的预检。在实际调用工具之前调用此项。

参数	类型	描述
agent_id	string	Agent 标识符
proposed_tool	string	即将调用的工具
proposed_args	object	即将传入的参数

仅在阻止模式下，断路器触发时才会返回 proceed: false。

get_stuck_report

详细分析 Agent 卡住的原因。

参数	类型	描述
agent_id	string	要分析的 Agent

返回：操作历史、模式分析、Token 浪费估算、多样性比率、重复次数最多的模式和恢复建议。

get_health_dashboard

所有受监控 Agent 的概览。无需参数。

返回按风险评分排序的所有 Agent，以及它们的状态（STUCK/HEALTHY）、操作计数和断路器配置。

资源

URI	描述
agent-guard://agents	所有受监控 Agent 的当前状态

使用模式

1. register_agent — at agent startup
2. Before each tool call:
   a. check_circuit_breaker — should this action proceed?
   b. Execute the tool
   c. log_action — record what happened
3. Periodically:
   - detect_loop — am I stuck?
   - get_health_dashboard — how are all agents doing?
4. On stuck detection:
   - get_stuck_report — what went wrong and how to recover

测试

npm test

许可证

MIT