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

プロジェクト概要

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

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

エージェント役割説明

詳細コードファイル分析

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…

プロジェクト要約

技術的特徴

1. A2A Protocol実践：

   • エージェント間通信の核心概念を実証
   • メッセージ送信、タスク管理、状態追跡を実装
   • マルチターン対話とタスク参照メカニズムを表示

2. モジュラー設計：

   • 責任の明確な分離：Aliceは評価、Bobは相互作用、Carolは可視化を処理
   • 拡張とメンテナンスが容易な再利用可能ユーティリティモジュール

3. エラーハンドリング：

   • 入力検証とエラープロンプト
   • ネットワーク通信例外処理
   • タスクキャンセルとタイムアウトメカニズム

学習価値

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

拡張可能性

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

セキュリティ考慮事項

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

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

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

関連ケーススタディ

🚀 入門例

• A2A Samples: Hello World Agent

  • A2A Python SDKを使用してHello Worldエージェントを構築する完全ガイド
  • 詳細な環境セットアップとテスト手順を含む

• A2A SDK Currency Agent Tutorial

  • 通貨変換エージェント構築のステップバイステップガイド
  • OpenRouter AIサービスを統合

🐍 Python実装ケース

• A2A Python Example: GitHub Agent

  • a2a-pythonを使用してGitHubエージェントを作成・接続
  • コードリポジトリ情報クエリ機能を実装

• A2A Example: Travel Planning Assistant

  • OpenRouterを統合した旅行計画エージェント実装
  • Python a2a-sdkを使用して構築

• A2A SDK Python実践ガイド

  • 詳細なA2A SDK Python開発チュートリアル
  • ワークフロー図と実践的なコード例を含む

🟨 JavaScript/TypeScriptケース

• A2A JS Example: Movie Agent

  • TMDB APIとOpenRouter AIとの統合
  • Express.jsサーバー実装

• A2A JavaScript SDK完全チュートリアル

  • TypeScript型安全実装
  • Express.jsサーバーSDKとストリーミング処理

☕ Java実装ケース

• A2A Java Example
  • Mavenマルチモジュールアーキテクチャ
  • Spring BootサーバーSDK実装
  • AI翻訳サービス例

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

• ADKでA2Aエージェントを実装：完全開発ガイド

  • Google ADKフレームワークを使用してA2Aインテリジェントエージェントシステムを実装
  • 完全な開発ワークフローをカバー

• A2A ADK経費精算エージェント

  • Google ADKとA2A protocolに基づくインテリジェント経費精算エージェント
  • フォーム補完情報を自動生成

• A2A CrewAI分析チャートエージェント

  • CrewAIフレームワークを使用してデータ分析エージェントを構築
  • チャート生成とデータ可視化機能を統合

🛠️ 開発ツール

• A2A Inspector: Agent2Agent通信デバッグ解説

  • 強力なWebベースデバッグツール
  • エージェントカードとJSON-RPC通信のリアルタイム検査

• A2A .NET SDK包括的ドキュメント

  • Google A2A Protocol v0.2.1を実装する.NETライブラリ
  • ASP.NET Coreアプリケーションに適用

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

• A2A Protocol理解：包括的ガイド

  • A2A protocolを理解するための包括的ガイド
  • 核心概念とAIエージェント相互運用性の利点

• A2A Protocol仕様（Python）

  • Python実装仕様の包括的ガイド
  • エージェントカード、メッセージング、タスク管理を含む核心機能をカバー

• 2025年A2A Protocol完全ガイド

  • A2A protocolの包括的紹介と実践ガイド
  • 基本概念から高度なアプリケーションまで完全カバー

🌟 エコシステムリソース

• Awesome A2Aディレクトリ

  • Google A2A protocolの完全エコシステムを探索
  • 公式ドキュメント、コミュニティ実装、サンプルプロジェクト、統合ガイドを含む

• A2A実装コレクション

  • A2A protocolの様々なオープンソース実装を探索
  • Java、TypeScript、Go、Rust、Pythonなどを含む

これらのケーススタディを通じて、シンプルなHello World例から複雑なマルチエージェントシステムまで、異なるシナリオでのA2A protocolアプリケーションについて深い洞察を得ることができ、A2A開発の旅に豊富な参考リソースを提供します。