A2A Samples: Hello World Agent

プロジェクト概要

これはA2A（Agent-to-Agent）SDKに基づくシンプルなHello Worldエージェントの例です。このプロジェクトでは、ユーザーメッセージに応答し、シンプルな挨拶を返すことができる基本的なインテリジェントエージェントサーバーの作成方法を示します。

依存関係バージョンの説明

Pythonバージョン要件

• Python >= 3.10

主要依存関係パッケージ

プロジェクト構造

helloworld/
├── __init__.py              # パッケージ初期化ファイル
├── __main__.py              # メインプログラムエントリーポイント
├── agent_executor.py        # エージェント実行器実装
├── test_client.py           # テストクライアント
├── pyproject.toml           # プロジェクト設定と依存関係
├── uv.lock                  # 依存関係ロックファイル
└── README.md                # プロジェクトドキュメント

環境セットアップ

1. UVパッケージマネージャーのインストール

まだUVをインストールしていない場合は、まずインストールしてください：

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# またはpipを使用
pip install uv

2. プロジェクトのクローン

git clone https://github.com/google-a2a/a2a-samples.git
cd a2a-samples/samples/python/agents/helloworld

3. 依存関係のインストール

UVはpyproject.tomlとuv.lockファイルに従って自動的にすべての依存関係をインストールします：

uv sync

コードアーキテクチャの説明

主要コンポーネント

1. HelloWorldAgent (agent_executor.py)

class HelloWorldAgent:
    """Hello World Agent."""
    
    async def invoke(self) -> str:
        return 'Hello World'

2. HelloWorldAgentExecutor (agent_executor.py)

class HelloWorldAgentExecutor(AgentExecutor):
    """エージェント実行器実装"""
    
    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
        result = await self.agent.invoke()
        event_queue.enqueue_event(new_agent_text_message(result))

3. サーバー設定 (__main__.py)

• エージェントスキルの定義（AgentSkill）
• パブリックおよび拡張エージェントカードの設定（AgentCard）
• リクエストハンドラーとタスクストレージのセットアップ
• Uvicornサーバーの起動

実行手順

1. エージェントサーバーの起動

uv run .

サーバーはhttp://localhost:9999で起動します。

2. テストクライアントの実行

別のターミナルウィンドウで：

uv run test_client.py

3. サービスの検証

以下の方法でサービスが正常に動作していることを確認できます：

エージェントカード情報へのアクセス

curl http://localhost:9999/.well-known/agent.json

拡張エージェントカードへのアクセス（認証が必要）

curl -H "Authorization: Bearer dummy-token-for-extended-card" \
     http://localhost:9999/agent/authenticatedExtendedCard

プロジェクトフローチャート

A2Aクライアントとサーバーの相互作用フロー

sequenceDiagram
    participant Client as A2A Client
    participant Server as A2A Server
    participant Agent as HelloWorldAgent
    participant Queue as EventQueue
    
    Note over Client,Server: 1. サービス発見フェーズ
    Client->>Server: GET /.well-known/agent.json
    Server-->>Client: パブリックエージェントカードを返す
    
    Note over Client,Server: 2. 拡張カード取得（オプション）
    Client->>Server: GET /agent/authenticatedExtendedCard<br/>(with Bearer token)
    Server-->>Client: 拡張エージェントカードを返す
    
    Note over Client,Server: 3. メッセージ送信フロー
    Client->>Server: POST /agent/message<br/>{"message": {"role": "user", "parts": [...]}}
    
    Note over Server,Queue: 4. サーバー内部処理
    Server->>Agent: HelloWorldAgentExecutor.execute()を呼び出し
    Agent->>Agent: HelloWorldAgent.invoke()を実行
    Agent-->>Queue: "Hello World"メッセージを生成
    Queue-->>Server: イベントキュー結果を返す
    
    Note over Client,Server: 5. レスポンス返却
    Server-->>Client: メッセージレスポンスを返す
    
    Note over Client,Server: 6. ストリーミングメッセージ処理（オプション）
    Client->>Server: POST /agent/message/stream
    Server-->>Client: メッセージチャンクをストリーミング返却
    Server-->>Client: メッセージチャンク1
    Server-->>Client: メッセージチャンク2
    Server-->>Client: 終了マーカー

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

graph TB
    subgraph "クライアント環境"
        C1[テストクライアント起動]
        C2[A2ACardResolver<br/>エージェントカード解析]
        C3[A2AClient<br/>初期化]
        C4[メッセージリクエスト送信]
        C5[レスポンス処理]
    end
    
    subgraph "ネットワーク通信"
        N1[HTTP/HTTPSリクエスト]
        N2[JSONデータ転送]
    end
    
    subgraph "サーバー環境"
        S1[A2AStarletteApplication<br/>Webサーバー]
        S2[DefaultRequestHandler<br/>リクエストハンドラー]
        S3[HelloWorldAgentExecutor<br/>エージェント実行器]
        S4[HelloWorldAgent<br/>コアエージェントロジック]
        S5[InMemoryTaskStore<br/>タスクストレージ]
        S6[EventQueue<br/>イベントキュー]
    end
    
    subgraph "エージェント設定"
        A1[パブリックエージェントカード<br/>基本スキル]
        A2[拡張エージェントカード<br/>強化スキル]
    end
    
    %% クライアントフロー
    C1 --> C2
    C2 --> C3
    C3 --> C4
    C4 --> C5
    
    %% ネットワーク通信
    C4 --> N1
    N1 --> N2
    N2 --> S1
    S1 --> N2
    N2 --> C5
    
    %% サーバーフロー
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S6
    S6 --> S3
    S3 --> S2
    S2 --> S1
    
    %% 設定関連
    A1 --> S1
    A2 --> S1
    S2 --> S5
    
    %% スタイリング
    style C3 fill:#e3f2fd
    style S1 fill:#f3e5f5
    style S4 fill:#e8f5e8
    style N2 fill:#fff3e0

APIエンドポイント

パブリックエンドポイント

認証エンドポイント

スキル設定

基本スキル

• ID: hello_world
• 名前: Returns hello world
• 説明: just returns hello world
• 例: ['hi', 'hello world']

拡張スキル（認証が必要）

• ID: super_hello_world
• 名前: Returns a SUPER Hello World
• 説明: A more enthusiastic greeting, only for authenticated users
• 例: ['super hi', 'give me a super hello']

トラブルシューティング

一般的な問題

1. ポートが占有されている

   # ポート使用状況の確認
   lsof -i :9999
   # 占有プロセスの終了
   kill -9 <PID>
   

2. 依存関係インストールの失敗

   # キャッシュクリアと再インストール
   uv cache clean
   uv sync --reinstall
   

3. Pythonバージョンの非互換性

   # Pythonバージョンの確認
   python --version
   # バージョン >= 3.10であることを確認
   

拡張開発

新しいスキルの追加

1. __main__.pyで新しいAgentSkillを定義
2. agent_executor.pyでロジック処理を変更
3. エージェントカード設定を更新

外部API統合

1. pyproject.tomlに新しい依存関係を追加
2. agent_executor.pyでAPI呼び出しを実装
3. 非同期レスポンスとエラーを処理

まとめ

このHello World例では、A2A SDKの基本的な使用方法を示しています：

• エージェントサーバーの作成と設定
• スキルの定義と管理
• クライアント・サーバー通信
• 認証と拡張機能

この例を通じて、独自のインテリジェントエージェントアプリケーションの構築方法を素早く理解できます。