Échantillons A2A : Agent Hello World

Aperçu du Projet

Ceci est un exemple simple d'agent Hello World basé sur le SDK A2A (Agent2Agent). Le projet démontre comment créer un serveur d'agent intelligent de base qui peut répondre aux messages des utilisateurs et retourner des salutations simples.

Exigences de Version des Dépendances

Exigences de Version Python

• Python >= 3.10

Dépendances Principales

Structure du Projet

helloworld/
├── __init__.py              # Fichier d'initialisation du paquet
├── __main__.py              # Point d'entrée du programme principal
├── agent_executor.py        # Implémentation de l'exécuteur d'agent
├── test_client.py           # Client de test
├── pyproject.toml           # Configuration du projet et dépendances
├── uv.lock                  # Fichier de verrouillage des dépendances
└── README.md                # Documentation du projet

Configuration de l'Environnement

1. Installer le Gestionnaire de Paquets UV

Si vous n'avez pas encore installé UV, veuillez l'installer d'abord :

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Ou utiliser pip
pip install uv

2. Cloner le Projet

git clone https://github.com/google-a2a/a2a-samples.git
cd a2a-samples/samples/python/agents/helloworld

3. Installer les Dépendances

UV installera automatiquement toutes les dépendances basées sur les fichiers pyproject.toml et uv.lock :

uv sync

Architecture du Code

Composants Principaux

1. HelloWorldAgent (agent_executor.py)

class HelloWorldAgent:
    """Agent Hello World."""
    
    async def invoke(self) -> str:
        return 'Hello World'

2. HelloWorldAgentExecutor (agent_executor.py)

class HelloWorldAgentExecutor(AgentExecutor):
    """Implémentation de l'exécuteur d'agent"""
    
    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
        result = await self.agent.invoke()
        event_queue.enqueue_event(new_agent_text_message(result))

3. Configuration du Serveur (__main__.py)

• Définir les compétences d'agent (AgentSkill)
• Configurer les cartes d'agent publiques et étendues (AgentCard)
• Configurer les gestionnaires de requêtes et le stockage des tâches
• Démarrer le serveur Uvicorn

Étapes d'Exécution

1. Démarrer le Serveur d'Agent

uv run .

Le serveur démarrera à http://localhost:9999.

2. Exécuter le Client de Test

Dans une autre fenêtre de terminal :

uv run test_client.py

3. Vérifier le Service

Vous pouvez vérifier que le service fonctionne correctement par les méthodes suivantes :

Accéder aux Informations de la Carte d'Agent

curl http://localhost:9999/.well-known/agent.json

Accéder à la Carte d'Agent Étendue (nécessite une authentification)

curl -H "Authorization: Bearer dummy-token-for-extended-card" \
     http://localhost:9999/agent/authenticatedExtendedCard

Diagramme de Flux du Projet

Flux d'Interaction Client-Serveur A2A

sequenceDiagram
    participant Client as Client A2A
    participant Server as Serveur A2A
    participant Agent as HelloWorldAgent
    participant Queue as EventQueue
    
    Note over Client,Server: 1. Phase de Découverte de Service
    Client->>Server: GET /.well-known/agent.json
    Server-->>Client: Retourner la carte d'agent publique
    
    Note over Client,Server: 2. Récupération de Carte Étendue (Optionnel)
    Client->>Server: GET /agent/authenticatedExtendedCard<br/>(avec token Bearer)
    Server-->>Client: Retourner la carte d'agent étendue
    
    Note over Client,Server: 3. Flux d'Envoi de Message
    Client->>Server: POST /agent/message<br/>{"message": {"role": "user", "parts": [...]}}
    
    Note over Server,Queue: 4. Traitement Interne du Serveur
    Server->>Agent: Appeler HelloWorldAgentExecutor.execute()
    Agent->>Agent: Exécuter HelloWorldAgent.invoke()
    Agent-->>Queue: Générer le message "Hello World"
    Queue-->>Server: Retourner le résultat de la file d'événements
    
    Note over Client,Server: 5. Retour de Réponse
    Server-->>Client: Retourner la réponse du message
    
    Note over Client,Server: 6. Traitement de Message en Streaming (Optionnel)
    Client->>Server: POST /agent/message/stream
    Server-->>Client: Diffuser les fragments de message
    Server-->>Client: Fragment de message 1
    Server-->>Client: Fragment de message 2
    Server-->>Client: Marqueur de fin

Diagramme de Flux d'Architecture Système

graph TB
    subgraph "Environnement Client"
        C1[Démarrage du Client de Test]
        C2[A2ACardResolver<br/>Analyser la Carte d'Agent]
        C3[A2AClient<br/>Initialisation]
        C4[Envoyer une Requête de Message]
        C5[Traiter la Réponse]
    end
    
    subgraph "Communication Réseau"
        N1[Requête HTTP/HTTPS]
        N2[Transfert de Données JSON]
    end
    
    subgraph "Environnement Serveur"
        S1[A2AStarletteApplication<br/>Serveur Web]
        S2[DefaultRequestHandler<br/>Gestionnaire de Requêtes]
        S3[HelloWorldAgentExecutor<br/>Exécuteur d'Agent]
        S4[HelloWorldAgent<br/>Logique d'Agent Principal]
        S5[InMemoryTaskStore<br/>Stockage de Tâches]
        S6[EventQueue<br/>File d'Événements]
    end
    
    subgraph "Configuration d'Agent"
        A1[Carte d'Agent Publique<br/>Compétences de Base]
        A2[Carte d'Agent Étendue<br/>Compétences Améliorées]
    end
    
    %% Flux client
    C1 --> C2
    C2 --> C3
    C3 --> C4
    C4 --> C5
    
    %% Communication réseau
    C4 --> N1
    N1 --> N2
    N2 --> S1
    S1 --> N2
    N2 --> C5
    
    %% Flux serveur
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S6
    S6 --> S3
    S3 --> S2
    S2 --> S1
    
    %% Associations de configuration
    A1 --> S1
    A2 --> S1
    S2 --> S5
    
    %% Style
    style C3 fill:#e3f2fd
    style S1 fill:#f3e5f5
    style S4 fill:#e8f5e8
    style N2 fill:#fff3e0

Points de Terminaison API

Points de Terminaison Publics

Points de Terminaison Authentifiés

Configuration des Compétences

Compétences de Base

• ID : hello_world
• Nom : Retourne hello world
• Description : retourne simplement hello world
• Exemples : ['hi', 'hello world']

Compétences Étendues (nécessite une authentification)

• ID : super_hello_world
• Nom : Retourne un SUPER Hello World
• Description : Une salutation plus enthousiaste, uniquement pour les utilisateurs authentifiés
• Exemples : ['super hi', 'give me a super hello']

Dépannage

Problèmes Courants

1. Port Déjà Utilisé

   # Vérifier l'utilisation du port
   lsof -i :9999
   # Tuer le processus
   kill -9 <PID>
   

2. Échec de l'Installation des Dépendances

   # Nettoyer le cache et réinstaller
   uv cache clean
   uv sync --reinstall
   

3. Version Python Incompatible

   # Vérifier la version Python
   python --version
   # S'assurer que la version >= 3.10
   

Développement d'Extensions

Ajouter de Nouvelles Compétences

1. Définir une nouvelle AgentSkill dans __main__.py
2. Modifier la gestion de la logique dans agent_executor.py
3. Mettre à jour la configuration de la carte d'agent

Intégrer des APIs Externes

1. Ajouter de nouvelles dépendances dans pyproject.toml
2. Implémenter les appels API dans agent_executor.py
3. Gérer les réponses asynchrones et les erreurs

Résumé

Cet exemple Hello World démontre l'utilisation de base du SDK A2A, incluant :

• Création et configuration de serveurs d'agents
• Définition et gestion des compétences
• Communication client-serveur
• Authentification et fonctionnalité étendue

Grâce à cet exemple, vous pouvez rapidement comprendre comment construire vos propres applications d'agents intelligents.