A2A Protocol

Agent de Planification de Contenu basé sur A2A et ADK

deutschEnglishfrançaisहिंदी日本語한국어中文
MILO•
Share
ADK
Content Planner Agent Based on A2A and ADK

Aperçu du Projet

L'Agent de Planification de Contenu est un agent intelligent de planification de contenu construit sur Google Agent Development Kit (ADK) et Python A2A SDK. Cet agent peut créer des plans de contenu détaillés basés sur des descriptions de contenu de haut niveau.

Qu'est-ce que le Protocole A2A

Le Protocole A2A (Agent2Agent Protocol) est un protocole standard ouvert spécialement conçu pour les agents IA. Son objectif principal est d'atteindre l'interopérabilité entre les agents sur différentes plateformes et piles technologiques, leur permettant de collaborer comme des "collègues" pour accomplir des tâches, indépendamment de la technologie sous-jacente.

Stack Technologique

  • Python: 3.10+
  • UV: Gestionnaire de paquets Python
  • Google ADK: Google Agent Development Kit
  • A2A SDK: Protocole de communication Agent-to-Agent
  • Gemini 2.5 Flash: Modèle de langage large
  • Google Search: Outil de recherche
  • Uvicorn: Serveur ASGI

Prérequis

1. Configuration de l'Environnement

Assurez-vous que votre système dispose des logiciels suivants installés :

# Vérifier la version Python (3.10+ requis)
python --version

# Installer le gestionnaire de paquets UV (si pas déjà installé)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Ou utiliser pip
pip install uv

2. Clés API

Vous devez obtenir des clés API Google pour utiliser les modèles Gemini et la fonctionnalité Google Search :

  1. Visitez Google AI Studio
  2. Créez une nouvelle clé API
  3. Sauvegardez la clé pour une utilisation ultérieure

Structure du Projet

samples/python/agents/content_planner/
├── __init__.py                 # Fichier d'initialisation du paquet
├── __main__.py                # Fichier d'entrée principal
├── agent_executor.py          # Exécuteur d'agent
├── content_planner_agent.py   # Définition de l'agent de planification de contenu
├── pyproject.toml            # Fichier de configuration du projet
├── requirements.txt          # Liste des dépendances
├── .env.example             # Exemple de variables d'environnement
└── README.md               # Documentation du projet

Démarrage Rapide

Étape 1 : Cloner le projet et naviguer vers le répertoire

# En supposant que vous avez déjà le projet a2a-samples
git clone https://github.com/a2aproject/a2a-samples.git
cd a2a-samples/samples/python/agents/content_planner

Étape 2 : Configurer les variables d'environnement

# Copier le fichier d'exemple des variables d'environnement
cp .env.example .env

# Éditer le fichier .env et ajouter votre clé API Google
echo "GOOGLE_API_KEY=your_actual_api_key_here" > .env

Étape 3 : Installer les dépendances et exécuter l'agent

# Utiliser UV pour installer les dépendances et exécuter le projet
uv run .

# Note :
"gradio>=5.30.0" n'est pas nécessaire dans l'agent actuel.

Par défaut, l'agent démarrera sur http://localhost:10001.

Étape 4 : Tester l'agent (nouvelle fenêtre de terminal)

# Naviguer vers le répertoire du client CLI
cd samples/python/hosts/cli

# Se connecter à l'agent et envoyer un message
uv run . --agent http://localhost:10001

Étape 5 : Interagir avec l'agent

Dans le client CLI, vous pouvez envoyer des messages comme :

Create an outline for a short, upbeat, and encouraging X post about learning Java

Explication du Code

1. Fichier d'Entrée Principal (__main__.py)

@click.command()
@click.option("--host", default="localhost")
@click.option("--port", default=10001)
def main(host, port):
    # Carte d'agent (métadonnées)
    agent_card = AgentCard(
        name='Content Planner Agent',
        description=content_planner_agent.description,
        url=f'http://{host}:{port}',
        version="1.0.0",
        defaultInputModes=["text", "text/plain"],
        defaultOutputModes=["text", "text/plain"],
        capabilities=AgentCapabilities(streaming=True),
        skills=[
            AgentSkill(
                id="content_planner",
                name="Creates outlines for content",
                description="Creates outlines for content given a high-level description of the content",
                tags=["plan", "outline"],
                examples=[
                    "Create an outline for a short, upbeat, and encouraging X post about learning Java",
                ],
            )
        ],
    )

Explication des Composants Clés :

  • AgentCard : Carte de métadonnées d'agent contenant le nom, la description, l'URL, la version, etc.
  • AgentSkill : Définition des compétences d'agent incluant l'ID, le nom, la description, les tags et les exemples
  • AgentCapabilities : Configuration des capacités d'agent, comme le support du streaming

2. Définition de l'Agent (content_planner_agent.py)

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

root_agent = Agent(
    name="content_planner_agent",
    model="gemini-2.5-flash",
    description=("Planning agent that creates a detailed and logical outline for a piece of content,"
                 "given a high-level description."),
    instruction=("You are an expert content planner. Your task is to create a detailed and logical outline for a piece"
                 "of content, given a high-level description."),
    tools=[google_search],
)

Fonctionnalités Clés :

  • Model : Utilise Gemini 2.5 Flash comme LLM de base
  • Tools : Intègre l'outil Google Search pour la récupération d'informations pertinentes
  • Instructions : Définit clairement le rôle et les tâches de l'agent

3. Exécuteur d'Agent (agent_executor.py)

class ADKAgentExecutor(AgentExecutor):
    def __init__(self, agent, status_message="Processing request...", artifact_name="response"):
        self.agent = agent
        self.status_message = status_message
        self.artifact_name = artifact_name
        self.runner = Runner(
            app_name=agent.name,
            agent=agent,
            artifact_service=InMemoryArtifactService(),
            session_service=InMemorySessionService(),
            memory_service=InMemoryMemoryService(),
        )

Fonctionnalité Principale :

  • Runner : Runner ADK qui gère l'exécution de l'agent
  • Composants de Service :
    • ArtifactService : Gère les artefacts générés
    • SessionService : Gère l'état de session
    • MemoryService : Gère la mémoire de conversation

Diagramme de Flux de l'Architecture Système

graph TB
    A[Demande Utilisateur] --> B[Client CLI A2A]
    B --> C[Requête HTTP]
    C --> D[Application Starlette A2A]
    D --> E[DefaultRequestHandler]
    E --> F[ADKAgentExecutor]
    F --> G[ADK Runner]
    G --> H[Agent de Planification de Contenu]
    H --> I[Modèle Gemini 2.5 Flash]
    H --> J[Outil Google Search]
    I --> K[Génération de Plan de Contenu]
    J --> K
    K --> L[Artefact de Réponse]
    L --> M[Achèvement de Tâche]
    M --> N[Retourner le Résultat à l'Utilisateur]
    
    subgraph "Composants ADK"
        O[InMemoryArtifactService]
        P[InMemorySessionService]
        Q[InMemoryMemoryService]
    end
    
    G --> O
    G --> P
    G --> Q

Flux d'Exécution Détaillé

1. Phase d'Initialisation

sequenceDiagram
    participant Main as __main__.py
    participant Agent as content_planner_agent
    participant Executor as ADKAgentExecutor
    participant Server as A2AStarletteApplication
    
    Main->>Agent: Charger la configuration de l'agent
    Main->>Executor: Créer l'instance d'exécuteur
    Main->>Server: Créer le serveur A2A
    Server->>Server: Démarrer le serveur Uvicorn

2. Phase de Traitement des Requêtes

sequenceDiagram
    participant Client as Client CLI
    participant Server as Serveur A2A
    participant Handler as DefaultRequestHandler
    participant Executor as ADKAgentExecutor
    participant Runner as ADK Runner
    participant Model as Gemini 2.5 Flash
    participant Search as Google Search
    
    Client->>Server: Envoyer une demande de planification de contenu
    Server->>Handler: Router la requête
    Handler->>Executor: Exécuter la tâche d'agent
    Executor->>Runner: Démarrer le runner ADK
    Runner->>Model: Appeler le modèle Gemini
    Runner->>Search: Exécuter la recherche Google
    Model->>Runner: Retourner le contenu généré
    Search->>Runner: Retourner les résultats de recherche
    Runner->>Executor: Fusionner les résultats
    Executor->>Handler: Retourner l'artefact
    Handler->>Server: Terminer la tâche
    Server->>Client: Retourner le plan de contenu

Configuration Avancée

Port Personnalisé

# Démarrer l'agent sur un port spécifié
uv run . --port=8080

Hôte Personnalisé

# Démarrer sur un hôte et port spécifiés
uv run . --host=0.0.0.0 --port=8080

Configuration des Variables d'Environnement

Vous pouvez configurer plus d'options dans le fichier .env :

GOOGLE_API_KEY=your_api_key_here
# Vous pouvez ajouter d'autres éléments de configuration
LOG_LEVEL=INFO

Dépannage

Problèmes Courants

  1. Erreur de Clé API

    Erreur : Invalid API key
Solution : Vérifiez si GOOGLE_API_KEY dans le fichier .env est correct

  2. Port Déjà Utilisé

    Erreur : Port 10001 is already in use
Solution : Utilisez le paramètre --port pour spécifier un autre port

  3. Échec d'Installation des Dépendances

    Erreur : Failed to install dependencies
Solution : Assurez-vous qu'UV est correctement installé, essayez uv sync

Extension et Personnalisation

Ajouter de Nouveaux Outils

Ajoutez de nouveaux outils dans content_planner_agent.py :

from google.adk.tools import google_search, web_search

root_agent = Agent(
    # ... autres configurations
    tools=[google_search, web_search],  # Ajouter plus d'outils
)

Modifier le Modèle

root_agent = Agent(
    name="content_planner_agent",
    model="gemini-1.5-pro",  # Utiliser un modèle différent
    # ... autres configurations
)

Instructions Personnalisées

root_agent = Agent(
    # ... autres configurations
    instruction=(
        "Vous êtes un planificateur de contenu spécialisé dans la documentation technique. "
        "Créez des plans détaillés qui incluent des exemples de code et les meilleures pratiques."
    ),
)

Meilleures Pratiques

  1. Sécurité :

    • Stockez toujours les clés API dans les variables d'environnement
    • Ne commitez pas les fichiers .env dans le contrôle de version

  2. Optimisation des Performances :

    • Utilisez des tailles de modèle appropriées
    • Configurez correctement les services de mémoire et de session

  3. Gestion des Erreurs :

    • Implémentez une gestion d'erreur et un logging appropriés
    • Fournissez des messages d'erreur significatifs

  4. Tests :

    • Écrivez des tests unitaires et d'intégration
    • Testez les réponses de l'agent avec différentes entrées

Résumé

L'Agent de Planification de Contenu démontre comment construire des agents intelligents en utilisant Google ADK et le Protocole A2A. À travers ce guide, vous devriez être capable de :

  • Comprendre l'architecture globale du projet
  • Exécuter et tester l'agent avec succès
  • Personnaliser et étendre selon les besoins
  • Résoudre les problèmes courants

Cet agent peut servir de base pour construire des systèmes multi-agents plus complexes, comme des workflows complets de création de contenu.

Plus d'Exemples du Protocole A2A