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
🎯 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 remboursementreturn_form()
: Encapsuler le formulaire au format protocole A2A et le retournerreimburse()
: 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