A2A ADK Spesenerstattungs-Agent

Dies ist ein intelligenter Spesenerstattungs-Agent, der auf dem Google Agent Development Kit (ADK) basiert und als Agent2Agent (A2A) Server läuft. Das Kernmerkmal dieses Agenten ist die intelligente Formular-Generierung: Wenn einer Benutzer-Erstattungsanfrage notwendige Informationen fehlen, generiert der Agent automatisch ein Formular für den Benutzer zum Ausfüllen und stellt sicher, dass vollständige Erstattungsinformationen vor der Verarbeitung gesammelt werden.

Quellcode

A2A ADK Sample

🎯 Projekt-Features

• Intelligente Formular-Interaktion: Erkennt automatisch fehlende Informationen und generiert dynamische Formulare
• A2A-Protokoll-Unterstützung: Standardisiertes Inter-Agent-Kommunikationsprotokoll
• Streaming-Verarbeitung: Unterstützt Echtzeit-Antworten und Status-Updates
• Google ADK-Integration: Basiert auf Googles neuestem Agent Development Kit

📋 Systemanforderungen

• Python 3.12 oder höher
• UV Paket-Management-Tool
• Google API Key (Gemini-Modell-Zugang)

🚀 Schnellstart

1. Google API Key erhalten

1. Besuchen Sie Google AI Studio
2. Melden Sie sich mit Ihrem Google-Konto an
3. Klicken Sie auf "Get API key"
4. Erstellen Sie einen neuen API-Schlüssel oder verwenden Sie einen vorhandenen
5. Kopieren Sie den API-Schlüssel für die spätere Verwendung

2. Umgebungskonfiguration

# Projekt lokal klonen (falls erforderlich)
git clone https://github.com/sing1ee/a2a-adk-expense-reimbursement.git
cd a2a-adk-expense-reimbursement

# Umgebungsvariablen-Datei erstellen
echo "GOOGLE_API_KEY=your_api_key_here" > .env

# your_api_key_here durch Ihren tatsächlichen API-Schlüssel ersetzen

3. Abhängigkeiten installieren und ausführen

# Virtuelle Umgebung aktivieren
source .venv/bin/activate

# Projekt mit uv ausführen
uv run .

Der Server startet unter http://localhost:10002.

4. Mit CLI-Client testen

Öffnen Sie ein neues Terminal-Fenster:

git clone https://github.com/a2aproject/a2a-samples.git
# Zum CLI-Client-Verzeichnis navigieren (angenommen in samples/python/hosts/cli)
cd a2a-samples/samples/python/hosts/cli

# Mit dem Erstattungs-Agent verbinden
uv run . --agent http://localhost:10002

5. Test-Interaktions-Beispiele

Geben Sie die folgenden Testbefehle im CLI-Client ein:

# Beispiel 1: Anfrage mit fehlenden Informationen (löst Formular aus)
Ich muss 20$ für das Mittagessen erstattet bekommen

# Beispiel 2: Anfrage mit vollständigen Informationen
Ich muss 50$ für ein Kunden-Mittagessen am 15. Januar 2024 erstattet bekommen

# Beispiel 3: Anfrage mit teilweisen Informationen
Bitte helfen Sie mir, die gestrigen Transportkosten von 25$ erstattet zu bekommen

🏗️ Projekt-Architektur

Kern-Dateistruktur

a2a-adk-expense-reimbursement/
├── __main__.py          # Server-Start-Einstiegspunkt
├── agent.py             # Kern-Agent-Logik
├── agent_executor.py    # A2A-Anfrage-Executor
├── pyproject.toml       # Projektkonfiguration und Abhängigkeiten
└── README.md           # Projektdokumentation

Hauptkomponenten-Beschreibung

1. __main__.py - Server-Einstieg

• A2A-Server und Agent-Informationen konfigurieren
• Agent-Fähigkeiten und Capability-Beschreibungen festlegen
• HTTP-Server starten, um auf Anfragen zu hören

2. agent.py - Kern-Agent-Logik

Enthält drei wichtige Tool-Funktionen:

• create_request_form(): Erstattungsformular-Vorlage erstellen
• return_form(): Formular in A2A-Protokollformat verpacken und zurückgeben
• reimburse(): Tatsächliche Erstattungsgenehmigungsoperation ausführen

3. agent_executor.py - Anfrage-Executor

• A2A-Protokoll-Anfragen und -Antworten verarbeiten
• Aufgabenstatus verwalten (arbeitet, benötigt Eingabe, abgeschlossen, etc.)
• Kommunikation zwischen Agent und A2A-Server koordinieren

🔄 Kern-Workflow

Das folgende Sequenzdiagramm zeigt den vollständigen Interaktionsfluss des Erstattungs-Agenten:

sequenceDiagram
    participant User as Benutzer/CLI-Client
    participant Server as A2A-Server
    participant Agent as Erstattungs-Agent
    participant LLM as Gemini 2.0 Flash

    User->>Server: Erstattungsanfrage senden<br/>"Ich muss 20$ für das Mittagessen erstattet bekommen"
    Server->>Agent: Benutzeranfrage weiterleiten
    Agent->>LLM: Anfrageinhalt analysieren
    LLM->>Agent: Fehlende Datum und andere Infos identifizieren
    Agent->>Agent: create_request_form() aufrufen
    Agent->>Agent: return_form() aufrufen
    Agent->>Server: Formularstruktur zurückgeben
    Server->>User: JSON-Formular zurückgeben<br/>mit Datum-, Betrag-, Zweck-Feldern
    
    User->>User: Benutzer füllt Formular aus<br/>Datum, Betrag, Zweck
    User->>Server: Ausgefülltes Formular einreichen
    Server->>Agent: Formulardaten weiterleiten
    Agent->>LLM: Formular-Vollständigkeit validieren
    LLM->>Agent: Bestätigen, dass Informationen vollständig sind
    Agent->>Agent: reimburse(request_id) aufrufen
    Agent->>Server: Genehmigungsergebnis zurückgeben
    Server->>User: Endergebnis zurückgeben<br/>"Erstattung genehmigt"

Workflow-Details

1. Anfrage-Empfang: Benutzer sendet Erstattungsanfrage über CLI-Client
2. Intelligente Analyse: Gemini-Modell analysiert Anfrage und identifiziert fehlende notwendige Informationen
3. Formular-Generierung: Wenn Informationen unvollständig sind, automatisch Formular mit erforderlichen Feldern generieren
4. Benutzer-Interaktion: Benutzer füllt Formular aus, um fehlende Informationen zu ergänzen
5. Informations-Validierung: Vollständigkeit und Gültigkeit der Formulardaten validieren
6. Erstattungs-Verarbeitung: Erstattungsgenehmigung ausführen und Ergebnis zurückgeben

🛠️ Erweiterte Konfiguration

Umgebungsvariablen

# Google API-Konfiguration
GOOGLE_API_KEY=your_api_key_here

# Vertex AI verwenden (optional)
GOOGLE_GENAI_USE_VERTEXAI=TRUE

# Server-Konfiguration
HOST=localhost
PORT=10002

Mit benutzerdefiniertem Port ausführen

uv run . --host 0.0.0.0 --port 8080

🧪 Entwicklung und Debugging

Ausführliche Protokollierung aktivieren

Der Agent aktiviert standardmäßig INFO-Level-Protokollierung. Detaillierte Anfrageverarbeitung anzeigen:

# Server-Logs anzeigen
uv run . 2>&1 | tee agent.log

Formular-Struktur-Beispiel

Der Agent generiert Formulare nach JSON-Schema-Format:

{
  "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"]
  }
}

⚠️ Sicherheitsüberlegungen

Wichtiger Hinweis: Dieser Beispielcode dient nur zu Demonstrationszwecken, um zu zeigen, wie das Agent2Agent (A2A)-Protokoll funktioniert. Beim Erstellen von Produktionsanwendungen muss jeder externe Agent als potenziell nicht vertrauenswürdige Entität behandelt werden.

Sicherheitsmaßnahmen

• Eingabe-Validierung: Alle externen Eingaben strikt validieren und bereinigen
• Datenverarbeitung: Agent-Karten, Nachrichten, Artefakte und andere Daten vorsichtig behandeln
• Anmeldedaten-Management: Angemessene Anmeldedaten-Schutzmaßnahmen implementieren
• Berechtigungs-Kontrolle: Agent-Zugriffsberechtigungen und Operationsbereich begrenzen