A2A Protocol

A2A Python Exemple : Agent GitHub

English中文русскийportuguês한국어日本語हिंदीfrançaisdeutsch
MILO•
Share
A2A Python Exemple : Agent GitHub

Un agent GitHub intelligent construit avec le SDK A2A (Agent2Agent) qui peut interroger les dépôts GitHub, les mises à jour récentes, les commits et l'activité des projets en utilisant le langage naturel.

🏗️ Architecture

Ce projet implémente un serveur A2A qui utilise un agent basé sur OpenAI avec l'intégration de l'API GitHub. L'architecture se compose des composants clés suivants :

Aperçu des composants

  • Serveur A2A (__main__.py) : L'application serveur principale qui gère les requêtes HTTP et gère le cycle de vie de l'agent
  • Exécuteur d'agent OpenAI (openai_agent_executor.py) : Exécute les tâches de l'agent avec l'intégration de l'API OpenRouter
  • Ensemble d'outils GitHub (github_toolset.py) : Fournit des outils API GitHub pour les opérations de dépôt
  • Définition de l'agent (openai_agent.py) : Définit les capacités de l'agent et l'invite système

Flux d'architecture

sequenceDiagram
    participant Client as Client A2A
    participant Server as Serveur A2A
    participant Agent as Agent OpenAI
    participant GitHub as API GitHub
    participant OpenRouter as API OpenRouter

    Note over Client,OpenRouter: Architecture de l'Agent GitHub A2A

    Client->>Server: Requête HTTP<br/>(requête sur GitHub)
    Server->>Agent: Traiter la requête<br/>(OpenAIAgentExecutor)
    
    Agent->>OpenRouter: Envoyer la complétion de chat<br/>(avec outils définis)
    OpenRouter-->>Agent: Réponse avec appels d'outils

    loop Exécution d'outils
        Agent->>GitHub: Appel API<br/>(GitHubToolset)
        GitHub-->>Agent: Données de dépôt/commit
        Agent->>OpenRouter: Envoyer les résultats des outils
        OpenRouter-->>Agent: Réponse finale
    end

    Agent->>Server: Réponse en streaming<br/>(TaskUpdater)
    Server->>Client: Réponse HTTP<br/>(résultats formatés)

    Note over Client: L'utilisateur voit les données GitHub<br/>formatées par l'IA

🔧 Logique des modules clés

1. Serveur principal (__main__.py)

  • Initialise le serveur A2A avec le framework Starlette
  • Crée une AgentCard qui définit les capacités et compétences de l'agent
  • Configure l'exécuteur d'agent OpenAI avec les outils GitHub
  • Démarre le serveur HTTP sur l'hôte et le port spécifiés

2. Ensemble d'outils GitHub (github_toolset.py)

Fournit trois fonctions principales de l'API GitHub :

  • get_user_repositories() : Récupère les dépôts récents pour un utilisateur
  • get_recent_commits() : Récupère les commits récents pour un dépôt spécifique
  • search_repositories() : Recherche des dépôts avec une activité récente

Toutes les fonctions incluent la gestion des erreurs et prennent en charge les paramètres optionnels pour le filtrage.

3. Exécuteur d'agent OpenAI (openai_agent_executor.py)

  • Gère le flux de conversation avec l'API OpenRouter
  • Convertit les outils GitHub au format d'appel de fonction OpenAI
  • Gère l'exécution des outils et le streaming des réponses
  • Implémente une conversation itérative avec des appels d'outils

4. Définition de l'agent (openai_agent.py)

  • Crée l'agent avec l'invite système et les outils disponibles
  • Définit le comportement de l'agent pour les requêtes liées à GitHub
  • Configure l'agent pour fournir des informations utiles sur les dépôts

📋 Prérequis

  • Python 3.10 ou supérieur
  • UV - Gestionnaire de paquets Python
  • Clé API OpenRouter - Pour les capacités IA
  • Jeton d'accès personnel GitHub (optionnel, mais recommandé pour des limites de taux plus élevées)

🚀 Configuration et exécution étape par étape

Étape 1 : Cloner et configurer l'environnement

# Cloner le dépôt
git clone https://github.com/sing1ee/a2a-py-github-agent.git
cd a2a-py-github-agent

# Créer un environnement virtuel
uv venv
source .venv/bin/activate  # Sur Windows : .venv\Scripts\activate

Étape 2 : Installer les dépendances

# Installer les dépendances en utilisant UV
uv sync

Étape 3 : Configurer les variables d'environnement

Créez un fichier .env à la racine du projet :

# Clé API OpenRouter (obligatoire)
echo "OPENROUTER_API_KEY=your_openrouter_api_key_here" > .env

# Jeton d'accès personnel GitHub (optionnel mais recommandé)
echo "GITHUB_TOKEN=your_github_personal_access_token_here" >> .env

Note : Le jeton GitHub est optionnel. Sans lui, l'agent utilisera un accès non authentifié avec des limites de taux limitées (60 requêtes par heure vs 5000 avec jeton).

Étape 4 : Exécuter le serveur A2A

# Activer l'environnement virtuel
source .venv/bin/activate

# Exécuter le serveur
uv run .

Le serveur démarrera sur http://localhost:10007 par défaut.

🧪 Test du client

Option 1 : Utilisation du client A2A Movie Agent

Vous pouvez tester l'agent GitHub en utilisant le client A2A Movie Agent :

# Cloner le client A2A Movie Agent
git clone https://github.com/sing1ee/a2a-js-movie-agent.git
cd a2a-js-movie-agent

# Installer les dépendances
bun install

# Se connecter à votre agent GitHub
bun cli http://localhost:10007

Cela démarrera un CLI interactif qui se connecte à votre serveur d'agent GitHub.

Option 2 : Utilisation de requêtes HTTP directes

Vous pouvez également tester en utilisant curl ou tout client HTTP :

# Exemple : Test avec une requête simple
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": "Afficher les commits récents pour le dépôt 'facebook/react'"
        }
      ],
      "messageId": "9229e770-767c-417b-a0b0-f0741243c589"
    },
    "metadata": {}
  }
}'

💡 Exemples de requêtes

L'agent GitHub peut gérer des requêtes comme :

  • Commits récents : "Afficher les commits récents pour le dépôt 'facebook/react'"
  • Recherche de dépôts : "Rechercher des dépôts Python populaires avec une activité récente"
  • Activité de projet : "Quelles sont les dernières mises à jour dans les dépôts d'apprentissage automatique ?"

🔑 Configuration du jeton GitHub

Pour créer un jeton d'accès personnel GitHub pour de meilleures limites de taux :

  1. Allez dans Paramètres GitHub > Jetons
  2. Cliquez sur "Générer un nouveau jeton (classique)"
  3. Sélectionnez les portées suivantes :
    • repo - Accès aux dépôts
    • user - Accès aux informations utilisateur
  4. Copiez le jeton et ajoutez-le à votre fichier .env

🛠️ Options de configuration

Configuration du serveur

Vous pouvez personnaliser le serveur en utilisant les options de ligne de commande :

# Hôte et port personnalisés
uv run . --host=0.0.0.0 --port=10007

Variables d'environnement

  • OPENROUTER_API_KEY : Votre clé API OpenRouter (obligatoire)
  • GITHUB_TOKEN : Jeton d'accès personnel GitHub (optionnel)

📖 Documentation de l'API

Outils disponibles

  1. get_user_repositories

    • Obtenir les dépôts de l'utilisateur avec des mises à jour récentes
    • Paramètres : username (optionnel), days (défaut : 30), limit (défaut : 10)

  2. get_recent_commits

    • Obtenir les commits récents pour un dépôt
    • Paramètres : repo_name (obligatoire), days (défaut : 7), limit (défaut : 10)

  3. search_repositories

    • Rechercher des dépôts avec une activité récente
    • Paramètres : query (obligatoire), sort (défaut : 'updated'), limit (défaut : 10)

📄 Licence

Ce projet est sous licence MIT - voir le fichier LICENSE pour plus de détails.

🔗 Projets connexes

  • A2A SDK - L'implémentation sous-jacente du protocole A2A
  • A2A Movie Agent - Un agent d'information sur les films construit avec le protocole A2A