A2A Protocol

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

English中文русскийportuguês한국어日本語हिंदीfrançaisdeutsch
MILO•
Share
A2A Python サンプル: GitHub エージェント

自然言語を使用してGitHubリポジトリ、最新の更新、コミット、プロジェクトアクティビティをクエリできるA2A（Agent2Agent）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): エージェントの機能とシステムプロンプトを定義

アーキテクチャフロー

sequenceDiagram
    participant Client as A2A クライアント
    participant Server as A2A サーバー
    participant Agent as OpenAI エージェント
    participant GitHub as GitHub API
    participant OpenRouter as OpenRouter API

    Note over Client,OpenRouter: A2A GitHub エージェントアーキテクチャ

    Client->>Server: HTTPリクエスト<br/>(GitHubに関するクエリ)
    Server->>Agent: リクエスト処理<br/>(OpenAIAgentExecutor)
    
    Agent->>OpenRouter: チャット完了送信<br/>(定義されたツールと共に)
    OpenRouter-->>Agent: ツール呼び出しを含む応答

    loop ツール実行
        Agent->>GitHub: API呼び出し<br/>(GitHubToolset)
        GitHub-->>Agent: リポジトリ/コミットデータ
        Agent->>OpenRouter: ツール結果送信
        OpenRouter-->>Agent: 最終応答
    end

    Agent->>Server: ストリーミング応答<br/>(TaskUpdater)
    Server->>Client: HTTP応答<br/>(フォーマットされた結果)

    Note over Client: ユーザーがAIによって<br/>フォーマットされたGitHubデータを確認

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

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プロトコルで構築された映画情報エージェント