agent-guard

agent-guard-mcp

エージェントシステムにおける最大の信頼性問題である、エージェントの無限ループを検出して防止する MCP サーバーです。

Model Context Protocol を通じて、サーキットブレーカー、パターン検出、エージェントの停滞分析、復旧の推奨事項を提供します。

インストール

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

監視対象のエージェントを登録します。

Param	Type	Default	Description
agent_id	string	required	一意のエージェント識別子
max_iterations	number	100	強制停止するまでの最大反復回数
progress_threshold	number	0.3	「進行中」と見なすための一意なアクション数／合計アクション数の最小比率

log_action

ループ検出のためにエージェントのアクションを記録します。直近 50 件のアクションをローリングウィンドウで保持します。

Param	Type	Default	Description
agent_id	string	required	エージェント識別子
tool_name	string	required	呼び出すツール
args	object	required	渡す引数
result_preview	string	""	結果の簡単なプレビュー（最大 200 文字）

パターンの繰り返しが検出されると、早期警告を返します。

detect_loop

エージェントが無限ループに陥っているかどうかを確認します。

Param	Type	Description
agent_id	string	確認するエージェント

戻り値：

• is_stuck — ブール値
• confidence — 0.0～1.0
• pattern — healthy、exact_repeat、low_diversity、または exact_repeat_and_low_diversity
• suggestion — 人が読める復旧アドバイス
• repeated_actions — 繰り返されたシグネチャとその回数のリスト

set_circuit_breaker

アクションパターンが繰り返された際の自動介入を設定します。

Param	Type	Default	Description
agent_id	string	required	エージェント識別子
max_repeats	number	3	同一のアクションが N 回繰り返された後に作動
action	string	"warn"	"warn"、"block"、または "suggest_alternative"

check_circuit_breaker

ツールを実行する前に、事前チェックを行います。実際にツールを呼び出す前に実行してください。

Param	Type	Description
agent_id	string	エージェント識別子
proposed_tool	string	呼び出そうとしているツール
proposed_args	object	渡そうとしている引数

サーキットブレーカーが作動すると、proceed: false を返します（ブロックモードのみ）。

get_stuck_report

エージェントが停滞している理由を詳細に分析します。

Param	Type	Description
agent_id	string	分析するエージェント

戻り値：アクション履歴、パターン分析、トークン浪費の推定値、多様性比率、繰り返しの多いパターン、復旧の推奨事項。

get_health_dashboard

監視対象のすべてのエージェントの概要を表示します。パラメーターはありません。

リスクスコア順に並べたすべてのエージェントと、ステータス（STUCK／HEALTHY）、アクション数、サーキットブレーカーの設定を返します。

リソース

URI	Description
agent-guard://agents	現在のステータスを含む、監視対象のすべてのエージェント

使用パターン

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