Agent de Remboursement de Frais A2A ADK

Ceci est un agent intelligent de remboursement de frais développé sur la base du Google Agent Development Kit (ADK), fonctionnant comme un serveur Agent2Agent (A2A). La fonctionnalité principale de cet agent est la génération intelligente de formulaires : lorsque la demande de remboursement d'un utilisateur manque d'informations nécessaires, l'agent génère automatiquement un formulaire à remplir par l'utilisateur, garantissant la collecte d'informations complètes de remboursement avant le traitement.

Code Source

A2A ADK Sample

🎯 Caractéristiques du Projet

Interaction Intelligente de Formulaires : Détecte automatiquement les informations manquantes et génère des formulaires dynamiques
Support du Protocole A2A : Protocole de communication inter-agents standardisé
Traitement en Streaming : Prend en charge les réponses en temps réel et les mises à jour de statut
Intégration Google ADK : Basé sur le dernier kit de développement d'agents de Google

📋 Exigences Système

Python 3.12 ou supérieur
Outil de gestion de paquets UV
Clé API Google (accès au modèle Gemini)

🚀 Démarrage Rapide

1. Obtenir une Clé API Google

Visitez Google AI Studio
Connectez-vous à votre compte Google
Cliquez sur "Get API key"
Créez une nouvelle clé API ou utilisez une existante
Copiez la clé API pour une utilisation ultérieure

2. Configuration de l'Environnement

# Cloner le projet localement (si nécessaire)
git clone https://github.com/sing1ee/a2a-adk-expense-reimbursement.git
cd a2a-adk-expense-reimbursement

# Créer le fichier de variables d'environnement
echo "GOOGLE_API_KEY=your_api_key_here" > .env

# Remplacer your_api_key_here par votre clé API réelle

3. Installation des Dépendances et Exécution

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

# Exécuter le projet en utilisant uv
uv run .

Le serveur démarrera sur http://localhost:10002.

4. Test avec le Client CLI

Ouvrez une nouvelle fenêtre de terminal :

git clone https://github.com/a2aproject/a2a-samples.git
# Naviguer vers le répertoire du client CLI (en supposant qu'il soit dans samples/python/hosts/cli)
cd a2a-samples/samples/python/hosts/cli

# Se connecter à l'agent de remboursement
uv run . --agent http://localhost:10002

5. Exemples d'Interaction de Test

Entrez les commandes de test suivantes dans le client CLI :

# Exemple 1 : Demande avec informations manquantes (déclenchera un formulaire)
J'ai besoin de me faire rembourser 20$ pour le déjeuner

# Exemple 2 : Demande avec informations complètes
J'ai besoin de me faire rembourser 50$ pour un déjeuner client le 15 janvier 2024

# Exemple 3 : Demande avec informations partielles
Veuillez m'aider à me faire rembourser les frais de transport d'hier de 25$

🏗️ Architecture du Projet

Structure des Fichiers Principaux

a2a-adk-expense-reimbursement/
├── __main__.py          # Point d'entrée de démarrage du serveur
├── agent.py             # Logique principale de l'agent
├── agent_executor.py    # Exécuteur de requêtes A2A
├── pyproject.toml       # Configuration du projet et dépendances
└── README.md           # Documentation du projet

Description des Composants Principaux

1. `main.py` - Entrée du Serveur

Configurer les informations du serveur A2A et de l'agent
Définir les compétences et descriptions de capacités de l'agent
Démarrer le serveur HTTP pour écouter les requêtes

2. `agent.py` - Logique Principale de l'Agent

Contient trois fonctions d'outils clés :

create_request_form() : Créer un modèle de formulaire de remboursement
return_form() : Encapsuler le formulaire au format protocole A2A et le retourner
reimburse() : Exécuter l'opération d'approbation de remboursement réelle

3. `agent_executor.py` - Exécuteur de Requêtes

Gérer les requêtes et réponses du protocole A2A
Gérer les états des tâches (en cours, nécessite une entrée, terminé, etc.)
Coordonner la communication entre l'agent et le serveur A2A

🔄 Flux de Travail Principal

Le diagramme de séquence suivant montre le flux d'interaction complet de l'agent de remboursement :

sequenceDiagram
    participant User as Utilisateur/Client CLI
    participant Server as Serveur A2A
    participant Agent as Agent de Remboursement
    participant LLM as Gemini 2.0 Flash

    User->>Server: Envoyer demande de remboursement<br/>"J'ai besoin de me faire rembourser 20$ pour le déjeuner"
    Server->>Agent: Transférer la demande utilisateur
    Agent->>LLM: Analyser le contenu de la demande
    LLM->>Agent: Identifier la date manquante et autres infos
    Agent->>Agent: Appeler create_request_form()
    Agent->>Agent: Appeler return_form()
    Agent->>Server: Retourner la structure du formulaire
    Server->>User: Retourner le formulaire JSON<br/>contenant les champs date, montant, objectif
    
    User->>User: L'utilisateur remplit le formulaire<br/>date, montant, objectif
    User->>Server: Soumettre le formulaire complété
    Server->>Agent: Transférer les données du formulaire
    Agent->>LLM: Valider la complétude du formulaire
    LLM->>Agent: Confirmer que les informations sont complètes
    Agent->>Agent: Appeler reimburse(request_id)
    Agent->>Server: Retourner le résultat d'approbation
    Server->>User: Retourner le résultat final<br/>"Remboursement approuvé"

Détails du Flux de Travail

Réception de Demande : L'utilisateur envoie une demande de remboursement via le client CLI
Analyse Intelligente : Le modèle Gemini analyse la demande et identifie les informations nécessaires manquantes
Génération de Formulaire : Si les informations sont incomplètes, génère automatiquement un formulaire avec les champs requis
Interaction Utilisateur : L'utilisateur remplit le formulaire pour compléter les informations manquantes
Validation des Informations : Valide la complétude et la validité des données du formulaire
Traitement du Remboursement : Exécute l'approbation de remboursement et retourne le résultat

🛠️ Configuration Avancée

Variables d'Environnement

# Configuration de l'API Google
GOOGLE_API_KEY=your_api_key_here

# Utiliser Vertex AI (optionnel)
GOOGLE_GENAI_USE_VERTEXAI=TRUE

# Configuration du serveur
HOST=localhost
PORT=10002

Exécution avec Port Personnalisé

uv run . --host 0.0.0.0 --port 8080

🧪 Développement et Débogage

Activer la Journalisation Détaillée

L'agent active par défaut la journalisation de niveau INFO. Voir le traitement détaillé des requêtes :

# Voir les journaux du serveur
uv run . 2>&1 | tee agent.log

Exemple de Structure de Formulaire

L'agent génère des formulaires suivant le format JSON Schema :

{
  "type": "form",
  "form": {
    "type": "object",
    "properties": {
      "date": {
        "type": "string",
        "format": "date",
        "title": "Date",
        "description": "Date of expense"
      },
      "amount": {
        "type": "string",
        "format": "number", 
        "title": "Amount",
        "description": "Amount of expense"
      },
      "purpose": {
        "type": "string",
        "title": "Purpose",
        "description": "Purpose of expense"
      }
    },
    "required": ["date", "amount", "purpose"]
  }
}

⚠️ Considérations de Sécurité

Avis Important : Ce code d'exemple est uniquement à des fins de démonstration pour montrer comment fonctionne le protocole Agent2Agent (A2A). Lors de la construction d'applications de production, tout agent externe doit être traité comme une entité potentiellement non fiable.

Mesures de Sécurité

Validation d'Entrée : Valider et assainir strictement toutes les entrées externes
Traitement des Données : Gérer avec prudence les cartes d'agents, messages, artefacts et autres données
Gestion des Identifiants : Implémenter des mesures appropriées de protection des identifiants
Contrôle des Permissions : Limiter les permissions d'accès et la portée des opérations de l'agent

A2A ADK Expense Reimbursement Agent