A2A Multi-Agent Beispiel: Zahlenratespiel

Projektübersicht

Dies ist ein Zahlenratespiel-Beispiel basierend auf dem Agent2Agent (A2A) Protocol, das zeigt, wie drei leichtgewichtige A2A Agents zusammenarbeiten, um ein klassisches Zahlenratespiel zu vervollständigen. Dieses Projekt dient als praktisches Einführungsbeispiel für das A2A Protocol und Python SDK mit folgenden Eigenschaften:

Keine LLM-Abhängigkeit: Benötigt keine API-Schlüssel oder große Sprachmodelle
Lokale Ausführung: Alle drei Agents laufen lokal ohne entfernte Server
Einfache Einrichtung: Minimale externe Abhängigkeiten
Kernkonzept-Demonstration: Zeigt die Kernfunktionalität des A2A Protocols

Agent-Rollenbeschreibung

Agent	Rolle	Aufgaben
AgentAlice	Evaluator	Wählt eine geheime Zahl von 1-100, bewertet Vermutungen und gibt Hinweise
AgentBob	CLI Frontend	Leitet Spielervermutungen weiter, zeigt Alices Hinweise an, interagiert mit Carol
AgentCarol	Visualizer	Generiert Textvisualisierung der Vermutungshistorie, mischt Historie auf Anfrage zufällig

Detaillierte Code-Datei-Analyse

1. Konfigurationsdatei (`config.py`)

AGENT_ALICE_PORT = 8001
AGENT_BOB_PORT = 8002
AGENT_CAROL_PORT = 8003

Zweck: Verwaltet Port-Konfigurationen zentral, um Port-Konflikte zu vermeiden. Alle Agents importieren Konfigurationen aus diesem Modul und gewährleisten Konsistenz in der Port-Zuweisung.

2. AgentAlice (`agent_Alice.py`)

Hauptfunktionen:

Wählt beim Start zufällig eine geheime Zahl von 1-100
Implementiert die NumberGuessExecutor-Klasse zur Behandlung der Vermutungsbewertung
Verarbeitet Nachrichten über das AgentExecutor-Interface des A2A SDK

Hauptmethoden:

execute(): Verarbeitet neu empfangene Nachrichten, ruft process_guess() zur Bewertung von Vermutungen auf
cancel(): Lehnt spezifizierte Tasks ab

Antworttypen:

"Go higher" - Vermutung ist niedriger als die geheime Zahl
"Go lower" - Vermutung ist höher als die geheime Zahl
"correct! attempts: <n>" - Vermutung ist korrekt, zeigt Anzahl der Versuche

3. AgentBob (`agent_Bob.py`)

Hauptfunktionen:

Fungiert als CLI-Frontend, verbindet Spieler mit anderen Agents
Verwaltet Spielstatus und Historienaufzeichnungen
Interagiert mit Carol zum Sortieren von Historienaufzeichnungen

Hauptmethoden:

_handle_guess(): Leitet Vermutungen an Alice weiter und gibt Feedback zurück
_negotiate_sorted_history(): Verhandelt mit Carol, bis die Historie sortiert ist
_visualise_history(): Fordert formatierte Historienvisualisierung an und druckt sie
play_game(): Führt interaktive CLI-Schleife aus

Verhandlungslogik:

Sendet anfängliche Misch-Anfrage an Carol
Überprüft, ob die zurückgegebene Liste sortiert ist
Sendet "Try again", wenn nicht sortiert, um Verhandlung fortzusetzen
Sendet "Well done!", wenn sortiert, um Verhandlung abzuschließen

4. AgentCarol (`agent_Carol.py`)

Hauptfunktionen:

Visualisiert Vermutungshistorienaufzeichnungen
Mischt Historienaufzeichnungslisten zufällig
Unterstützt Multi-Turn-Dialoge und Task-Kontext

Hauptmethoden:

_handle_initial(): Behandelt anfängliche Nachrichten in neuen Gesprächen
_handle_followup(): Behandelt Follow-up-Nachrichten, die auf bestehende Tasks verweisen
execute(): Dispatcht an entsprechende Handler basierend auf Nachrichtentyp

Skill-Definitionen:

history_visualiser: Generiert formatierte Vermutungshistorien-Zusammenfassung
history_shuffler: Mischt Reihenfolge der Historienaufzeichnungseinträge zufällig

5. Utility-Module (`utils/`)

`game_logic.py`

Hauptfunktionen:

process_guess(): Bewertet einzelne Vermutungen und gibt Feedback zurück
build_visualisation(): Erstellt menschenlesbare Historienaufzeichnungsdarstellung
is_sorted_history(): Überprüft, ob Historie nach Vermutungswerten sortiert ist
process_history_payload(): Verarbeitet historienbezogene Anfragen

`protocol_wrappers.py`

Hauptfunktionen:

send_text(): Sendet Textnachrichten synchron an Ziel-Agents
send_followup(): Sendet Follow-up-Nachrichten, behält Gesprächskontext bei
cancel_task(): Bricht Tasks auf entfernten Agents ab
extract_text(): Extrahiert Klartext aus Task- oder Message-Objekten

`server.py`

Hauptfunktionen:

run_agent_blocking(): Startet blockierenden Agent-Server
Verwendet Starlette + Uvicorn als HTTP-Server

System-Architektur-Flussdiagramm

graph TD
    A[Player] --> B[AgentBob CLI]
    B --> C[AgentAlice Evaluator]
    B --> D[AgentCarol Visualizer]
    
    C --> E[Secret Number 1-100]
    C --> F[Evaluate Guess]
    F --> G{Guess Result}
    G -->|Too Low| H[Return Go higher]
    G -->|Too High| I[Return Go lower]
    G -->|Correct| J[Return correct! attempts: N]
    
    B --> K[Game History]
    K --> L[Send to Carol for Visualization]
    L --> M[Generate Formatted Table]
    M --> N[Display to Player]
    
    B --> O[Negotiate Sorting]
    O --> P[Send Shuffle Request]
    P --> Q[Carol Random Shuffle]
    Q --> R{Check if Sorted}
    R -->|Not Sorted| S[Send Try again]
    R -->|Sorted| T[Send Well done!]
    S --> Q
    T --> U[Update History]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e8f5e8
    style D fill:#fff3e0
    style E fill:#ffebee
    style F fill:#e8f5e8
    style K fill:#f3e5f5
    style O fill:#f3e5f5

Nachrichtenfluss-Diagramm

sequenceDiagram
    participant Player as Player
    participant Bob as AgentBob
    participant Alice as AgentAlice
    participant Carol as AgentCarol
    
    Note over Player,Carol: Game Start
    Player->>Bob: Input guess number
    Bob->>Alice: Send guess
    Alice->>Bob: Return evaluation result
    Bob->>Player: Display hint
    
    Note over Player,Carol: Record History
    Bob->>Bob: Add to game history
    
    Note over Player,Carol: Visualize History
    Bob->>Carol: Send history records
    Carol->>Bob: Return formatted table
    Bob->>Player: Display history visualization
    
    Note over Player,Carol: Negotiate Sorting
    Bob->>Carol: Send shuffle request
    Carol->>Bob: Return shuffled list
    Bob->>Bob: Check if sorted
    
    alt Not Sorted
        Bob->>Carol: Send "Try again"
        Carol->>Bob: Shuffle list again
        Bob->>Bob: Recheck sorting
    else Sorted
        Bob->>Carol: Send "Well done!"
        Carol->>Bob: Complete task
        Bob->>Bob: Update history
    end
    
    Note over Player,Carol: Continue Game or End
    alt Guess Correct
        Bob->>Player: Display victory message
    else Guess Incorrect
        Player->>Bob: Continue inputting guesses
    end

Projekt mit uv ausführen

1. Umgebungseinrichtung

Stellen Sie sicher, dass uv installiert ist:

# uv installieren (falls noch nicht installiert)
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Projekteinrichtung

# Projekt klonen
git clone https://github.com/a2aproject/a2a-samples.git
cd a2a-samples/samples/python/agents/number_guessing_game

# Virtuelle Umgebung mit uv erstellen und Abhängigkeiten installieren
uv venv
source .venv/bin/activate  # Linux/macOS
# oder .venv\Scripts\activate  # Windows

# Abhängigkeiten installieren
uv pip install -r requirements.txt

3. Spiel ausführen

Öffnen Sie drei Terminal-Fenster und aktivieren Sie die virtuelle Umgebung in jedem:

# Terminal 1 - Alice (Evaluator) starten
uv run python agent_Alice.py

# Terminal 2 - Carol (Visualizer) starten
uv run python agent_Carol.py

# Terminal 3 - Bob (CLI Frontend) starten
uv run python agent_Bob.py

4. Gameplay

In Bobs Terminal fordert das Spiel Sie auf, Zahlen zwischen 1-100 einzugeben. Raten Sie weiter basierend auf Alices Feedback, bis Sie die richtige Vermutung treffen.

Gameplay-Beispiel:

Guess the number AgentAlice chose (1-100)!
Your guess: 50
Alice says: Go higher

=== Carol's visualisation (sorted) ===
Guesses so far:
  1.  50 -> Go higher
============================

Your guess: 75
Alice says: Go lower

=== Carol's visualisation (sorted) ===
Guesses so far:
  1.  50 -> Go higher
  2.  75 -> Go lower
============================

Your guess: 62
Alice says: correct! attempts: 3
You won! Exiting…

Projektzusammenfassung

Technische Eigenschaften

A2A Protocol Praxis:
- Demonstriert Kernkonzepte der Inter-Agent-Kommunikation
- Implementiert Nachrichtenversendung, Task-Management und Statusverfolgung
- Zeigt Multi-Turn-Dialog und Task-Kontext-Mechanismen
Modulares Design:
- Klare Trennung der Verantwortlichkeiten: Alice behandelt Bewertung, Bob Interaktion, Carol Visualisierung
- Wiederverwendbare Utility-Module für einfache Erweiterung und Wartung
Fehlerbehandlung:
- Eingabevalidierung und Fehleraufforderungen
- Netzwerkkommunikations-Ausnahmebehandlung
- Task-Abbruch und Timeout-Mechanismen

Lernwert

A2A Einführung: Bietet einfaches, verständliches Beispiel zum Verstehen des A2A Protocols
Agent-Kollaboration: Zeigt, wie mehrere Agents zusammenarbeiten, um komplexe Aufgaben zu erfüllen
Asynchrone Programmierung: Demonstriert asynchrone Nachrichtenverarbeitung und Statusmanagement
Protocol-Design: Zeigt, wie klare Agent-Interfaces und Skill-Definitionen entworfen werden

Erweiterungsmöglichkeiten

Mehr Agents hinzufügen: Neue Agent-Rollen wie statistische Analysten, Strategieberater usw. einführen
Spiellogik erweitern: Komplexere Spielregeln wie Zeitlimits, Bewertungssysteme usw. hinzufügen
Netzwerk-Deployment: Agents auf verschiedenen Maschinen bereitstellen, verteilte Agent-Systeme demonstrieren
LLM-Integration: AI-Agents hinzufügen, die intelligente Hinweise und Strategievorschläge bieten

Sicherheitsüberlegungen

Wie in der Projektdokumentation erwähnt, sollten in Produktionsumgebungen:

Externe Agents als nicht vertrauenswürdige Entitäten behandelt werden
Alle empfangenen Daten Validierung und Bereinigung erfordern
Angemessene Sicherheitsmaßnahmen wie Eingabevalidierung und Anmeldedatenschutz implementiert werden

Dieses Beispiel bietet Entwicklern eine sichere, kontrollierte Umgebung zum Lernen und Experimentieren mit dem A2A Protocol, während es grundlegende Muster für den Aufbau verteilter Agent-Systeme demonstriert.

A2A Multi-Agent Beispiel: Zahlenratespiel

Projektübersicht

Agent-Rollenbeschreibung

Detaillierte Code-Datei-Analyse

1. Konfigurationsdatei (`config.py`)

2. AgentAlice (`agent_Alice.py`)

3. AgentBob (`agent_Bob.py`)

4. AgentCarol (`agent_Carol.py`)

5. Utility-Module (`utils/`)

`game_logic.py`

`protocol_wrappers.py`

`server.py`

System-Architektur-Flussdiagramm

Nachrichtenfluss-Diagramm

Projekt mit uv ausführen

1. Umgebungseinrichtung

2. Projekteinrichtung

3. Spiel ausführen

4. Gameplay

Projektzusammenfassung

Technische Eigenschaften

Lernwert

Erweiterungsmöglichkeiten

Sicherheitsüberlegungen

Verwandte Fallstudien

🚀 Einsteiger-Beispiele

🐍 Python-Implementierungsfälle

🟨 JavaScript/TypeScript-Fälle

☕ Java-Implementierungsfälle

🔧 Framework-Integrationsfälle

🛠️ Entwicklungstools

📚 Protocol-Verständnis und Best Practices

🌟 Ökosystem-Ressourcen

A2A Multi-Agent Beispiel: Zahlenratespiel

Projektübersicht

Agent-Rollenbeschreibung

Detaillierte Code-Datei-Analyse

1. Konfigurationsdatei (config.py)

2. AgentAlice (agent_Alice.py)

3. AgentBob (agent_Bob.py)

4. AgentCarol (agent_Carol.py)

5. Utility-Module (utils/)

game_logic.py

protocol_wrappers.py

server.py

System-Architektur-Flussdiagramm

Nachrichtenfluss-Diagramm

Projekt mit uv ausführen

1. Umgebungseinrichtung

2. Projekteinrichtung

3. Spiel ausführen

4. Gameplay

Projektzusammenfassung

Technische Eigenschaften

Lernwert

Erweiterungsmöglichkeiten

Sicherheitsüberlegungen

Verwandte Fallstudien

🚀 Einsteiger-Beispiele

🐍 Python-Implementierungsfälle

🟨 JavaScript/TypeScript-Fälle

☕ Java-Implementierungsfälle

🔧 Framework-Integrationsfälle

🛠️ Entwicklungstools

📚 Protocol-Verständnis und Best Practices

🌟 Ökosystem-Ressourcen

1. Konfigurationsdatei (`config.py`)

2. AgentAlice (`agent_Alice.py`)

3. AgentBob (`agent_Bob.py`)

4. AgentCarol (`agent_Carol.py`)

5. Utility-Module (`utils/`)

`game_logic.py`

`protocol_wrappers.py`

`server.py`