MARL Cop & Thief - MCP を介したデュアル AI エージェント

2 つの自律 AI エージェント（Cop と Thief）が MCP サーバー上で 自由な自然言語 で対話し、ゲーム理論的ミニマックス + 自己対戦 RL エンジンで手を決定し、Web コントロールパネル にライブ表示し、合意された JSON マッチレポート を Gmail API 経由でメール送信する、分散型・部分観測可能な 追跡ゲーム です。

University of Haifa · Orchestration of AI Agents (ex06) · Dr. Yoram Segal.
1 つのコマンドですべてを起動し、1 つのブラウザタブでマッチ全体を実行します。

Highlights

• ワンコマンドノード - python -m cop_thief.app は両 MCP サーバー、パブリック Cloudflare トンネル、およびブラウザコントロールパネルをまとめて起動します（孤立トンネルなし、ポートのやりくり不要）。

• Web コントロールパネル - ノードのライブステータス、コピー可能な公開 URL/トークン、対戦相手用の チャレンジフォーム、ワンクリックの ミラーセルフテスト、ライブな 5×5 ゲーム TV をすべて http://127.0.0.1:8800 で提供。

• 本格的な戦略 - Conway の封鎖ゲーム（Cop = Devil の壁、§4.3）と 自己対戦 RL による重み学習を備えた Angel–Devil ミニマックス エンジン（ゼロ和マルコフゲーム、アルファベータ）。課題のベースラインであるテーブル型 Q をはるかに超えています。docs/STRATEGY.md を参照。

• 分散型 & チート耐性 - 審判なし。両側が結果をハッシュ化（SHA-256）し、不一致があればスコアは 0/0 です。受信した散文は敵対的と見なされます。プロンプトインジェクション/強制は スクリーニングされ、証拠として記録され、結果を変更できません（降参アクションは存在しません）。

• Single SDK boundary + API Gatekeeper - すべてのロジックは CopThiefSDK の背後にあり、すべての外部コール（LLM、Gmail）は DeepSeek→Anthropic フェールオーバを備えた FIFO バックプレッシャ付きゲートキーパーを経由します。

• 品質ゲート - pytest カバレッジ 85 % 以上、ruff 違反ゼロ、1 ファイル 150 行以内、uv のみ。

Related MCP server: Police MCP Server

Quick start

uv sync                                   # install (uv is the ONLY package manager)
cp .env-example .env                      # fill in real values (see "Secrets")
uv run ruff check .                       # zero-violation lint gate
uv run pytest                             # full suite (>=85% coverage gate)
uv run python -m cop_thief.app            # launch the control panel + servers + tunnels

次に http://127.0.0.1:8800 を開きます。

Playing a match (control panel)

1. uv run python -m cop_thief.app を実行 → パネルが開きます。Servers ● と Tunnels ● が緑になるまで待ちます。

2. ステータスカードには、2 つの公開 …/mcp/ URL とロール別トークン（コピー用ボタン）が表示されます。これらを対戦相手に送ってください。合わせて docs/INTER_GROUP_TREATY_SPEC.md も送ります。記入フォームは match_setup/ の（RULES.txt、OUR_DETAILS、OPPONENT_DETAILS）を使用します。

3. 対戦相手の 2 つの …/mcp/ URL（トークンがあればそれも）を チャレンジフォーム に貼り付け、START CHALLENGE をクリックします。6 つのサブゲームがクロスホストで TV 上に表示され、レポートがメール送信されます。

4. まだパートナーがいませんか？ MIRROR SELF-TEST ⟳ をクリックします。自分のローカルホストエンドポイントとトークンが自動記入され、自分自身と対戦します（戦略テストに最適）。

A game = 6 sub-games（§4.1 に従う）: Cop で 3 ゲーム（ホームレグ）と Thief で 3 ゲーム（アウェイレグ）をプレイし、Thief 先手、各 ≤ 25 手です。スコアリングは不変です: Cop が捕獲 → 20 / 5; Thief が生き残り → 5 / 10。

Screenshots

The control panel - ノードのステータス（Servers/Tunnels/Game）、共有可能な …/mcp/ URL とトークン（コピー用ボタン付き）、対戦相手チャレンジフォーム、ライブゲーム。ここではミラーセルフテストが実行中です。[INTENT: BARRIER] 行（Cop が隣接セルに壁を作りその場に留まる、§4.3）、緑色の B バリア、! による捕獲に注目。

Live board - Cop C（青）と Thief T（赤）がいる 5×5 グリッド。隣に通信傍受フィードがあり、自然言語の [INTENT: MOVE] 送信と HOME LEG / Sub-game セパレータが表示されています。

Leg transition - サブゲーム 4/6 で AWAY LEG（こちらが Thief をプレイ）に入るランナー。ボード上には B バリアと ! による捕獲が残っています。

ノードを起動すると、共有可能なエンドポイントがターミナルに出力されます（1 プロセス: servers + tunnels + panel）:

Control panel  >  http://127.0.0.1:8800   (open in a browser)
╔══════════════════════════════════════════════════════════════════╗
║ LIVE PUBLIC MATRIX (Team Alpha)                                   ║
╠══════════════════════════════════════════════════════════════════╣
║ COP   (:8001)  https://acting-tomorrow-yard-raid.trycloudflare.com/mcp/   ║
║ THIEF (:8002)  https://dial-mean-courses-tramadol.trycloudflare.com/mcp/  ║
╚══════════════════════════════════════════════════════════════════╝
Tunnels live and written to config/setup.json. Share these /mcp/ URLs. Ctrl+C to stop.

Architecture

Entry points

Strategy in one paragraph

各 request_move には、ゼロ和マルコフゲーム（Cop が最大化、Thief が最小化、最適敵対仮定）に対する深さ制限付き アルファベータ・ミニマックス で応答します。進捗に応じた終端スコア（±WIN ∓ turns）により、ポリシーは捕獲/生存を迫るため、引き分けは構造的に回避されます。Cop のアクション集合には 隣接セルへの壁作成（Conway の "Devil" ムーブ、§4.3）が含まれます。評価関数の containment 特徴量は、Thief のフラッドフィル逃出領域であり、プランナーは適法な追い込んで罠に嵌める手筋を自ら発見します。線形評価の重みは 自己対戦 TD（selfplay.train_weights）で調整可能です。3 つのバリアント・プロファイル（aggressive / balanced / defensive）が要求される 3 エージェントのロースターを編成します。完全な設計: docs/STRATEGY.md。

Formal model - Dec-POMDP

この追跡は Decentralized, Partially-Observable Markov Decision Process としてモデル化され、タプル ⟨ n, S, {Aᵢ}, P, R, {Ωᵢ}, O, γ ⟩（ex06 §11）で表されます。

部分観測可能性は現実のものです。各エージェントは、ボードに対する 信念（直前の観測 + 解析された対戦相手の散文）から決定し、グローバルな真実値からは決して決定しません。

Orchestration challenges (the hard part)

ex06 §14 によれば、この課題の 価値はオーケストレーション であり、勝利ではありません。難しい問題とその解決方法:

• 自由な自然言語、事前定義されたプロトコルなし。 エージェントは散文で対話します。薄い決定的コントラクトを重ねます - 各メッセージは、正確に1つの標識 [INTENT: MOVE|BARRIER|HOLD] で始まり、その後に方角語が続きます - これにより、本体は自由なNLのままでも手は機械的に解決可能です。これにより、独立に構築された2つのエンジンを、共有コードベースなしでロックステップに保ちます。

• 言語的曖昧さと信頼できない入力。 受信した散文は決定的に解析されます（最長一致の方角語、フレーバーテキストが偽装できないようにブラケットのみのインテント）。非構造化された相手テキストに対してはオプションのLLM解析を使用します; 信頼度が低い場合は → 安全な探索的フォールバック（クラッシュせず、キャプチャを偽造しない）。すべてのフィールドは敵対的として扱われます - 例えば非数値の variant は強制的に変換され、信頼されません。

• 相互理解の確保。 両ピアは決定的な手言語を共有し（LLM不要のエンコード/パース）、ゲームはバイト再現可能です。最後に両サイドは標準 sub_games をハッシュします（SHA-256、K3）; 不一致があれば ⇒ 両者とも 0/0 - 合意は前提ではなく強制されます。

• 信頼性のないネットワーク上での活性。 ホスト間の手は再接続によるリトライを行います; 継続的な停止またはフローズンしたピア（手ごとの20秒タイムアウト）は、そのサブゲームを棄権し、シリーズは常に全6戦を完了し、レポートはそれでもメール送信されます - 停止した相手は決してマッチを止められません。

可視化と決定的な証拠（§11）

• GUI - 上記のスクリーンショットは、ライブの5×5ボード、[INTENT: …] 通信傍受フィード、バリア（B）、キャプチャー（!）、およびレグ遷移を示しています。

• クラウド MCP 通信 - 上記のブートブロックは、ライブの公開 Cloudflare /mcp/ URLを出力し、パネルの通信フィードはクラウドサーバーと交換される実際の [INTENT:] 送信をストリームします; 各手番も data/game_audit.jsonl に追記され、改ざん防止付きのゲーム別アーカイブ（data/archive/、レポート内のバンドル SHA-256）に封入されます。

• 学習 - 戦略の重みは自己対戦TD（selfplay.train_weights）で調整されます; 比較用にテーブル型Q学習ベースラインも保持されます。設計+カーブ: docs/STRATEGY.md。

セキュリティと公正なプレー

• トークン - すべての MCP ツール呼び出しには、ロールごとの失効可能なベアラートークンが必要です; 帯域外で交換され、ローテーションで失効できます。サーバーはフェイルクローズドです。

• インジェクション対策 - 受信送信は信頼されません; インジェクション/強制/成りすまし/偽造は検査され、data/game_audit.jsonl で hostile:true とフラグされ、レポートで計上され、エンジン決定の結果には一切影響を与えません。相手との条約（§F）に明文化されています。

• 相互合意 - 両サードは標準 sub_games をハッシュします; 不一致があれば ⇒ 0/0（both_lose）。

• レポーティング - OAuth2 Desktop 経由の Gmail API（スコープ gmail.modify、パスワードなし）; グーループ名は件名とJSONボデーの両方に含まれます; 安全ガードはデフオルトで使い捨て用受信トレーを使用します。

トークン予算とコスト

すべての外部呼び出しは API Gatekeeper → TokenTracker によってメータリングされ、ライブな使用量を data/token_usage.json にストリームします（原子書き込み; K3合意ハッシュから除外されるため、コストが結果に影響することはありません）。すべての数値は設定駆動です（config/setup.json → token_budget / economics）。

実際には、プロジエクト全体の LLM コストは約 $0.01 です。 手はローカルなミニマックスエージンから来ており、 手言語は決定的な [INTENT: …] エンコード/パースです - プレーやレポート送信に LLM は不要です （Gmail API であり、LLM ではありません）。小さな予算 + DeepSeek 優先のフェールオーバーは、オプショナル の LLM 支援自然言語パースのためのガードレールです; 上限は**$0.50**に設定されており、十分な余裕があります。

シークレットと設定

• .env-example を .env にコピーして記入します: DEEPSEEK_API_KEY、ANTHROPIC_API_KEY、COP_MCP_TOKEN、THIEF_MCP_TOKEN、GMAIL_CREDENTIALS_PATH。依存ゼロのオートローグーが起動時に .env を注入します - export/source は不要です; 既存のシェル export が常に優先されます。

• 調整可能な項目はすべてバージョン管理された config/*. json にあります（ハードコーデングなし）。シークレット（.env、credentials.json、token.json）は git に無視され、ソース管理に入ることはありません。

ドキュメンテーション

PRD · PLAN · TODO · STRATEY · RULES_AND_AGREEMENTS · INTER_GROUP_TREATY_SPEC

ライセンス

MIT.