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

これは、Google Agent Development Kit (ADK)に基づいて開発された知能的な経費精算エージェントで、Agent2Agent (A2A)サーバーとして実行されます。このエージェントの核心機能は知能的フォーム生成です：ユーザーの精算リクエストに必要な情報が不足している場合、エージェントが自動的にユーザーが記入するフォームを生成し、処理前に完全な精算情報を収集することを保証します。

ソースコード

A2A ADK Sample

🎯 プロジェクトの特徴

• 知能的フォームインタラクション: 不足している情報を自動検出し、動的フォームを生成
• A2Aプロトコルサポート: 標準化されたエージェント間通信プロトコル
• ストリーミング処理: リアルタイム応答とステータス更新をサポート
• Google ADK統合: Googleの最新エージェント開発キットに基づく

📋 システム要件

• Python 3.12以上
• UVパッケージ管理ツール
• Google API Key（Geminiモデルアクセス）

🚀 クイックスタート

1. Google API Keyの取得

1. Google AI Studioにアクセス
2. Googleアカウントでログイン
3. "Get API key"をクリック
4. 新しいAPI keyを作成するか既存のものを使用
5. 後で使用するためにAPI keyをコピー

2. 環境設定

# プロジェクトをローカルにクローン（必要な場合）
git clone https://github.com/sing1ee/a2a-adk-expense-reimbursement.git
cd a2a-adk-expense-reimbursement

# 環境変数ファイルを作成
echo "GOOGLE_API_KEY=your_api_key_here" > .env

# your_api_key_hereを実際のAPI keyに置き換える

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

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

# uvを使用してプロジェクトを実行
uv run .

サーバーはhttp://localhost:10002で開始されます。

4. CLIクライアントでテスト

新しいターミナルウィンドウを開きます：

git clone https://github.com/a2aproject/a2a-samples.git
# CLIクライアントディレクトリに移動（samples/python/hosts/cliにあると仮定）
cd a2a-samples/samples/python/hosts/cli

# 精算エージェントに接続
uv run . --agent http://localhost:10002

5. テストインタラクション例

CLIクライアントで以下のテストコマンドを入力してください：

# 例1: 情報が不足しているリクエスト（フォームがトリガーされます）
昼食代$20を精算する必要があります

# 例2: 完全な情報があるリクエスト
2024年1月15日のクライアント昼食代$50を精算する必要があります

# 例3: 部分的な情報があるリクエスト
昨日の交通費$25を精算してください

🏗️ プロジェクトアーキテクチャ

コアファイル構造

a2a-adk-expense-reimbursement/
├── __main__.py          # サーバー起動エントリーポイント
├── agent.py             # コアエージェントロジック
├── agent_executor.py    # A2Aリクエストエグゼキューター
├── pyproject.toml       # プロジェクト設定と依存関係
└── README.md           # プロジェクトドキュメント

主要コンポーネントの説明

1. __main__.py - サーバーエントリー

• A2Aサーバーとエージェント情報の設定
• エージェントスキルと能力の説明を設定
• リクエストを受信するHTTPサーバーを開始

2. agent.py - コアエージェントロジック

3つの主要なツール関数を含む：

• create_request_form(): 精算フォームテンプレートを作成
• return_form(): フォームをA2Aプロトコル形式でラップして返す
• reimburse(): 実際の精算承認操作を実行

3. agent_executor.py - リクエストエグゼキューター

• A2Aプロトコルのリクエストとレスポンスを処理
• タスクステータスの管理（作業中、入力が必要、完了など）
• エージェントとA2Aサーバー間の通信を調整

🔄 コアワークフロー

以下のシーケンス図は、精算エージェントの完全なインタラクションフローを示しています：

sequenceDiagram
    participant User as ユーザー/CLIクライアント
    participant Server as A2Aサーバー
    participant Agent as 精算エージェント
    participant LLM as Gemini 2.0 Flash

    User->>Server: 精算リクエストを送信<br/>"昼食代$20を精算する必要があります"
    Server->>Agent: ユーザーリクエストを転送
    Agent->>LLM: リクエスト内容を分析
    LLM->>Agent: 日付などの情報が不足していることを識別
    Agent->>Agent: create_request_form()を呼び出し
    Agent->>Agent: return_form()を呼び出し
    Agent->>Server: フォーム構造を返す
    Server->>User: JSONフォームを返す<br/>日付、金額、目的フィールドを含む
    
    User->>User: ユーザーがフォームを記入<br/>日付、金額、目的
    User->>Server: 完成したフォームを送信
    Server->>Agent: フォームデータを転送
    Agent->>LLM: フォームの完全性を検証
    LLM->>Agent: 情報が完全であることを確認
    Agent->>Agent: reimburse(request_id)を呼び出し
    Agent->>Server: 承認結果を返す
    Server->>User: 最終結果を返す<br/>"精算が承認されました"

ワークフローの詳細

1. リクエスト受信: ユーザーがCLIクライアントを通じて精算リクエストを送信
2. 知能的分析: Geminiモデルがリクエストを分析し、不足している必要な情報を識別
3. フォーム生成: 情報が不完全な場合、必要なフィールドを含むフォームを自動生成
4. ユーザーインタラクション: ユーザーがフォームを記入して不足している情報を補完
5. 情報検証: フォームデータの完全性と有効性を検証
6. 精算処理: 精算承認を実行し、結果を返す

🛠️ 高度な設定

環境変数

# Google API設定
GOOGLE_API_KEY=your_api_key_here

# Vertex AIを使用（オプション）
GOOGLE_GENAI_USE_VERTEXAI=TRUE

# サーバー設定
HOST=localhost
PORT=10002

カスタムポートで実行

uv run . --host 0.0.0.0 --port 8080

🧪 開発とデバッグ

詳細ログの有効化

エージェントはデフォルトでINFOレベルのログを有効にします。詳細なリクエスト処理を確認：

# サーバーログを表示
uv run . 2>&1 | tee agent.log

フォーム構造の例

エージェントはJSON Schema形式に従うフォームを生成します：

{
  "type": "form",
  "form": {
    "type": "object",
    "properties": {
      "date": {
        "type": "string",
        "format": "date",
        "title": "Date",
        "description": "Date of expense"
      },
      "amount": {
        "type": "string",
        "format": "number", 
        "title": "Amount",
        "description": "Amount of expense"
      },
      "purpose": {
        "type": "string",
        "title": "Purpose",
        "description": "Purpose of expense"
      }
    },
    "required": ["date", "amount", "purpose"]
  }
}

⚠️ セキュリティ考慮事項

重要な注意: このサンプルコードは、Agent2Agent (A2A)プロトコルの動作方法を示すデモンストレーション目的のみです。本番アプリケーションを構築する際は、すべての外部エージェントを潜在的に信頼できないエンティティとして扱う必要があります。

セキュリティ対策

• 入力検証: すべての外部入力を厳密に検証し、サニタイズ
• データ処理: エージェントカード、メッセージ、アーティファクトなどのデータを慎重に処理
• 認証情報管理: 適切な認証情報保護措置を実装
• 権限制御: エージェントのアクセス権限と操作範囲を制限