A2A Samples: Hello World Agent

 

プロジェクト概要

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

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

Pythonバージョン要件

  • • Python >= 3.10

主要依存関係パッケージ

パッケージ名 バージョン 用途
a2a-sdk >= 0.2.5 A2Aコア SDK、エージェントフレームワークを提供
uvicorn >= 0.34.2 ASGIサーバー、Webアプリケーション実行用
click >= 8.1.8 コマンドラインインターフェースツール
httpx >= 0.28.1 非同期HTTPクライアント
pydantic >= 2.11.4 データ検証とシリアライゼーション
python-dotenv >= 1.1.0 環境変数管理
langchain-google-genai >= 2.1.4 Google Generative AI統合
langgraph >= 0.4.1 言語グラフ処理フレームワーク

プロジェクト構造

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クライアントとサーバーの相互作用フロー

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

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




エージェント設定



サーバー環境



ネットワーク通信



クライアント環境



テストクライアント起動



A2ACardResolver エージェントカード解析



A2AClient 初期化



メッセージリクエスト送信



レスポンス処理



HTTP/HTTPSリクエスト



JSONデータ転送



A2AStarletteApplication Webサーバー



DefaultRequestHandler リクエストハンドラー



HelloWorldAgentExecutor エージェント実行器



HelloWorldAgent コアエージェントロジック



InMemoryTaskStore タスクストレージ



EventQueue イベントキュー



パブリックエージェントカード 基本スキル



拡張エージェントカード 強化スキル



APIエンドポイント



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






	
		

			エンドポイント
			メソッド
			説明
		

	
	
		

			/.well-known/agent.json
			GET
			パブリックエージェントカード情報の取得
		

		

			/agent/message
			POST
			エージェントへのメッセージ送信
		

		

			/agent/message/stream
			POST
			ストリーミングメッセージ送信
		

	






認証エンドポイント






	
		

			エンドポイント
			メソッド
			説明
			認証
		

	
	
		

			/agent/authenticatedExtendedCard
			GET
			拡張エージェントカードの取得
			Bearer Token
		

	






スキル設定



基本スキル



    
	
  • • 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. 1. ポートが占有されている

	
    # ポート使用状況の確認
lsof -i :9999
# 占有プロセスの終了
kill -9 <PID>
    
	
    2. 
	
  2. 2. 依存関係インストールの失敗

	
    # キャッシュクリアと再インストール
uv cache clean
uv sync --reinstall
    
	
    3. 
	
  3. 3. Pythonバージョンの非互換性

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




拡張開発



新しいスキルの追加



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




外部API統合



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




まとめ



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



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




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



 



Python A2A