A2A + CrewAI + OpenRouter Chart Generation Agent Tutorial

Focus du Tutoriel

Ce tutoriel vous guidera dans la pratique des compétences clés suivantes :

• Intégrer OpenRouter + CrewAI + A2A : Développement d'agents de bout en bout complet utilisant OpenRouter comme fournisseur LLM, CrewAI comme framework d'agents, et le protocole A2A comme interface standardisée
• Pratiquer le Retour de Données d'Image d'Agents A2A : Apprenez comment faire générer et retourner des données d'image aux agents, pas seulement des réponses textuelles
• Utiliser A2A Inspector pour Déboguer les Applications A2A : Maîtrisez les outils de débogage professionnels pour tester et valider vos applications d'agents

Démarrage Rapide

1. Cloner le Code

git clone [email protected]:sing1ee/a2a-crewai-charts-agent.git
cd a2a-crewai-charts-agent

2. Créer la Configuration d'Environnement

Créer le fichier .env :

OPENROUTER_API_KEY=sk-or-v1-your-api-key-here
OPENAI_MODEL_NAME=openrouter/anthropic/claude-3.7-sonnet

3. Configuration d'Environnement et Exécution

# Créer l'environnement virtuel
uv venv

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

# Exécuter l'application
uv run .

L'application démarrera sur http://localhost:10011.

Déboguer avec A2A Inspector

A2A Inspector est un outil puissant spécialement conçu pour déboguer les applications A2A.

Étapes de Débogage :

1. Accéder à A2A Inspector : Ouvrir https://inspector.a2aprotocol.ai

2. Se Connecter à Votre Agent :

   • Entrer l'adresse de votre Agent dans Inspector : http://localhost:10011
   • Cliquer sur "Connect" pour établir la connexion

3. Tester la Fonctionnalité de l'Agent :

   • Envoyer un message de test : "Generate a chart of revenue: Jan,1000 Feb,2000 Mar,1500"
   • Observer le processus complet d'interaction du protocole A2A
   • Visualiser les données d'image retournées

4. Déboguer et Surveiller :

   • Vérifier les capacités et compétences de l'Agent
   • Surveiller le flux complet de requête et réponse
   • Vérifier la transmission correcte des données d'image

Référez-vous à la Documentation A2A Inspector pour des guides de débogage plus détaillés.

Processus Principal et Introduction du Code

Diagramme de Séquence de l'Architecture Système

sequenceDiagram
    participant U as User
    participant A2A as A2A Inspector
    participant S as A2A Server
    participant H as DefaultRequestHandler
    participant E as ChartGenerationAgentExecutor
    participant CA as ChartGenerationAgent
    participant Crew as CrewAI Crew
    participant Tool as ChartGenerationTool
    participant MP as Matplotlib
    participant Cache as InMemoryCache

    U->>A2A: Send prompt "Generate chart: A,100 B,200"
    A2A->>S: HTTP POST /tasks with A2A message
    S->>H: Handle request with RequestContext
    H->>E: execute(context, event_queue)
    E->>CA: invoke(query, session_id)
    CA->>Crew: kickoff with inputs
    Crew->>Tool: generate_chart_tool(prompt, session_id)
    Tool->>Tool: Parse CSV data
    Tool->>MP: Create bar chart with matplotlib
    MP-->>Tool: Return PNG bytes
    Tool->>Cache: Store image with ID
    Cache-->>Tool: Confirm storage
    Tool-->>Crew: Return image ID
    Crew-->>CA: Return image ID
    CA-->>E: Return image ID
    E->>CA: get_image_data(session_id, image_key)
    CA->>Cache: Retrieve image data
    Cache-->>CA: Return Imagedata
    CA-->>E: Return Imagedata
    E->>H: Create FilePart with image bytes
    H->>S: enqueue completed_task event
    S-->>A2A: Return A2A response with image
    A2A-->>U: Display generated chart

Détails des Composants Principaux

1. Initialisation du Serveur A2A (__main__.py)

# Définir les capacités et compétences de l'Agent
capabilities = AgentCapabilities(streaming=False)
skill = AgentSkill(
    id='chart_generator',
    name='Chart Generator',
    description='Generate a chart based on CSV-like data passed in',
    tags=['generate image', 'edit image'],
    examples=['Generate a chart of revenue: Jan,$1000 Feb,$2000 Mar,$1500'],
)

# Créer la carte de l'Agent
agent_card = AgentCard(
    name='Chart Generator Agent',
    description='Generate charts from structured CSV-like data input.',
    url=f'http://{host}:{port}/',
    version='1.0.0',
    defaultInputModes=ChartGenerationAgent.SUPPORTED_CONTENT_TYPES,
    defaultOutputModes=ChartGenerationAgent.SUPPORTED_CONTENT_TYPES,
    capabilities=capabilities,
    skills=[skill],
)

Points Clés :

• AgentCapabilities définit les fonctions d'Agent supportées (streaming désactivé ici)
• AgentSkill décrit les compétences spécifiques de l'Agent et exemples d'utilisation
• AgentCard est l'identité de l'Agent dans le protocole A2A

2. Implémentation de l'Agent CrewAI (agent.py)

class ChartGenerationAgent:
    def __init__(self):
        # Créer un agent spécialisé de génération de graphiques
        self.chart_creator_agent = Agent(
            role='Chart Creation Expert',
            goal='Generate a bar chart image based on structured CSV input.',
            backstory='You are a data visualization expert who transforms structured data into visual charts.',
            verbose=False,
            allow_delegation=False,
            tools=[generate_chart_tool],
        )

        # Définir la tâche
        self.chart_creation_task = Task(
            description=(
                "You are given a prompt: '{user_prompt}'.\n"
                "If the prompt includes comma-separated key:value pairs (e.g. 'a:100, b:200'), "
                "reformat it into CSV with header 'Category,Value'.\n"
                "Ensure it becomes two-column CSV, then pass that to the 'ChartGenerationTool'.\n"
                "Use session ID: '{session_id}' when calling the tool."
            ),
            expected_output='The id of the generated chart image',
            agent=self.chart_creator_agent,
        )

Points Clés :

• La classe Agent de CrewAI définit les rôles et capacités de l'assistant IA
• La classe Task décrit la logique d'exécution de tâches spécifiques
• Les outils personnalisés sont intégrés dans l'Agent via le paramètre tools

3. Outil de Génération de Graphiques

@tool('ChartGenerationTool')
def generate_chart_tool(prompt: str, session_id: str) -> str:
    """Generates a bar chart image from CSV-like input using matplotlib."""
    
    # Analyser les données CSV
    df = pd.read_csv(StringIO(prompt))
    df.columns = ['Category', 'Value']
    df['Value'] = pd.to_numeric(df['Value'], errors='coerce')
    
    # Générer le graphique en barres
    fig, ax = plt.subplots()
    ax.bar(df['Category'], df['Value'])
    ax.set_xlabel('Category')
    ax.set_ylabel('Value')
    ax.set_title('Bar Chart')
    
    # Sauvegarder en octets PNG
    buf = BytesIO()
    plt.savefig(buf, format='png')
    plt.close(fig)
    buf.seek(0)
    image_bytes = buf.read()
    
    # Encoder et mettre en cache l'image
    data = Imagedata(
        bytes=base64.b64encode(image_bytes).decode('utf-8'),
        mime_type='image/png',
        name='generated_chart.png',
        id=uuid4().hex,
    )
    
    # Stocker l'image dans le cache
    session_data = cache.get(session_id) or {}
    session_data[data.id] = data
    cache.set(session_id, session_data)
    
    return data.id

Points Clés :

• Utiliser le décorateur @tool pour convertir la fonction en outil CrewAI
• Utiliser pandas pour analyser les données CSV, matplotlib pour générer les graphiques
• Images stockées en encodage base64 pour la transmission réseau
• Utiliser les ID de session pour gérer l'isolation des données pour plusieurs utilisateurs

4. Exécuteur A2A (agent_executor.py)

class ChartGenerationAgentExecutor(AgentExecutor):
    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
        # Obtenir l'entrée utilisateur
        query = context.get_user_input()
        
        # Appeler l'Agent CrewAI
        result = self.agent.invoke(query, context.context_id)
        
        # Obtenir les données d'image générées
        data = self.agent.get_image_data(
            session_id=context.context_id, 
            image_key=result.raw
        )
        
        if data and not data.error:
            # Créer une partie de fichier contenant les octets d'image
            parts = [
                Part(
                    root=FilePart(
                        file=FileWithBytes(
                            bytes=data.bytes,
                            mimeType=data.mime_type,
                            name=data.name,
                        )
                    )
                )
            ]
        else:
            # Retourner un message texte en cas d'erreur
            parts = [Part(root=TextPart(text=data.error or 'Failed to generate chart image.'))]
        
        # Ajouter la tâche terminée à la file d'événements
        event_queue.enqueue_event(
            completed_task(
                context.task_id,
                context.context_id,
                [new_artifact(parts, f'chart_{context.task_id}')],
                [context.message],
            )
        )

Points Clés :

• AgentExecutor est la couche d'exécution du protocole A2A
• Obtenir les requêtes utilisateur via RequestContext
• Convertir les réponses CrewAI au format du protocole A2A
• Support pour retourner des données de type fichier (images)

5. Système de Cache (utils.py)

class InMemoryCache:
    """Cache en mémoire thread-safe simple sans expiration."""
    
    def __init__(self):
        self._lock = threading.Lock()
        self._store: dict[str, Any] = {}
    
    def get(self, key: str) -> Any | None:
        with self._lock:
            return self._store.get(key)
    
    def set(self, key: str, value: Any) -> None:
        with self._lock:
            self._store[key] = value

Points Clés :

• Implémentation de cache en mémoire thread-safe
• Utilisé pour stocker les données d'image générées
• Support l'isolation de session pour éviter la confusion des données utilisateur

Résumé de la Stack Technologique

• Protocole A2A : Protocole de communication d'agents standardisé
• CrewAI : Framework de collaboration multi-agents
• OpenRouter : Service d'agrégation d'API LLM
• Matplotlib : Bibliothèque de génération de graphiques Python
• Pandas : Bibliothèque de traitement de données
• UV : Gestionnaire de paquets Python moderne

Suggestions d'Extension

1. Support Plus de Types de Graphiques : Graphiques en secteurs, graphiques linéaires, nuages de points, etc.
2. Ajouter la Validation de Données : Validation plus forte des données d'entrée et gestion d'erreurs
3. Cache Persistant : Utiliser Redis ou le système de fichiers pour stocker les images
4. Support de Streaming : Support du progrès de génération de graphiques en temps réel
5. Entrée Multimodale : Support du téléchargement de fichiers CSV au lieu d'une entrée texte uniquement

Grâce à ce tutoriel, vous avez maîtrisé les compétences clés de construction d'agents pratiques utilisant la stack technologique IA moderne. Cet agent de génération de graphiques peut servir de base pour des applications d'analyse de données plus complexes.

System Prompt for AI

You are a professional assistant based on the CrewAI chart generation agent tutorial. This tutorial provides a comprehensive guide on building a complete AI chart generation application. I can help you with:

## What I Can Help You With:
- **Quick Start**: Guide you from scratch to build an agent application using OpenRouter + CrewAI + A2A protocol
- **Solve Technical Issues**: Answer specific questions about environment setup, code implementation, and debugging
- **Understand Core Concepts**: Explain how A2A protocol, CrewAI framework, and agent architecture work
- **Practical Guidance**: Provide best practices for image data handling, tool integration, and cache design
- **Debug Support**: Teach you to use A2A Inspector for professional debugging and troubleshooting

## You Can Ask Me:
- "How to configure OpenRouter API keys?"
- "How do CrewAI Agents and Tasks work?"
- "How to return image data after chart generation?"
- "How to connect and test my agent with A2A Inspector?"
- "How is the cache system implemented in the code?"
- "How to extend support for more chart types?"

I'll provide accurate, practical answers based on the tutorial content to help you quickly master modern AI agent development skills.

You can visit [A2AProtocol.ai](https://a2aprotocol.ai/) for more tutorials.