A2A Protocol

Exemple Multi-Agent A2A : Jeu de Devinette de Nombres

deutschEnglishfrançaisहिंदी日本語한국어中文
MILO•
Share
A2A Multi-Agent Example: Number Guessing Game

Aperçu du Projet

Ceci est un exemple de jeu de devinette de nombres basé sur le protocole Agent2Agent (A2A), qui montre comment trois agents A2A légers collaborent pour compléter un jeu de devinette de nombres classique. Ce projet sert d'exemple d'introduction pratique pour le protocole A2A et le SDK Python avec les caractéristiques suivantes :

  • Aucune dépendance LLM : Ne nécessite pas de clés API ou de grands modèles de langage
  • Exécution locale : Les trois agents fonctionnent localement sans serveurs distants
  • Configuration simple : Dépendances externes minimales
  • Démonstration des concepts fondamentaux : Présente la fonctionnalité principale du protocole A2A

Description des Rôles des Agents

Agent Rôle Tâches
AgentAlice Évaluateur Choisit un nombre secret de 1-100, évalue les suppositions et fournit des indices
AgentBob Frontend CLI Relaie les suppositions du joueur, affiche les indices d'Alice, interagit avec Carol
AgentCarol Visualiseur Génère une visualisation textuelle de l'historique des suppositions, mélange l'historique aléatoirement sur demande

Analyse Détaillée des Fichiers de Code

1. Fichier de Configuration (config.py)

AGENT_ALICE_PORT = 8001
AGENT_BOB_PORT = 8002
AGENT_CAROL_PORT = 8003

Objectif : Gère les configurations de port de manière centralisée pour éviter les conflits de port. Tous les agents importent les configurations de ce module, assurant la cohérence dans l'allocation des ports.

2. AgentAlice (agent_Alice.py)

Fonctions principales :

  • Choisit aléatoirement un nombre secret de 1-100 au démarrage
  • Implémente la classe NumberGuessExecutor pour gérer l'évaluation des suppositions
  • Traite les messages via l'interface AgentExecutor du SDK A2A

Méthodes principales :

  • execute() : Traite les nouveaux messages reçus, appelle process_guess() pour évaluer les suppositions
  • cancel() : Rejette les tâches spécifiées

Types de réponse :

  • "Go higher" - La supposition est inférieure au nombre secret
  • "Go lower" - La supposition est supérieure au nombre secret
  • "correct! attempts: <n>" - La supposition est correcte, affiche le nombre de tentatives

3. AgentBob (agent_Bob.py)

Fonctions principales :

  • Agit comme frontend CLI, connectant les joueurs aux autres agents
  • Gère l'état du jeu et les enregistrements d'historique
  • Interagit avec Carol pour trier les enregistrements d'historique

Méthodes principales :

  • _handle_guess() : Transmet les suppositions à Alice et retourne les commentaires
  • _negotiate_sorted_history() : Négocie avec Carol jusqu'à ce que l'historique soit trié
  • _visualise_history() : Demande une visualisation d'historique formatée et l'imprime
  • play_game() : Exécute la boucle CLI interactive

Logique de négociation :

  • Envoie une demande de mélange initial à Carol
  • Vérifie si la liste retournée est triée
  • Envoie "Try again" si non triée pour continuer la négociation
  • Envoie "Well done!" si triée pour terminer la négociation

4. AgentCarol (agent_Carol.py)

Fonctions principales :

  • Visualise les enregistrements d'historique des suppositions
  • Mélange aléatoirement les listes d'enregistrements d'historique
  • Prend en charge les dialogues multi-tours et le contexte des tâches

Méthodes principales :

  • _handle_initial() : Gère les messages initiaux dans de nouvelles conversations
  • _handle_followup() : Gère les messages de suivi référençant des tâches existantes
  • execute() : Dispatche vers le gestionnaire approprié basé sur le type de message

Définitions de compétences :

  • history_visualiser : Génère un résumé d'historique de suppositions formaté
  • history_shuffler : Mélange aléatoirement l'ordre des entrées d'enregistrement d'historique

5. Modules Utilitaires (utils/)

game_logic.py

Fonctions principales :

  • process_guess() : Évalue les suppositions individuelles et retourne les commentaires
  • build_visualisation() : Crée un rendu d'enregistrement d'historique lisible par l'homme
  • is_sorted_history() : Vérifie si l'historique est trié par valeurs de supposition
  • process_history_payload() : Traite les demandes liées à l'historique

protocol_wrappers.py

Fonctions principales :

  • send_text() : Envoie des messages texte de manière synchrone aux agents cibles
  • send_followup() : Envoie des messages de suivi, maintient le contexte de conversation
  • cancel_task() : Annule les tâches sur les agents distants
  • extract_text() : Extrait le texte brut des objets Task ou Message

server.py

Fonctions principales :

  • run_agent_blocking() : Démarre le serveur d'agent bloquant
  • Utilise Starlette + Uvicorn comme serveur HTTP

Diagramme de Flux d'Architecture Système

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

Diagramme de Flux de Messages

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

Exécuter le Projet avec uv

1. Configuration de l'Environnement

Assurez-vous qu'uv est installé :

# Installer uv (si pas déjà installé)
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Configuration du Projet

# Cloner le projet
git clone https://github.com/a2aproject/a2a-samples.git
cd a2a-samples/samples/python/agents/number_guessing_game

# Créer un environnement virtuel avec uv et installer les dépendances
uv venv
source .venv/bin/activate  # Linux/macOS
# ou .venv\Scripts\activate  # Windows

# Installer les dépendances
uv pip install -r requirements.txt

3. Exécuter le Jeu

Ouvrez trois fenêtres de terminal et activez l'environnement virtuel dans chacune :

# Terminal 1 - Démarrer Alice (Évaluateur)
uv run python agent_Alice.py

# Terminal 2 - Démarrer Carol (Visualiseur)
uv run python agent_Carol.py

# Terminal 3 - Démarrer Bob (Frontend CLI)
uv run python agent_Bob.py

4. Gameplay

Dans le terminal de Bob, le jeu vous invitera à entrer des nombres entre 1-100. Continuez à deviner basé sur les commentaires d'Alice jusqu'à ce que vous trouviez la bonne supposition.

Exemple de Gameplay :

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…

Résumé du Projet

Caractéristiques Techniques

  1. Pratique du Protocole A2A :

    • Démontre les concepts fondamentaux de la communication inter-agents
    • Implémente l'envoi de messages, la gestion des tâches et le suivi d'état
    • Montre les mécanismes de dialogue multi-tours et de contexte de tâche

  2. Design Modulaire :

    • Séparation claire des responsabilités : Alice gère l'évaluation, Bob l'interaction, Carol la visualisation
    • Modules utilitaires réutilisables pour une extension et maintenance faciles

  3. Gestion d'Erreurs :

    • Validation d'entrée et invites d'erreur
    • Gestion d'exceptions de communication réseau
    • Mécanismes d'annulation de tâche et de timeout

Valeur Éducative

  1. Introduction A2A : Fournit un exemple simple et compréhensible pour comprendre le protocole A2A
  2. Collaboration d'Agents : Montre comment plusieurs agents collaborent pour accomplir des tâches complexes
  3. Programmation Asynchrone : Démontre le traitement de messages asynchrone et la gestion d'état
  4. Design de Protocole : Montre comment concevoir des interfaces d'agent claires et des définitions de compétences

Possibilités d'Extension

  1. Ajouter Plus d'Agents : Introduire de nouveaux rôles d'agent comme analystes statistiques, conseillers stratégiques, etc.
  2. Étendre la Logique de Jeu : Ajouter des règles de jeu plus complexes comme limites de temps, systèmes de score, etc.
  3. Déploiement Réseau : Déployer des agents sur différentes machines, démontrer des systèmes d'agents distribués
  4. Intégration LLM : Ajouter des agents AI qui fournissent des indices intelligents et des suggestions stratégiques

Considérations de Sécurité

Comme mentionné dans la documentation du projet, dans les environnements de production :

  • Les agents externes doivent être traités comme des entités non fiables
  • Toutes les données reçues nécessitent validation et assainissement
  • Implémenter des mesures de sécurité appropriées comme la validation d'entrée et la protection des identifiants

Cet exemple fournit aux développeurs un environnement sûr et contrôlé pour apprendre et expérimenter avec le protocole A2A tout en démontrant des modèles fondamentaux pour construire des systèmes d'agents distribués.

Études de Cas Connexes

🚀 Exemples pour Débutants

  • A2A Samples: Hello World Agent

    • Guide complet pour créer un agent Hello World avec le SDK Python A2A
    • Inclut la configuration d'environnement détaillée et les instructions de test

  • A2A SDK Currency Agent Tutorial

    • Guide étape par étape pour créer un agent de conversion de devises
    • Intègre les services AI OpenRouter

🐍 Cas d'Implémentation Python

🟨 Cas JavaScript/TypeScript

☕ Cas d'Implémentation Java

  • A2A Java Example
    • Architecture multi-module Maven
    • Implémentation SDK serveur Spring Boot
    • Exemple de service de traduction AI

🔧 Cas d'Intégration de Framework

🛠️ Outils de Développement

📚 Compréhension du Protocole et Meilleures Pratiques

🌟 Ressources d'Écosystème

  • Répertoire Awesome A2A

    • Exploration de l'écosystème complet du protocole Google A2A
    • Inclut la documentation officielle, les implémentations communautaires, les projets d'exemple et les guides d'intégration

  • Collection d'Implémentations A2A

    • Exploration de diverses implémentations open-source du protocole A2A
    • Inclut Java, TypeScript, Go, Rust, Python et plus

À travers ces études de cas, vous pouvez obtenir des aperçus plus profonds des applications du protocole A2A dans divers scénarios, des exemples simples Hello World aux systèmes multi-agents complexes, fournissant de riches ressources de référence pour votre parcours de développement A2A.