A2A Python Beispiel: GitHub Agent

Ein intelligenter GitHub-Agent, der mit dem A2A (Agent2Agent) SDK erstellt wurde und GitHub-Repositories, aktuelle Updates, Commits und Projektaktivitäten mit natürlicher Sprache abfragen kann.

🏗️ Architektur

Dieses Projekt implementiert einen A2A-Server, der einen OpenAI-basierten Agent mit GitHub-API-Integration verwendet. Die Architektur besteht aus folgenden Schlüsselkomponenten:

Komponentenübersicht

• A2A Server (__main__.py): Die Hauptserveranwendung, die HTTP-Anfragen verarbeitet und den Agent-Lebenszyklus verwaltet
• OpenAI Agent Executor (openai_agent_executor.py): Führt Agent-Aufgaben mit OpenRouter-API-Integration aus
• GitHub Toolset (github_toolset.py): Stellt GitHub-API-Tools für Repository-Operationen bereit
• Agent Definition (openai_agent.py): Definiert Agent-Fähigkeiten und System-Prompt

Architektur-Fluss

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

    Note over Client,OpenRouter: A2A GitHub Agent Architektur

    Client->>Server: HTTP-Anfrage<br/>(GitHub-Abfrage)
    Server->>Agent: Anfrage verarbeiten<br/>(OpenAIAgentExecutor)
    
    Agent->>OpenRouter: Chat-Completion senden<br/>(mit definierten Tools)
    OpenRouter-->>Agent: Antwort mit Tool-Aufrufen

    loop Tool-Ausführung
        Agent->>GitHub: API-Aufruf<br/>(GitHubToolset)
        GitHub-->>Agent: Repository/Commit-Daten
        Agent->>OpenRouter: Tool-Ergebnisse senden
        OpenRouter-->>Agent: Finale Antwort
    end

    Agent->>Server: Streaming-Antwort<br/>(TaskUpdater)
    Server->>Client: HTTP-Antwort<br/>(formatierte Ergebnisse)

    Note over Client: Benutzer sieht KI-formatierte<br/>GitHub-Daten

🔧 Schlüsselmodul-Logik

1. Hauptserver (__main__.py)

• Initialisiert A2A-Server mit Starlette-Framework
• Erstellt eine AgentCard, die Agent-Fähigkeiten und -Kompetenzen definiert
• Konfiguriert OpenAI-Agent-Executor mit GitHub-Tools
• Startet HTTP-Server auf angegebenem Host und Port

2. GitHub Toolset (github_toolset.py)

Stellt drei Haupt-GitHub-API-Funktionen bereit:

• get_user_repositories(): Ruft aktuelle Repositories für einen Benutzer ab
• get_recent_commits(): Ruft aktuelle Commits für ein spezifisches Repository ab
• search_repositories(): Sucht nach Repositories mit aktueller Aktivität

Alle Funktionen beinhalten Fehlerbehandlung und unterstützen optionale Parameter für Filterung.

3. OpenAI Agent Executor (openai_agent_executor.py)

• Verwaltet Konversationsfluss mit OpenRouter-API
• Konvertiert GitHub-Tools in OpenAI-Funktionsaufruf-Format
• Behandelt Tool-Ausführung und Antwort-Streaming
• Implementiert iterative Konversation mit Tool-Aufrufen

4. Agent Definition (openai_agent.py)

• Erstellt Agent mit System-Prompt und verfügbaren Tools
• Definiert Agent-Verhalten für GitHub-bezogene Anfragen
• Konfiguriert Agent zur Bereitstellung hilfreicher Repository-Informationen

📋 Voraussetzungen

• Python 3.10 oder höher
• UV - Python-Paketmanager
• OpenRouter API-Schlüssel - Für KI-Fähigkeiten
• GitHub Personal Access Token (optional, aber empfohlen für höhere Rate-Limits)

🚀 Schritt-für-Schritt-Setup und -Ausführung

Schritt 1: Klonen und Umgebung einrichten

# Repository klonen
git clone https://github.com/sing1ee/a2a-py-github-agent.git
cd a2a-py-github-agent

# Virtuelle Umgebung erstellen
uv venv
source .venv/bin/activate  # Unter Windows: .venv\Scripts\activate

Schritt 2: Abhängigkeiten installieren

# Abhängigkeiten mit UV installieren
uv sync

Schritt 3: Umgebungsvariablen konfigurieren

Erstellen Sie eine .env-Datei im Projektroot:

# OpenRouter API-Schlüssel (erforderlich)
echo "OPENROUTER_API_KEY=your_openrouter_api_key_here" > .env

# GitHub Personal Access Token (optional aber empfohlen)
echo "GITHUB_TOKEN=your_github_personal_access_token_here" >> .env

Hinweis: Das GitHub-Token ist optional. Ohne es verwendet der Agent unauthentifizierten Zugriff mit begrenzten Rate-Limits (60 Anfragen pro Stunde vs. 5000 mit Token).

Schritt 4: A2A-Server ausführen

# Virtuelle Umgebung aktivieren
source .venv/bin/activate

# Server ausführen
uv run .

Der Server startet standardmäßig auf http://localhost:10007.

🧪 Client-Tests

Option 1: A2A Movie Agent Client verwenden

Sie können den GitHub-Agent mit dem A2A Movie Agent Client testen:

# A2A Movie Agent Client klonen
git clone https://github.com/sing1ee/a2a-js-movie-agent.git
cd a2a-js-movie-agent

# Abhängigkeiten installieren
bun install

# Mit Ihrem GitHub-Agent verbinden
bun cli http://localhost:10007

Dies startet eine interaktive CLI, die sich mit Ihrem GitHub-Agent-Server verbindet.

Option 2: Direkte HTTP-Anfragen verwenden

Sie können auch mit curl oder jedem HTTP-Client testen:

# Beispiel: Test mit einfacher Anfrage
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": "Zeige aktuelle Commits für das Repository 'facebook/react'"
        }
      ],
      "messageId": "9229e770-767c-417b-a0b0-f0741243c589"
    },
    "metadata": {}
  }
}'

💡 Beispiel-Anfragen

Der GitHub-Agent kann Anfragen wie diese verarbeiten:

• Aktuelle Commits: "Zeige aktuelle Commits für das Repository 'facebook/react'"
• Repository-Suche: "Suche nach beliebten Python-Repositories mit aktueller Aktivität"
• Projektaktivität: "Was sind die neuesten Updates in Machine-Learning-Repositories?"

🔑 GitHub-Token-Konfiguration

Um ein GitHub Personal Access Token für bessere Rate-Limits zu erstellen:

1. Gehen Sie zu GitHub-Einstellungen > Token
2. Klicken Sie auf "Neues Token generieren (klassisch)"
3. Wählen Sie folgende Bereiche:
   • repo - Repository-Zugriff
   • user - Benutzerinformations-Zugriff
4. Kopieren Sie das Token und fügen Sie es zu Ihrer .env-Datei hinzu

🛠️ Konfigurationsoptionen

Server-Konfiguration

Sie können den Server mit Befehlszeilenoptionen anpassen:

# Benutzerdefinierter Host und Port
uv run . --host=0.0.0.0 --port=10007

Umgebungsvariablen

• OPENROUTER_API_KEY: Ihr OpenRouter-API-Schlüssel (erforderlich)
• GITHUB_TOKEN: GitHub Personal Access Token (optional)

📖 API-Dokumentation

Verfügbare Tools

1. get_user_repositories

   • Benutzer-Repositories mit aktuellen Updates abrufen
   • Parameter: username (optional), days (Standard: 30), limit (Standard: 10)

2. get_recent_commits

   • Aktuelle Commits für ein Repository abrufen
   • Parameter: repo_name (erforderlich), days (Standard: 7), limit (Standard: 10)

3. search_repositories

   • Repositories mit aktueller Aktivität suchen
   • Parameter: query (erforderlich), sort (Standard: 'updated'), limit (Standard: 10)

📄 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert - siehe die LICENSE-Datei für Details.

🔗 Verwandte Projekte

• A2A SDK - Die zugrunde liegende A2A-Protokoll-Implementierung
• A2A Movie Agent - Ein Filminfo-Agent, der mit dem A2A-Protokoll erstellt wurde