Présentation du Projet

Ce projet constitue un exemple de jeu de devinette basé sur le protocole Agent2Agent (A2A), démontrant la collaboration entre trois agents A2A légers pour accomplir un jeu classique de devinette de nombres. Ce projet sert d'introduction pratique au protocole A2A et au SDK Python, avec les caractéristiques suivantes :

• Sans dépendance LLM : aucune clé API ou modèle de langage volumineux requis
• Exécution locale : les trois agents fonctionnent en local, sans serveur distant
• Installation simplifiée : dépendances externes minimales
• Démonstration des concepts fondamentaux : illustre les fonctionnalités essentielles du protocole A2A

Description des Rôles des Agents

Agent	Rôle	Fonctionnalités
AgentAlice	Évaluateur	Choisit un nombre secret entre 1-100, évalue les propositions et fournit des indices
AgentBob	Interface CLI	Relaye les propositions du joueur, affiche les indices d'Alice, négocie avec Carol
AgentCarol	Visualiseur	Génère une visualisation textuelle de l'historique des tentatives, peut mélanger l'historique sur demande

Analyse Approfondie des Fichiers

1. Fichier de Configuration (config.py)

AGENT_ALICE_PORT = 8001
AGENT_BOB_PORT = 8002
AGENT_CAROL_PORT = 8003

Objectif : Centraliser la gestion des ports pour éviter les conflits. Tous les agents importent leur configuration depuis ce module, garantissant une cohérence dans l'allocation des ports.

2. AgentAlice (agent_Alice.py)

Fonctionnalités principales :

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

Méthodes clés :

• execute() : Traite les nouveaux messages reçus, appelle process_guess() pour évaluer la proposition
• cancel() : Rejette une tâche spécifique

Types de réponses :

• "Go higher" - la proposition est inférieure au nombre secret
• "Go lower" - la proposition est supérieure au nombre secret
• "correct! attempts: <n>" - proposition correcte, affiche le nombre d'essais

3. AgentBob (agent_Bob.py)

Fonctionnalités principales :

• Sert d'interface CLI, reliant le joueur aux autres agents
• Gère l'état du jeu et l'historique des tentatives
• Négocie avec Carol pour trier l'historique

Méthodes clés :

• _handle_guess() : Transmet la proposition à Alice et retourne le feedback
• _negotiate_sorted_history() : Négocie avec Carol jusqu'à ce que l'historique soit trié
• _visualise_history() : Demande et affiche la visualisation formatée de l'historique
• play_game() : Exécute la boucle interactive CLI

Logique de négociation :

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

4. AgentCarol (agent_Carol.py)

Fonctionnalités principales :

• Visualise l'historique des propositions
• Mélange aléatoirement l'ordre des entrées de l'historique
• Supporte les conversations multi-tours et les références de tâches

Méthodes clés :

• _handle_initial() : Gère le message initial d'une nouvelle conversation
• _handle_followup() : Gère les messages de suivi référençant une tâche existante
• execute() : Distribue vers le processeur approprié selon le type de message

Définition des compétences :

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

5. Modules Utilitaires (utils/)

game_logic.py

Fonctionnalités principales :

• process_guess() : Évalue une proposition individuelle et retourne le feedback
• build_visualisation() : Crée une rendu lisible de l'historique
• is_sorted_history() : Vérifie si l'historique est trié par ordre de propositions
• process_history_payload() : Traite les requêtes liées à l'historique

protocol_wrappers.py

Fonctionnalités principales :

• send_text() : Envoie synchrone d'un message texte vers l'agent cible
• send_followup() : Envoie un message de suivi, conservant le contexte de conversation
• cancel_task() : Annule une tâche sur un agent distant
• extract_text() : Extrait le texte brut d'une Task ou Message

server.py

Fonctionnalités principales :

• run_agent_blocking() : Lance un serveur agent en mode bloquant
• Utilise Starlette + Uvicorn comme serveur HTTP

Diagramme d'Architecture du Système

graph TD A[Joueur] --> B[AgentBob CLI] B --> C[AgentAlice Évaluateur] B --> D[AgentCarol Visualiseur] C --> E[Nombre secret 1-100] C --> F[Évaluer la proposition] F --> G{Résultat} G -->|Trop bas| H[Retour Go higher] G -->|Trop haut| I[Retour Go lower] G -->|Correct| J[Retour correct! attempts: N] B --> K[Historique du jeu] K --> L[Envoyer à Carol pour visualisation] L --> M[Générer tableau formaté] M --> N[Afficher au joueur] B --> O[Négociation de tri] O --> P[Envoyer demande de mélange] P --> Q[Carol mélange aléatoirement] Q --> R{Vérifier tri} R -->|Non trié| S[Envoyer Try again] R -->|Trié| T[Envoyer Well done!] S --> Q T --> U[Mettre à jour l'historique] 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 des Messages

sequenceDiagram participant Player as Joueur participant Bob as AgentBob participant Alice as AgentAlice participant Carol as AgentCarol Note over Player,Carol: Début du jeu Player->>Bob: Saisir le nombre deviné Bob->>Alice: Envoyer la proposition Alice->>Bob: Retourner le résultat de l'évaluation Bob->>Player: Afficher l'indice Note over Player,Carol: Enregistrer l'historique Bob->>Bob: Ajouter à l'historique du jeu Note over Player,Carol: Visualiser l'historique Bob->>Carol: Envoyer l'historique Carol->>Bob: Retourner le tableau formaté Bob->>Player: Afficher la visualisation Note over Player,Carol: Négocier le tri Bob->>Carol: Envoyer demande de mélange Carol->>Bob: Retourner la liste mélangée Bob->>Bob: Vérifier si trié alt Non trié Bob->>Carol: Envoyer "Try again" Carol->>Bob: Mélanger à nouveau Bob->>Bob: Revérifier le tri else Trié Bob->>Carol: Envoyer "Well done!" Carol->>Bob: Terminer la tâche Bob->>Bob: Mettre à jour l'historique end Note over Player,Carol: Continuer ou terminer alt Proposition correcte Bob->>Player: Afficher message de victoire else Proposition incorrecte Player->>Bob: Continuer à saisir end Exécution du Projet avec uv

1. Préparation de l'Environnement

Assurez-vous qu'uv est installé :

# Installer uv (si pas encore 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. Lancer 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 (Interface CLI)
uv run python agent_Bob.py

4. Comment Jouer

Dans le terminal de Bob, le jeu vous demandera de saisir un nombre entre 1-100. Continuez à deviner en vous basant sur les indices d'Alice jusqu'à trouver le nombre secret.

Exemple de partie :

Devinez le nombre choisi par AgentAlice (1-100) !
Votre proposition : 50
Alice répond : Go higher

=== Visualisation de Carol (triée) ===
Essais jusqu'à présent :
  1.  50 -> Go higher
============================

Votre proposition : 75
Alice répond : Go lower

=== Visualisation de Carol (triée) ===
Essais jusqu'à présent :
  1.  50 -> Go higher
  2.  75 -> Go lower
============================

Votre proposition : 62
Alice répond : correct! attempts: 3
Vous avez gagné ! Sortie…

Résumé du Projet

Caractéristiques Techniques

1. Pratique du protocole A2A :

• Démontre les concepts fondamentaux de communication inter-agents
• Implémente l'envoi de messages, la gestion des tâches et le suivi d'état
• Illustre les mécanismes de conversations multi-tours et de références de tâches

2. Conception modulaire :

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

3. Gestion des erreurs :

• Validation des entrées et messages d'erreur
• Traitement des exceptions de communication réseau
• Mécanismes d'annulation de tâches et de gestion des délais

Valeur Pédagogique

1. Introduction à A2A : Fournit un exemple simple et compréhensible pour appréhender le protocole A2A
2. Collaboration multi-agents : Montre comment plusieurs agents peuvent coopérer pour accomplir des tâches complexes
3. Programmation asynchrone : Démontre le traitement asynchrone des messages et la gestion d'état
4. Conception de protocole : Illustre comment définir des interfaces d'agents claires et des définitions de compétences

Possibilités d'Extension

1. Ajouter d'autres agents : Introduire de nouveaux rôles comme analyste statistiques, conseiller en stratégie, etc.
2. Enrichir la logique du jeu : Ajouter des règles plus complexes comme des limites de temps, un système de points, etc.
3. Déploiement réseau : Déployer les agents sur différentes machines pour démontrer un système d'agents distribués
4. Intégration LLM : Ajouter des agents IA，提供 des indices intelligents et des suggestions stratégiques

Considérations de Sécurité

Comme mentionné dans la documentation du projet, en environnement de production :

• Les agents externes doivent être considérés comme des entités non dignes de confiance
• Toutes les données reçues doivent être validées et assainies
• Des mesures de sécurité appropriées doivent être implémentées, comme la validation des entrées et la protection des identifiants

Cet exemple offre aux développeurs un environnement sécurisé et contrôlé pour apprendre et expérimenter le protocole A2A, tout en démontrant les motifs de base pour construire des systèmes d'agents distribués.

Articles Connexes

Exemples d'Introduction

• A2A Samples: Hello World Agent
• Guide complet pour construire un agent Hello World avec le SDK Python A2A
• Includes detailed environment setup and testing instructions
• A2A SDK Currency Agent Tutorial
• Guide pas à pas pour construire un agent de conversion de devises
• Intégration avec le service AI OpenRouter

Cas d'Implémentation Python

• A2A Python Example: GitHub Agent
• Création et connexion de agents GitHub avec a2a-python
• Implémentation de fonctionnalités de requête d'informations de dépôt
• A2A Example: Travel Planning Assistant
• Implémentation d'un agent de planification de voyages avec OpenRouter
• Construction avec Python a2a-sdk
• A2A SDK Python Practical Guide
• Tutoriel approfondi sur le développement avec le SDK Python A2A
• Contains workflow diagrams and practical code examples

Cas JavaScript/TypeScript

• A2A JS Example: Movie Agent
• Intégration avec TMDB API et OpenRouter AI
• Implémentation de serveur Express.js
• A2A JavaScript SDK Complete Tutorial
• Implémentation typesafe avec TypeScript
• SDK serveur Express.js et traitement en streaming

Cas d'Implémentation Java

• A2A Java Example
• Architecture multi-modules Maven
• Implémentation du SDK serveur Spring Boot
• Exemple de service de traduction IA

Cas d'Intégration de Frameworks

• Implementing A2A Agents with ADK: Complete Development Guide
• Implémentation d'un système d'agents A2A intelligents avec le framework Google ADK
• Couvre le流程 de développement complet
• A2A ADK Expense Reimbursement Agent
• Agent intelligent de报销 basé sur Google ADK et le protocole A2A
• Génération automatique de informations complémentaires pour les formulaires
• A2A CrewAI Analytics Chart Agent
• Construction d'un agent d'analyse de données avec le框架 CrewAI
• Intégration de fonctionnalités de génération de graphiques et visualisation

️ Outils de Développement

• A2A Inspector: Agent2Agent Communication Debugging Detailed
• Outil de débogage puissant basé sur le web
• Inspection en temps réel des cartes d'agents et communications JSON-RPC
• A2A .NET SDK Comprehensive Documentation
• Bibliothèque .NET implémentant Google A2A Protocol v0.2.1
• Pour les applications ASP.NET Core

Compréhension du Protocole et Bonnes Pratiques

• Understanding the A2A Protocol: Comprehensive Guide
• Guide complet pour comprendre le protocole A2A
• Concepts fondamentaux et avantages d'interopérabilité des agents IA
• A2A Protocol Specification (Python)
• Guide complet de la spécification en implémentation Python
• Couvre les cartes d'agents, la transmission de messages, la gestion des tâches et autres fonctionnalités essentielles
• 2025 Complete A2A Protocol Guide
• Introduction complète et guide pratique du protocole A2E
• Couverture complète des concepts de base aux applications avancées

Ressources de l'Écosystème

• Awesome A2A Directory
• Explorer l'écosystème complet du protocole Google A2A
• Contient la documentation officielle, implémentations communautaires, exemples de projets et guides d'intégration
• A2A Implementation Collection
• Explorer diverses implémentations open source du protocole A2A
• Inclut Java, TypeScript, Go, Rust, Python et autres

Through ces articles, vous pouvez approfondir votre compréhension des applications du protocole A2A dans différents scénarios, des exemples simples Hello World aux systèmes multi-agents complexes, offrant des ressources de référence riches pour votre parcours de développement A2A.