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
🎯 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
- Besuchen Sie Google AI Studio
- Melden Sie sich mit Ihrem Google-Konto an
- Klicken Sie auf "Get API key"
- Erstellen Sie einen neuen API-Schlüssel oder verwenden Sie einen vorhandenen
- 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 erstellenreturn_form()
: Formular in A2A-Protokollformat verpacken und zurückgebenreimburse()
: 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
- Anfrage-Empfang: Benutzer sendet Erstattungsanfrage über CLI-Client
- Intelligente Analyse: Gemini-Modell analysiert Anfrage und identifiziert fehlende notwendige Informationen
- Formular-Generierung: Wenn Informationen unvollständig sind, automatisch Formular mit erforderlichen Feldern generieren
- Benutzer-Interaktion: Benutzer füllt Formular aus, um fehlende Informationen zu ergänzen
- Informations-Validierung: Vollständigkeit und Gültigkeit der Formulardaten validieren
- 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