A2A Protocol

Implementing A2A Agents with ADK: Complete Development Guide

deutschEnglishfrançaisहिंदी日本語한국어中文
MILO•
Share
ADK
Implementing A2A Agents with ADK: Complete Development Guide

Table des matières

  1. Aperçu d'ADK et du protocole A2A
  2. Configuration de l'environnement et installation des dépendances
  3. Conception de la structure du projet
  4. Développement d'agents A2A côté serveur
  5. Développement d'agents A2A côté client
  6. Configuration et métadonnées des agents
  7. Démarrage et test du serveur A2A
  8. Test d'intégration de l'interface utilisateur web
  9. Explication détaillée du flux de communication A2A

Aperçu d'ADK et du protocole A2A

Qu'est-ce qu'ADK et A2A ?

ADK (Agent Development Kit) est un framework de développement d'agents intelligents développé par Google, tandis qu'A2A (Agent2Agent Protocol) est un protocole de communication inter-agents standardisé. Le framework ADK intègre un support complet pour les agents A2A, fournissant des composants clés comme RemoteA2aAgent, permettant aux développeurs de :

  • 🔗 Connexion transparente : Implémenter une communication standardisée entre agents distribués
  • 🚀 Développement rapide : Construire rapidement des systèmes d'agents complexes en utilisant des APIs simples
  • 🔄 Standardisation du protocole : Respecter les spécifications du protocole A2A pour assurer l'interopérabilité
  • 🎯 Routage intelligent : Gérer automatiquement le routage des messages et la conversion de format
  • 📊 Observabilité : Capacités de journalisation et de surveillance intégrées

Note importante : ADK est un framework de développement, A2A est un protocole de communication. ADK inclut l'implémentation du protocole A2A, permettant aux développeurs de créer facilement des systèmes d'agents intelligents prenant en charge la communication Agent2Agent. Ce guide montrera comment utiliser la fonctionnalité A2A dans le framework ADK.

Avantages clés de la fonctionnalité A2A dans ADK

  1. Architecture distribuée : Prend en charge le déploiement d'agents sur différents serveurs et environnements, communiquant via le protocole A2A
  2. Protocole standardisé : Respecte les spécifications du protocole de communication A2A, assurant la compatibilité inter-plateformes
  3. Prêt à l'emploi : ADK fournit des outils CLI complets et une interface utilisateur web avec support A2A intégré
  4. Haute extensibilité : Prend en charge les outils personnalisés et la logique métier complexe, compatible avec l'écosystème A2A
  5. Prêt pour la production : Garanties de sécurité et de fiabilité de niveau entreprise

Configuration de l'environnement et installation des dépendances

Exigences système

  • Python : 3.10 ou supérieur
  • Système d'exploitation : Linux, macOS, ou Windows
  • Clé API : Clé API Gemini (pour la fonctionnalité LLM)

Étape 1 : Création du répertoire de projet

# Créer le répertoire racine du projet
mkdir adk-a2a-demo
cd adk-a2a-demo

# Créer un environnement virtuel
python -m venv .venv

# Activer l'environnement virtuel
# Linux/macOS :
source .venv/bin/activate
# Windows :
# .venv\Scripts\activate

Étape 2 : Installation des dépendances ADK (avec support A2A)

# Installer le package ADK core (avec support du protocole A2A)
pip install google-adk[a2a]>=1.6.1

# Vérifier l'installation
adk --version

Étape 3 : Configuration des variables d'environnement

# Créer le fichier .env
echo "GOOGLE_API_KEY=your_gemini_api_key_here" > .env

# Définir la variable d'environnement (temporaire)
export GOOGLE_API_KEY="your_gemini_api_key_here"

Conception de la structure du projet

Structure de projet A2A recommandée basée sur ADK

adk-a2a-demo/
├── .env                    # Configuration des variables d'environnement
├── requirements.txt        # Dépendances Python
├── __init__.py            # Initialisation du projet principal
├── agent.py               # Agent client A2A (RemoteA2aAgent)
├── remote_a2a/            # Répertoire des agents A2A côté serveur
│   └── facts_agent/       # Implémentation d'agent spécifique
│       ├── __init__.py    # Initialisation du package d'agent
│       ├── agent.py       # Logique principale de l'agent
│       └── agent.json     # Configuration des métadonnées de l'agent A2A
└── README.md              # Documentation du projet

Création de la structure de projet de base

# Créer les répertoires et fichiers nécessaires
mkdir -p remote_a2a/facts_agent
touch __init__.py agent.py
touch remote_a2a/facts_agent/__init__.py
touch remote_a2a/facts_agent/agent.py
touch remote_a2a/facts_agent/agent.json
touch requirements.txt

Développement d'agents A2A côté serveur

Étape 1 : Création de l'implémentation de l'agent côté serveur

L'agent côté serveur est le composant principal qui exécute réellement la logique métier. Implémentation dans remote_a2a/facts_agent/agent.py :

# remote_a2a/facts_agent/agent.py

from google.adk import Agent
from google.adk.tools import google_search

# Définir l'agent côté serveur
root_agent = Agent(
    # Identifiant unique de l'agent
    name="facts_agent",
    
    # Modèle de langage large à utiliser
    model="gemini-2.0-flash",
    
    # Description des capacités de l'agent
    description="Un agent qui fournit des faits intéressants.",
    
    # Instructions de comportement de l'agent
    instruction=(
        "Vous êtes un agent utile qui peut fournir des faits intéressants. "
        "Utilisez la recherche Google pour trouver des informations précises et à jour. "
        "Fournissez toujours des sources pour vos faits."
    ),
    
    # Liste des outils disponibles
    tools=[google_search],
)

Étape 2 : Configuration de l'initialisation du package d'agent

Dans remote_a2a/facts_agent/__init__.py :

# remote_a2a/facts_agent/__init__.py

# Importer l'implémentation de l'agent pour qu'elle soit découverte par ADK
from . import agent

Étape 3 : Analyse des fonctionnalités principales de l'agent côté serveur

# Explication des composants principaux de l'agent

# 1. Nom (name)
# - Doit être unique, utilisé pour identifier l'agent dans le réseau A2A
# - Recommandé d'utiliser des noms descriptifs

# 2. Modèle (model)
# - Spécifie le modèle de langage large à utiliser
# - Prend en charge les modèles de la série Gemini

# 3. Description (description)
# - Brève description des capacités de l'agent
# - Affichée aux autres agents lors de la découverte d'agents

# 4. Instruction (instruction)
# - Guidance comportementale détaillée
# - Définit la personnalité et le style de réponse de l'agent

# 5. Outils (tools)
# - Outils externes que l'agent peut appeler
# - Comme la recherche, le calcul, les appels d'API, etc.

Développement d'agents A2A côté client

Étape 1 : Création de l'agent côté client

L'agent côté client utilise RemoteA2aAgent pour se connecter aux services distants. Implémentation dans agent.py :

# agent.py

from google.adk.agents.remote_a2a_agent import RemoteA2aAgent

# Définir l'agent client A2A distant
root_agent = RemoteA2aAgent(
    # Nom de l'agent client
    name="facts_agent",
    
    # Description des capacités
    description="Un agent qui fournit des faits intéressants.",
    
    # URL de la carte d'agent distant
    agent_card="http://localhost:8001/a2a/facts_agent/.well-known/agent.json",
)

Étape 2 : Configuration détaillée de RemoteA2aAgent

# Exemple de configuration avancée
root_agent = RemoteA2aAgent(
    name="facts_agent",
    description="Un agent qui fournit des faits intéressants.",
    agent_card="http://localhost:8001/a2a/facts_agent/.well-known/agent.json",
    
    # Configuration optionnelle
    timeout=300.0,          # Timeout HTTP (secondes)
    httpx_client=None,      # Client HTTP personnalisé
)

Étape 3 : Principe de fonctionnement de l'agent côté client

  1. Découverte d'agent : Obtenir les informations de l'agent distant via l'URL agent_card
  2. Établissement de connexion : Créer une connexion HTTP vers le serveur A2A distant
  3. Transformation de message : Convertir les événements locaux en messages du protocole A2A
  4. Invocation distante : Envoyer des requêtes à l'agent distant
  5. Traitement de réponse : Recevoir et convertir les réponses de l'agent distant

Configuration et métadonnées des agents

Étape 1 : Création du fichier de configuration de l'agent

Définir les métadonnées de l'agent dans remote_a2a/facts_agent/agent.json :

{
  "name": "facts_agent",
  "description": "Un agent qui fournit des faits intéressants.",
  "url": "http://localhost:8001/a2a/facts_agent",
  "version": "1.0.0",
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "capabilities": {
    "streaming": true,
    "functions": true
  },
  "skills": [
    {
      "id": "give_facts",
      "name": "Faits intéressants",
      "description": "Fournit des faits intéressants sur divers sujets en utilisant la recherche Google.",
      "tags": ["information", "faits", "connaissance", "recherche", "google"],
      "examples": [
        "Dites-moi un fait intéressant sur la ville de New York.",
        "Partagez quelque chose de fascinant sur la physique quantique.",
        "Quel est un fait inhabituel sur la vie marine ?"
      ]
    }
  ]
}

Étape 2 : Explication des champs de configuration

{
  // Informations de base
  "name": "Identifiant unique de l'agent",
  "description": "Brève description des capacités de l'agent",
  "url": "URL du point de terminaison du service A2A",
  "version": "Numéro de version (versioning sémantique)",
  
  // Modes d'entrée/sortie
  "defaultInputModes": ["Formats d'entrée pris en charge"],
  "defaultOutputModes": ["Formats de sortie pris en charge"],
  
  // Capacités de l'agent
  "capabilities": {
    "streaming": "Si la réponse en streaming est prise en charge",
    "functions": "Si les appels de fonction sont pris en charge"
  },
  
  // Définitions des compétences
  "skills": [
    {
      "id": "Identifiant unique de la compétence",
      "name": "Nom d'affichage de la compétence",
      "description": "Description détaillée de la compétence",
      "tags": ["tag1", "tag2"],
      "examples": ["Exemple d'utilisation 1", "Exemple d'utilisation 2"]
    }
  ]
}

Étape 3 : Création des fichiers de dépendances

Dans requirements.txt :

google-adk[a2a]>=1.6.1

Dans __init__.py :

# Fichier d'initialisation du projet
from . import agent

Démarrage et test du serveur A2A

Étape 1 : Démarrage du serveur A2A

# Assurez-vous d'être dans le répertoire racine du projet et que l'environnement virtuel est activé
source .venv/bin/activate

# Démarrer le serveur A2A
adk api_server --a2a --port 8001 remote_a2a

# Sortie attendue :
# INFO:     Uvicorn running on http://127.0.0.1:8001 (Press CTRL+C to quit)
# INFO:     A2A endpoints enabled for agents: facts_agent

Étape 2 : Vérification des points de terminaison A2A

# Tester le point de terminaison de découverte d'agent
curl http://localhost:8001/a2a/facts_agent/.well-known/agent.json

# Devrait retourner le JSON de configuration de l'agent

Étape 3 : Analyse de l'architecture du serveur A2A

Une fois le serveur A2A démarré, il crée les points de terminaison suivants :

  1. Point de terminaison de découverte d'agent : /.well-known/agent.json

    • Fournit les métadonnées et informations de capacité de l'agent
    • Utilisé pour la découverte automatique d'agents et la configuration

  2. Point de terminaison de traitement de messages : /a2a/{agent_name}

    • Reçoit les messages d'autres agents
    • Traite les requêtes du protocole A2A

  3. Point de terminaison de vérification de santé : /health

    • Surveillance de l'état du serveur
    • Vérification de santé du répartiteur de charge

Test d'intégration de l'interface utilisateur web

Étape 1 : Démarrage du serveur web ADK

Dans une nouvelle fenêtre de terminal :

# Activer l'environnement virtuel
source .venv/bin/activate

# Démarrer le serveur d'interface utilisateur web
adk web .

# Sortie attendue :
# INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
# INFO:     Available agents: facts_agent

Étape 2 : Processus de test de l'interface utilisateur web

  1. Accès à l'interface utilisateur web : Ouvrir http://localhost:8000 dans le navigateur

  2. Sélection d'agent : Choisir facts_agent dans le menu déroulant

  3. Test de conversation : Saisir un message de test, par exemple :

    "Dites-moi un fait intéressant sur l'intelligence artificielle"

  4. Observation de la réponse : Vérifier que l'agent répond correctement et utilise l'outil de recherche Google

Étape 3 : Exemples de cas de test

# Cas de test 1 : Question de fait de base
Entrée : Quel est un fait intéressant sur la Grande Muraille de Chine ?
Attendu : Retourner des faits intéressants sur la Grande Muraille avec des sources de recherche

# Cas de test 2 : Question de connaissance scientifique
Entrée : Partagez quelque chose de fascinant sur les trous noirs.
Attendu : Retourner des faits scientifiques sur les trous noirs

# Cas de test 3 : Question d'événement actuel
Entrée : Quelle est une découverte récente dans l'exploration spatiale ?
Attendu : Retourner les dernières découvertes de l'exploration spatiale

Explication détaillée du flux de communication A2A

Diagramme de séquence de communication A2A complet

sequenceDiagram
    participant User as Utilisateur
    participant WebUI as Interface Web ADK<br/>(localhost:8000)
    participant Client as Agent Client<br/>(RemoteA2aAgent)
    participant A2AServer as Serveur A2A<br/>(localhost:8001)
    participant Agent as Agent Serveur<br/>(facts_agent)
    participant LLM as Gemini LLM
    participant Search as Recherche Google

    User->>WebUI: 1. Saisie du message de question
    WebUI->>Client: 2. Appel de l'agent client
    
    Note over Client: 3. Vérification de l'initialisation de l'agent
    Client->>A2AServer: 4. GET /.well-known/agent.json
    A2AServer-->>Client: 5. Retour de la configuration de l'agent
    
    Note over Client: 6. Construction du message A2A
    Client->>A2AServer: 7. POST /a2a/facts_agent<br/>Envoi du message A2A
    
    A2AServer->>Agent: 8. Conversion en événement interne
    Agent->>LLM: 9. Envoi du prompt
    LLM-->>Agent: 10. Retour de la réponse (avec appel d'outil)
    
    Agent->>Search: 11. Exécution de la recherche Google
    Search-->>Agent: 12. Retour des résultats de recherche
    
    Agent->>LLM: 13. Intégration des résultats de recherche
    LLM-->>Agent: 14. Génération de la réponse finale
    
    Agent-->>A2AServer: 15. Retour du résultat de traitement
    A2AServer-->>Client: 16. Retour de la réponse A2A
    
    Note over Client: 17. Conversion en événement interne
    Client-->>WebUI: 18. Retour de la réponse
    WebUI-->>User: 19. Affichage du résultat final

Analyse des étapes de communication clés

1. Phase de découverte d'agent (Étapes 4-5)

GET http://localhost:8001/a2a/facts_agent/.well-known/agent.json

Réponse :
{
  "name": "facts_agent",
  "url": "http://localhost:8001/a2a/facts_agent",
  "skills": [...]
}

2. Phase d'envoi de message (Étape 7)

POST http://localhost:8001/a2a/facts_agent
Content-Type: application/json

{
  "id": "uuid-123",
  "params": {
    "message": {
      "messageId": "msg-456",
      "parts": [{"text": "Dites-moi un fait sur l'IA"}],
      "role": "user"
    }
  }
}

3. Phase de retour de réponse (Étape 16)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "result": {
    "messageId": "response-789",
    "parts": [{"text": "Voici un fait intéressant sur l'IA..."}],
    "role": "agent"
  }
}

Résumé

Grâce à ce guide, vous avez appris à implémenter le protocole A2A en utilisant le framework ADK pour construire un système complet de communication agent-à-agent. Les points d'apprentissage clés sont les suivants :

🎯 Compétences principales

  • ✅ Configuration de l'environnement ADK A2A : Configurer l'environnement de développement à partir de zéro
  • ✅ Développement d'agents A2A côté serveur : Créer des agents intelligents avec des fonctionnalités réelles en utilisant ADK
  • ✅ Développement d'agents A2A côté client : Implémenter la connexion d'agents distants via RemoteA2aAgent
  • ✅ Compréhension du protocole A2A : Maîtrise approfondie du protocole de communication Agent2Agent
  • ✅ Test de l'interface utilisateur web ADK : Test de bout en bout en utilisant l'interface utilisateur web fournie par ADK

🚀 Avantages techniques

  • Standardisation : Communication d'agents standardisée basée sur le protocole A2A
  • Distribué : ADK prend en charge le déploiement d'agents A2A inter-serveurs
  • Évolutif : Facile d'ajouter de nouvelles fonctionnalités et d'intégrer avec l'écosystème A2A
  • Prêt pour la production : Stabilité et sécurité de niveau entreprise

🔮 Prochaines étapes

  • Explorer plus d'outils ADK et d'options d'intégration A2A
  • Construire des systèmes de collaboration multi-agents A2A
  • Implémenter des extensions de protocole A2A personnalisées
  • Déployer des solutions ADK A2A en environnement de production

L'implémentation A2A d'ADK fournit une base puissante pour construire des systèmes d'agents intelligents de nouvelle génération, rendant la collaboration d'agents simple et efficace. Commencez votre parcours de développement ADK A2A !

Ressources de référence

Mots-clés : A2A ADK, Agent Development Kit, protocole A2A, développement d'agents, communication d'agents intelligents, Google ADK, protocole d'agents, système d'agents distribués, RemoteA2aAgent, API Gemini