A2A Python サンプル: GitHub エージェント

自然言語を使用してGitHubリポジトリ、最新の更新、コミット、プロジェクトアクティビティをクエリできるA2A（Agent-to-Agent）SDKで構築されたインテリジェントなGitHubエージェントです。

🏗️ アーキテクチャ

このプロジェクトは、GitHub API統合を備えたOpenAIベースのエージェントを使用するA2Aサーバーを実装しています。アーキテクチャは以下の主要コンポーネントで構成されています：

コンポーネント概要

• A2A サーバー (__main__.py): HTTPリクエストを処理し、エージェントのライフサイクルを管理するメインサーバーアプリケーション
• OpenAI エージェント実行器 (openai_agent_executor.py): OpenRouter API統合でエージェントタスクを実行
• GitHub ツールセット (github_toolset.py): リポジトリ操作用のGitHub APIツールを提供
• エージェント定義 (openai_agent.py): エージェントの機能とシステムプロンプトを定義

アーキテクチャフロー

🔧 主要モジュールロジック

1. メインサーバー (__main__.py)

• StarletteフレームワークでA2Aサーバーを初期化
• エージェントの機能とスキルを定義するAgentCardを作成
• GitHubツールを備えたOpenAIエージェント実行器をセットアップ
• 指定されたホストとポートでHTTPサーバーを開始

2. GitHub ツールセット (github_toolset.py)

3つの主要なGitHub API機能を提供：

• get_user_repositories(): ユーザーの最新リポジトリを取得
• get_recent_commits(): 特定のリポジトリの最新コミットを取得
• search_repositories(): 最近のアクティビティがあるリポジトリを検索

すべての機能にはエラーハンドリングが含まれ、フィルタリング用のオプションパラメータをサポートしています。

3. OpenAI エージェント実行器 (openai_agent_executor.py)

• OpenRouter APIとの会話フローを管理
• GitHubツールをOpenAI関数呼び出し形式に変換
• ツール実行と応答ストリーミングを処理
• ツール呼び出しを伴う反復的な会話を実装

4. エージェント定義 (openai_agent.py)

• システムプロンプトと利用可能なツールでエージェントを作成
• GitHub関連クエリに対するエージェントの動作を定義
• 有用なリポジトリ情報を提供するようにエージェントを設定

📋 前提条件

• Python 3.10以上
• UV - Pythonパッケージマネージャー
• OpenRouter APIキー - AI機能用
• GitHub個人アクセストークン（オプションですが、より高いレート制限のため推奨）

🚀 ステップバイステップセットアップと実行

ステップ1: クローンと環境セットアップ

# リポジトリをクローン
git clone https://github.com/sing1ee/a2a-py-github-agent.git
cd a2a-py-github-agent

# 仮想環境を作成
uv venv
source .venv/bin/activate  # Windowsの場合: .venv\Scripts\activate

ステップ2: 依存関係のインストール

# UVを使用して依存関係をインストール
uv sync

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

プロジェクトルートに.envファイルを作成：

# OpenRouter APIキー（必須）
echo "OPENROUTER_API_KEY=your_openrouter_api_key_here" > .env

# GitHub個人アクセストークン（オプションですが推奨）
echo "GITHUB_TOKEN=your_github_personal_access_token_here" >> .env

注意: GitHubトークンはオプションです。トークンなしでは、エージェントは制限されたレート制限（トークンありの5000回に対して1時間あたり60回のリクエスト）で認証されていないアクセスを使用します。

ステップ4: A2Aサーバーの実行

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

# サーバーを実行
uv run .

サーバーはデフォルトでhttp://localhost:10007で開始されます。

🧪 クライアントテスト

オプション1: A2A Movie Agentクライアントの使用

A2A Movie Agentクライアントを使用してGitHubエージェントをテストできます：

# A2A Movie Agentクライアントをクローン
git clone https://github.com/sing1ee/a2a-js-movie-agent.git
cd a2a-js-movie-agent

# 依存関係をインストール
bun install

# GitHubエージェントに接続
bun cli http://localhost:10007

これにより、GitHubエージェントサーバーに接続するインタラクティブなCLIが開始されます。

オプション2: 直接HTTPリクエストの使用

curlまたは任意のHTTPクライアントを使用してテストすることもできます：

# 例: シンプルなクエリでテスト
curl -X POST http://localhost:10007/ \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "リポジトリ 'facebook/react' の最新コミットを表示してください"
        }
      ],
      "messageId": "9229e770-767c-417b-a0b0-f0741243c589"
    },
    "metadata": {}
  }
}'

💡 クエリ例

GitHubエージェントは以下のようなクエリを処理できます：

• 最新コミット: "リポジトリ 'facebook/react' の最新コミットを表示してください"
• リポジトリ検索: "最近のアクティビティがある人気のPythonリポジトリを検索してください"
• プロジェクトアクティビティ: "機械学習リポジトリの最新アップデートは何ですか？"

🔑 GitHubトークンセットアップ

より良いレート制限のためにGitHub個人アクセストークンを作成するには：

1. GitHub設定 > トークンに移動
2. "新しいトークンを生成（クラシック）"をクリック
3. 以下のスコープを選択：
   • repo - リポジトリへのアクセス
   • user - ユーザー情報へのアクセス
4. トークンをコピーして.envファイルに追加

🛠️ 設定オプション

サーバー設定

コマンドラインオプションを使用してサーバーをカスタマイズできます：

# カスタムホストとポート
uv run . --host=0.0.0.0 --port=10007

環境変数

• OPENROUTER_API_KEY: OpenRouter APIキー（必須）
• GITHUB_TOKEN: GitHub個人アクセストークン（オプション）

📖 API ドキュメント

利用可能なツール

1. get_user_repositories

   • 最新の更新があるユーザーのリポジトリを取得
   • パラメータ: username（オプション）、days（デフォルト: 30）、limit（デフォルト: 10）

2. get_recent_commits

   • リポジトリの最新コミットを取得
   • パラメータ: repo_name（必須）、days（デフォルト: 7）、limit（デフォルト: 10）

3. search_repositories

   • 最近のアクティビティがあるリポジトリを検索
   • パラメータ: query（必須）、sort（デフォルト: 'updated'）、limit（デフォルト: 10）

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています - 詳細はLICENSEファイルを参照してください。

🔗 関連プロジェクト

• A2A SDK - 基盤となるA2Aプロトコル実装
• A2A Movie Agent - A2Aプロトコルで構築された映画情報エージェント

A2A Python