Implementing A2A Agents with ADK: Complete Development Guide

目次

1. ADKとA2Aプロトコルの概要
2. 環境設定と依存関係のインストール
3. プロジェクト構造設計
4. A2Aサーバーサイドエージェント開発
5. A2Aクライアントサイドエージェント開発
6. エージェント設定とメタデータ
7. A2Aサーバー起動とテスト
8. Web UI統合テスト
9. A2A通信フローの詳細説明

ADKとA2Aプロトコルの概要

ADKとA2Aとは何か？

**ADK（Agent Development Kit）**はGoogleが開発したインテリジェントエージェント開発フレームワークであり、**A2A（Agent2Agent Protocol）**は標準化されたエージェント間通信プロトコルです。ADKフレームワークはA2Aエージェントに対する完全なサポートを内蔵しており、RemoteA2aAgentなどの主要コンポーネントを提供して、開発者が以下を実行できるようにします：

• 🔗 シームレスな接続：分散エージェント間の標準化された通信を実装
• 🚀 迅速な開発：シンプルなAPIを使用して複雑なエージェントシステムを迅速に構築
• 🔄 プロトコル標準化：A2Aプロトコル仕様に従って相互運用性を保証
• 🎯 インテリジェントルーティング：メッセージルーティングとフォーマット変換を自動処理
• 📊 観測可能性：内蔵されたログ記録と監視機能

重要な注意：ADKは開発フレームワークであり、A2Aは通信プロトコルです。ADKはA2Aプロトコルの実装を含んでおり、開発者がAgent2Agent通信をサポートするインテリジェントエージェントシステムを簡単に構築できます。このガイドでは、ADKフレームワーク内でA2A機能を使用する方法を示します。

ADKのA2A機能の主要な利点

1. 分散アーキテクチャ：異なるサーバーと環境でのエージェント展開をサポートし、A2Aプロトコルを通じて通信
2. 標準化されたプロトコル：A2A通信プロトコル仕様に従い、クロスプラットフォーム互換性を保証
3. すぐに使える：ADKはA2Aサポートが内蔵された完全なCLIツールとWeb UIを提供
4. 高い拡張性：カスタムツールと複雑なビジネスロジックをサポートし、A2Aエコシステムと互換
5. 本番環境対応：エンタープライズグレードのセキュリティと信頼性保証

環境設定と依存関係のインストール

システム要件

• Python：3.10以上
• オペレーティングシステム：Linux、macOS、またはWindows
• APIキー：Gemini APIキー（LLM機能用）

ステップ1：プロジェクトディレクトリの作成

# プロジェクトルートディレクトリを作成
mkdir adk-a2a-demo
cd adk-a2a-demo

# 仮想環境を作成
python -m venv .venv

# 仮想環境をアクティベート
# Linux/macOS:
source .venv/bin/activate
# Windows:
# .venv\Scripts\activate

ステップ2：ADK依存関係のインストール（A2Aサポート含む）

# ADKコアパッケージをインストール（A2Aプロトコルサポート含む）
pip install google-adk[a2a]>=1.6.1

# インストールを確認
adk --version

ステップ3：環境変数の設定

# .envファイルを作成
echo "GOOGLE_API_KEY=your_gemini_api_key_here" > .env

# 環境変数を設定（一時的）
export GOOGLE_API_KEY="your_gemini_api_key_here"

プロジェクト構造設計

ADKベースの推奨A2Aプロジェクト構造

adk-a2a-demo/
├── .env                    # 環境変数設定
├── requirements.txt        # Python依存関係
├── __init__.py            # メインプロジェクト初期化
├── agent.py               # A2Aクライアントエージェント（RemoteA2aAgent）
├── remote_a2a/            # A2Aサーバーサイドエージェントディレクトリ
│   └── facts_agent/       # 特定のエージェント実装
│       ├── __init__.py    # エージェントパッケージ初期化
│       ├── agent.py       # エージェントコアロジック
│       └── agent.json     # A2Aエージェントメタデータ設定
└── README.md              # プロジェクトドキュメント

基本プロジェクト構造の作成

# 必要なディレクトリとファイルを作成
mkdir -p remote_a2a/facts_agent
touch __init__.py agent.py
touch remote_a2a/facts_agent/__init__.py
touch remote_a2a/facts_agent/agent.py
touch remote_a2a/facts_agent/agent.json
touch requirements.txt

A2Aサーバーサイドエージェント開発

ステップ1：サーバーサイドエージェント実装の作成

サーバーサイドエージェントは実際にビジネスロジックを実行するコアコンポーネントです。remote_a2a/facts_agent/agent.pyで実装：

# remote_a2a/facts_agent/agent.py

from google.adk import Agent
from google.adk.tools import google_search

# サーバーサイドエージェントを定義
root_agent = Agent(
    # エージェント固有識別子
    name="facts_agent",
    
    # 使用する大規模言語モデル
    model="gemini-2.0-flash",
    
    # エージェント機能説明
    description="興味深い事実を提供するエージェントです。",
    
    # エージェント行動指示
    instruction=(
        "あなたは興味深い事実を提供できる有用なエージェントです。"
        "Google検索を使用して正確で最新の情報を見つけてください。"
        "常に事実の出典を提供してください。"
    ),
    
    # 利用可能なツールリスト
    tools=[google_search],
)

ステップ2：エージェントパッケージ初期化の設定

remote_a2a/facts_agent/__init__.pyで：

# remote_a2a/facts_agent/__init__.py

# ADKが発見できるようにエージェント実装をインポート
from . import agent

ステップ3：サーバーサイドエージェントコア機能分析

# エージェントのコアコンポーネント説明

# 1. 名前（name）
# - 一意である必要があり、A2Aネットワークでエージェントを識別するために使用
# - 説明的な名前の使用を推奨

# 2. モデル（model）
# - 使用する大規模言語モデルを指定
# - Geminiシリーズモデルをサポート

# 3. 説明（description）
# - エージェント機能の簡潔な説明
# - エージェント発見時に他のエージェントに表示される

# 4. 指示（instruction）
# - 詳細な行動ガイダンス
# - エージェントの性格と応答スタイルを定義

# 5. ツール（tools）
# - エージェントが呼び出せる外部ツール
# - 検索、計算、API呼び出しなど

A2Aクライアントサイドエージェント開発

ステップ1：クライアントサイドエージェントの作成

クライアントサイドエージェントはRemoteA2aAgentを使用してリモートサービスに接続します。agent.pyで実装：

# agent.py

from google.adk.agents.remote_a2a_agent import RemoteA2aAgent

# リモートA2Aクライアントエージェントを定義
root_agent = RemoteA2aAgent(
    # クライアントエージェント名
    name="facts_agent",
    
    # 機能説明
    description="興味深い事実を提供するエージェントです。",
    
    # リモートエージェントカードURL
    agent_card="http://localhost:8001/a2a/facts_agent/.well-known/agent.json",
)

ステップ2：RemoteA2aAgentの詳細設定

# 高度な設定例
root_agent = RemoteA2aAgent(
    name="facts_agent",
    description="興味深い事実を提供するエージェントです。",
    agent_card="http://localhost:8001/a2a/facts_agent/.well-known/agent.json",
    
    # オプション設定
    timeout=300.0,          # HTTPタイムアウト（秒）
    httpx_client=None,      # カスタムHTTPクライアント
)

ステップ3：クライアントサイドエージェントの動作原理

1. エージェント発見：agent_card URLを通じてリモートエージェント情報を取得
2. 接続確立：リモートA2AサーバーへのHTTP接続を作成
3. メッセージ変換：ローカルイベントをA2Aプロトコルメッセージに変換
4. リモート呼び出し：リモートエージェントにリクエストを送信
5. 応答処理：リモートエージェントの応答を受信して変換

エージェント設定とメタデータ

ステップ1：エージェント設定ファイルの作成

remote_a2a/facts_agent/agent.jsonでエージェントメタデータを定義：

{
  "name": "facts_agent",
  "description": "興味深い事実を提供するエージェントです。",
  "url": "http://localhost:8001/a2a/facts_agent",
  "version": "1.0.0",
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "capabilities": {
    "streaming": true,
    "functions": true
  },
  "skills": [
    {
      "id": "give_facts",
      "name": "興味深い事実",
      "description": "Google検索を使用してさまざまなトピックに関する興味深い事実を提供します。",
      "tags": ["情報", "事実", "知識", "検索", "グーグル"],
      "examples": [
        "ニューヨーク市に関する興味深い事実を教えてください。",
        "量子物理学について魅力的な事実を教えてください。",
        "海洋生物に関する珍しい事実は何ですか？"
      ]
    }
  ]
}

ステップ2：設定フィールドの説明

{
  // 基本情報
  "name": "エージェント固有識別子",
  "description": "エージェント機能の簡潔な説明",
  "url": "A2Aサービスエンドポイント URL",
  "version": "バージョン番号（セマンティックバージョニング）",
  
  // 入力/出力モード
  "defaultInputModes": ["サポートされる入力形式"],
  "defaultOutputModes": ["サポートされる出力形式"],
  
  // エージェント機能
  "capabilities": {
    "streaming": "ストリーミング応答がサポートされているかどうか",
    "functions": "関数呼び出しがサポートされているかどうか"
  },
  
  // スキル定義
  "skills": [
    {
      "id": "スキル固有識別子",
      "name": "スキル表示名",
      "description": "詳細なスキル説明",
      "tags": ["タグ1", "タグ2"],
      "examples": ["使用例1", "使用例2"]
    }
  ]
}

ステップ3：依存関係ファイルの作成

requirements.txtで：

google-adk[a2a]>=1.6.1

__init__.pyで：

# プロジェクト初期化ファイル
from . import agent

A2Aサーバー起動とテスト

ステップ1：A2Aサーバーの起動

# プロジェクトルートディレクトリにいて、仮想環境がアクティブであることを確認
source .venv/bin/activate

# A2Aサーバーを起動
adk api_server --a2a --port 8001 remote_a2a

# 期待される出力：
# INFO:     Uvicorn running on http://127.0.0.1:8001 (Press CTRL+C to quit)
# INFO:     A2A endpoints enabled for agents: facts_agent

ステップ2：A2Aエンドポイントの確認

# エージェント発見エンドポイントをテスト
curl http://localhost:8001/a2a/facts_agent/.well-known/agent.json

# エージェント設定JSONが返されることを期待

ステップ3：A2Aサーバーアーキテクチャ分析

A2Aサーバーが起動すると、以下のエンドポイントが作成されます：

1. エージェント発見エンドポイント：/.well-known/agent.json

   • エージェントメタデータと機能情報を提供
   • 自動エージェント発見と設定に使用

2. メッセージ処理エンドポイント：/a2a/{agent_name}

   • 他のエージェントからメッセージを受信
   • A2Aプロトコルリクエストを処理

3. ヘルスチェックエンドポイント：/health

   • サーバー状態監視
   • ロードバランサーヘルスチェック

Web UI統合テスト

ステップ1：ADK Webサーバーの起動

新しいターミナルウィンドウで：

# 仮想環境をアクティベート
source .venv/bin/activate

# Web UIサーバーを起動
adk web .

# 期待される出力：
# INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
# INFO:     Available agents: facts_agent

ステップ2：Web UIテストプロセス

1. Web UIアクセス：ブラウザでhttp://localhost:8000を開く

2. エージェント選択：ドロップダウンメニューからfacts_agentを選択

3. 会話テスト：テストメッセージを入力、例えば：

   "人工知能に関する興味深い事実を教えてください"
   

4. 応答観察：エージェントが正しく応答し、Google検索ツールを使用することを確認

ステップ3：テストケース例

# テストケース1：基本的な事実クエリ
入力：万里の長城に関する興味深い事実は何ですか？
期待：検索ソースを含む万里の長城に関する興味深い事実を返す

# テストケース2：科学知識クエリ
入力：ブラックホールについて魅力的な事実を教えてください。
期待：ブラックホールに関する科学的事実を返す

# テストケース3：時事クエリ
入力：宇宙探査の最近の発見は何ですか？
期待：最新の宇宙探査発見を返す

A2A通信フローの詳細説明

完全なA2A通信シーケンス図

sequenceDiagram
    participant User as ユーザー
    participant WebUI as ADK Web UI<br/>(localhost:8000)
    participant Client as クライアントエージェント<br/>(RemoteA2aAgent)
    participant A2AServer as A2Aサーバー<br/>(localhost:8001)
    participant Agent as サーバーエージェント<br/>(facts_agent)
    participant LLM as Gemini LLM
    participant Search as Google検索

    User->>WebUI: 1. クエリメッセージ入力
    WebUI->>Client: 2. クライアントエージェント呼び出し
    
    Note over Client: 3. エージェント初期化チェック
    Client->>A2AServer: 4. GET /.well-known/agent.json
    A2AServer-->>Client: 5. エージェント設定を返す
    
    Note over Client: 6. A2Aメッセージ構築
    Client->>A2AServer: 7. POST /a2a/facts_agent<br/>A2Aメッセージ送信
    
    A2AServer->>Agent: 8. 内部イベントに変換
    Agent->>LLM: 9. プロンプト送信
    LLM-->>Agent: 10. 応答を返す（ツール呼び出し含む）
    
    Agent->>Search: 11. Google検索実行
    Search-->>Agent: 12. 検索結果を返す
    
    Agent->>LLM: 13. 検索結果を統合
    LLM-->>Agent: 14. 最終応答を生成
    
    Agent-->>A2AServer: 15. 処理結果を返す
    A2AServer-->>Client: 16. A2A応答を返す
    
    Note over Client: 17. 内部イベントに変換
    Client-->>WebUI: 18. 応答を返す
    WebUI-->>User: 19. 最終結果を表示

主要通信ステップ分析

1. エージェント発見フェーズ（ステップ4-5）

GET http://localhost:8001/a2a/facts_agent/.well-known/agent.json

応答：
{
  "name": "facts_agent",
  "url": "http://localhost:8001/a2a/facts_agent",
  "skills": [...]
}

2. メッセージ送信フェーズ（ステップ7）

POST http://localhost:8001/a2a/facts_agent
Content-Type: application/json

{
  "id": "uuid-123",
  "params": {
    "message": {
      "messageId": "msg-456",
      "parts": [{"text": "AIについての事実を教えてください"}],
      "role": "user"
    }
  }
}

3. 応答返却フェーズ（ステップ16）

HTTP/1.1 200 OK
Content-Type: application/json

{
  "result": {
    "messageId": "response-789",
    "parts": [{"text": "こちらは興味深いAIの事実です..."}],
    "role": "agent"
  }
}

まとめ

このガイドを通じて、ADKフレームワークを使用してA2Aプロトコルを実装し、完全なエージェント間通信システムを構築する方法を学びました。主要な学習内容は以下の通りです：

🎯 コアスキル

• ✅ ADK A2A環境設定：ゼロから開発環境を設定
• ✅ A2Aサーバーサイドエージェント開発：ADKを使用して実際の機能を持つインテリジェントエージェントを作成
• ✅ A2Aクライアントサイドエージェント開発：RemoteA2aAgentを通じてリモートエージェント接続を実装
• ✅ A2Aプロトコル理解：Agent2Agent通信プロトコルの深い習得
• ✅ ADK Web UIテスト：ADK提供のWeb UIを使用したエンドツーエンドテスト

🚀 技術的利点

• 標準化：A2Aプロトコルベースの標準化されたエージェント通信
• 分散：ADKはサーバー間A2Aエージェント展開をサポート
• スケーラブル：新機能の追加とA2Aエコシステムとの統合が容易
• 本番環境対応：エンタープライズグレードの安定性とセキュリティ

🔮 次のステップ

• より多くのADKツールとA2A統合オプションを探索
• マルチA2Aエージェント協調システムを構築
• カスタムA2Aプロトコル拡張を実装
• ADK A2Aソリューションを本番環境に展開

ADKのA2A実装は次世代インテリジェントエージェントシステム構築のための強力な基盤を提供し、エージェント協調をシンプルで効率的にします。ADK A2A開発の旅を始めましょう！

参考資料

• Google ADK公式ドキュメント
• A2Aプロトコル仕様
• Gemini APIドキュメント
• サンプルコードリポジトリ

キーワード：A2A ADK、Agent Development Kit、A2Aプロトコル、エージェント開発、インテリジェントエージェント通信、Google ADK、エージェントプロトコル、分散エージェントシステム、RemoteA2aAgent、Gemini API