A2A マルチエージェント例：数字当てゲーム

プロジェクト概要

これはAgent2Agent（A2A）protocolに基づく数字当てゲームの例で、3つの軽量なA2Aエージェントがどのように協力して古典的な数字当てゲームを完成させるかを実証しています。このプロジェクトはA2A protocolとPython SDKの実用的な入門例として機能し、以下の特徴があります：

LLM依存なし：APIキーや大規模言語モデルが不要
ローカル実行：3つのエージェントすべてがリモートサーバーなしでローカル実行
簡単インストール：最小限の外部依存関係
核心概念実証：A2A protocolの核心機能を紹介

エージェント役割説明

エージェント	役割	機能
AgentAlice	評価者	1-100の秘密の数字を選択、推測を評価してヒントを提供
AgentBob	CLIフロントエンド	プレイヤーの推測を中継、Aliceのヒントを表示、Carolと交渉
AgentCarol	可視化	推測履歴のテキスト可視化を生成、要求に応じて履歴をランダムシャッフル

詳細コードファイル分析

1. 設定ファイル（`config.py`）

AGENT_ALICE_PORT = 8001
AGENT_BOB_PORT = 8002
AGENT_CAROL_PORT = 8003

機能：ポート設定を一元管理してポート競合を回避。すべてのエージェントがこのモジュールから設定をインポートし、ポート割り当ての一貫性を確保。

2. AgentAlice（`agent_Alice.py`）

核心機能：

起動時に1-100の秘密の数字をランダム選択
NumberGuessExecutorクラスを実装して推測評価を処理
A2A SDKのAgentExecutorインターフェースを通じてメッセージを処理

主要メソッド：

execute()：新しく受信したメッセージを処理、process_guess()を呼び出して推測を評価
cancel()：指定されたタスクを拒否

応答タイプ：

"Go higher" - 推測が秘密の数字より小さい
"Go lower" - 推測が秘密の数字より大きい
"correct! attempts: <n>" - 推測が正しい、試行回数を表示

3. AgentBob（`agent_Bob.py`）

核心機能：

CLIフロントエンドとして機能、プレイヤーを他のエージェントと接続
ゲーム状態と履歴記録を管理
Carolと交渉して履歴記録をソート

主要メソッド：

_handle_guess()：推測をAliceに転送してフィードバックを返す
_negotiate_sorted_history()：履歴がソートされるまでCarolと交渉
_visualise_history()：フォーマットされた履歴可視化を要求して印刷
play_game()：インタラクティブCLIループを実行

交渉ロジック：

Carolに初期シャッフル要求を送信
返されたリストがソートされているかチェック
ソートされていない場合、"Try again"を送信して交渉を継続
ソートされている場合、"Well done!"を送信して交渉を完了

4. AgentCarol（`agent_Carol.py`）

核心機能：

推測履歴記録を可視化
履歴記録リストをランダムシャッフル
マルチターン対話とタスク参照をサポート

主要メソッド：

_handle_initial()：新しい会話での初期メッセージを処理
_handle_followup()：既存タスクを参照するフォローアップメッセージを処理
execute()：メッセージタイプに基づいて適切なハンドラーにディスパッチ

スキル定義：

history_visualiser：フォーマットされた推測履歴要約を生成
history_shuffler：履歴記録エントリの順序をランダムシャッフル

5. ユーティリティモジュール（`utils/`）

`game_logic.py`

核心機能：

process_guess()：個別の推測を評価してフィードバックを返す
build_visualisation()：人間が読める履歴記録レンダリングを作成
is_sorted_history()：履歴が推測値でソートされているかチェック
process_history_payload()：履歴関連要求を処理

`protocol_wrappers.py`

核心機能：

send_text()：ターゲットエージェントにテキストメッセージを同期送信
send_followup()：フォローアップメッセージを送信、会話コンテキストを維持
cancel_task()：リモートエージェントでタスクをキャンセル
extract_text()：TaskまたはMessageオブジェクトからプレーンテキストを抽出

`server.py`

核心機能：

run_agent_blocking()：ブロッキングエージェントサーバーを開始
Starlette + UvicornをHTTPサーバーとして使用

システムアーキテクチャフローチャート

graph TD
    A[Player] --> B[AgentBob CLI]
    B --> C[AgentAlice Evaluator]
    B --> D[AgentCarol Visualizer]
    
    C --> E[Secret Number 1-100]
    C --> F[Evaluate Guess]
    F --> G{Guess Result}
    G -->|Too Low| H[Return Go higher]
    G -->|Too High| I[Return Go lower]
    G -->|Correct| J[Return correct! attempts: N]
    
    B --> K[Game History]
    K --> L[Send to Carol for Visualization]
    L --> M[Generate Formatted Table]
    M --> N[Display to Player]
    
    B --> O[Negotiate Sorting]
    O --> P[Send Shuffle Request]
    P --> Q[Carol Random Shuffle]
    Q --> R{Check if Sorted}
    R -->|Not Sorted| S[Send Try again]
    R -->|Sorted| T[Send Well done!]
    S --> Q
    T --> U[Update History]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e8f5e8
    style D fill:#fff3e0
    style E fill:#ffebee
    style F fill:#e8f5e8
    style K fill:#f3e5f5
    style O fill:#f3e5f5

メッセージフロー図

sequenceDiagram
    participant Player as Player
    participant Bob as AgentBob
    participant Alice as AgentAlice
    participant Carol as AgentCarol
    
    Note over Player,Carol: Game Start
    Player->>Bob: Input guess number
    Bob->>Alice: Send guess
    Alice->>Bob: Return evaluation result
    Bob->>Player: Display hint
    
    Note over Player,Carol: Record History
    Bob->>Bob: Add to game history
    
    Note over Player,Carol: Visualize History
    Bob->>Carol: Send history records
    Carol->>Bob: Return formatted table
    Bob->>Player: Display history visualization
    
    Note over Player,Carol: Negotiate Sorting
    Bob->>Carol: Send shuffle request
    Carol->>Bob: Return shuffled list
    Bob->>Bob: Check if sorted
    
    alt Not Sorted
        Bob->>Carol: Send "Try again"
        Carol->>Bob: Shuffle list again
        Bob->>Bob: Recheck sorting
    else Sorted
        Bob->>Carol: Send "Well done!"
        Carol->>Bob: Complete task
        Bob->>Bob: Update history
    end
    
    Note over Player,Carol: Continue Game or End
    alt Guess Correct
        Bob->>Player: Display victory message
    else Guess Incorrect
        Player->>Bob: Continue inputting guesses
    end

uvでプロジェクトを実行

1. 環境セットアップ

uvがインストールされていることを確認：

# uvをインストール（まだインストールされていない場合）
curl -LsSf https://astral.sh/uv/install.sh | sh

2. プロジェクトセットアップ

# プロジェクトをクローン
git clone https://github.com/a2aproject/a2a-samples.git
cd a2a-samples/samples/python/agents/number_guessing_game

# uvを使用して仮想環境を作成し依存関係をインストール
uv venv
source .venv/bin/activate  # Linux/macOS
# または .venv\Scripts\activate  # Windows

# 依存関係をインストール
uv pip install -r requirements.txt

3. ゲームの実行

3つのターミナルウィンドウを開き、それぞれで仮想環境をアクティベート：

# ターミナル1 - Alice（評価者）を開始
uv run python agent_Alice.py

# ターミナル2 - Carol（可視化）を開始
uv run python agent_Carol.py

# ターミナル3 - Bob（CLIフロントエンド）を開始
uv run python agent_Bob.py

4. ゲームプレイ

Bobのターミナルで、ゲームは1-100の数字を入力するよう促します。正しく推測するまで、Aliceのフィードバックに基づいて推測を続けてください。

ゲームフローの例：

Guess the number AgentAlice chose (1-100)!
Your guess: 50
Alice says: Go higher

=== Carol's visualisation (sorted) ===
Guesses so far:
  1.  50 -> Go higher
============================

Your guess: 75
Alice says: Go lower

=== Carol's visualisation (sorted) ===
Guesses so far:
  1.  50 -> Go higher
  2.  75 -> Go lower
============================

Your guess: 62
Alice says: correct! attempts: 3
You won! Exiting…

プロジェクト要約

技術的特徴

A2A Protocol実践：
- エージェント間通信の核心概念を実証
- メッセージ送信、タスク管理、状態追跡を実装
- マルチターン対話とタスク参照メカニズムを表示
モジュラー設計：
- 責任の明確な分離：Aliceは評価、Bobは相互作用、Carolは可視化を処理
- 拡張とメンテナンスが容易な再利用可能ユーティリティモジュール
エラーハンドリング：
- 入力検証とエラープロンプト
- ネットワーク通信例外処理
- タスクキャンセルとタイムアウトメカニズム

学習価値

A2A入門：A2A protocolを理解するためのシンプルで理解しやすい例を提供
エージェント協力：複数のエージェントが複雑なタスクを完了するために協力する方法を表示
非同期プログラミング：非同期メッセージ処理と状態管理を実証
Protocol設計：明確なエージェントインターフェースとスキル定義の設計方法を表示

拡張可能性

より多くのエージェントを追加：統計アナリスト、戦略アドバイザーなどの新しいエージェント役割を導入
ゲームロジックの強化：時間制限、スコアリングシステムなどのより複雑なゲームルールを追加
ネットワーク展開：エージェントを異なるマシンに展開し、分散エージェントシステムを実証
LLM統合：インテリジェントなヒントと戦略提案を提供するAIエージェントを追加

セキュリティ考慮事項

プロジェクトドキュメントで言及されているように、本番環境では：

外部エージェントは信頼できないエンティティとして扱うべき
受信したすべてのデータは検証と無害化が必要
入力検証や認証情報保護などの適切なセキュリティ対策を実装

この例は、開発者にA2A protocolを学習し実験するための安全で制御された環境を提供し、分散エージェントシステム構築の基本パターンを実証します。

A2A マルチエージェント例：数字当てゲーム

プロジェクト概要

エージェント役割説明

詳細コードファイル分析

1. 設定ファイル（`config.py`）

2. AgentAlice（`agent_Alice.py`）

3. AgentBob（`agent_Bob.py`）

4. AgentCarol（`agent_Carol.py`）

5. ユーティリティモジュール（`utils/`）

`game_logic.py`

`protocol_wrappers.py`

`server.py`

システムアーキテクチャフローチャート

メッセージフロー図

uvでプロジェクトを実行

1. 環境セットアップ

2. プロジェクトセットアップ

3. ゲームの実行

4. ゲームプレイ

プロジェクト要約

技術的特徴

学習価値

拡張可能性

セキュリティ考慮事項

関連ケーススタディ

🚀 入門例

🐍 Python実装ケース

🟨 JavaScript/TypeScriptケース

☕ Java実装ケース

🔧 フレームワーク統合ケース

🛠️ 開発ツール

📚 Protocol理解とベストプラクティス

🌟 エコシステムリソース

A2A マルチエージェント例：数字当てゲーム

プロジェクト概要

エージェント役割説明

詳細コードファイル分析

1. 設定ファイル（config.py）

2. AgentAlice（agent_Alice.py）

3. AgentBob（agent_Bob.py）

4. AgentCarol（agent_Carol.py）

5. ユーティリティモジュール（utils/）

game_logic.py

protocol_wrappers.py

server.py

システムアーキテクチャフローチャート

メッセージフロー図

uvでプロジェクトを実行

1. 環境セットアップ

2. プロジェクトセットアップ

3. ゲームの実行

4. ゲームプレイ

プロジェクト要約

技術的特徴

学習価値

拡張可能性

セキュリティ考慮事項

関連ケーススタディ

🚀 入門例

🐍 Python実装ケース

🟨 JavaScript/TypeScriptケース

☕ Java実装ケース

🔧 フレームワーク統合ケース

🛠️ 開発ツール

📚 Protocol理解とベストプラクティス

🌟 エコシステムリソース

1. 設定ファイル（`config.py`）

2. AgentAlice（`agent_Alice.py`）

3. AgentBob（`agent_Bob.py`）

4. AgentCarol（`agent_Carol.py`）

5. ユーティリティモジュール（`utils/`）

`game_logic.py`

`protocol_wrappers.py`

`server.py`