✈️ Flight Search Agent

Auteur : Saad Bendahou
Contexte : Projet académique - Deep Learning / Intelligence Artificielle
Année : 2025

📋 Description

Flight Search Agent est un agent conversationnel intelligent développé pour la recherche et la réservation de vols. Le projet utilise le protocole MCP (Model Context Protocol) pour exposer des outils de recherche standardisés, intègre Google Gemini API pour la compréhension du langage naturel, et l'API Amadeus pour récupérer des données de vols réelles en temps réel.

L'interface web moderne est développée avec FastAPI et offre une expérience utilisateur immersive avec un arrière-plan animé et des étiquettes de villes flottantes.

🎯 Caractéristiques principales

• ✅ Recherche de vols intelligente entre différentes villes (Maroc, Europe, Monde)

• ✅ Compréhension du langage naturel : dates relatives ("demain", "la semaine prochaine")

• ✅ Google Gemini API : LLM rapide et efficace (gemini-2.5-flash)

• ✅ Protocole MCP : Exposition d'outils de recherche standardisés

• ✅ Intégration API Amadeus : Données de vols réelles et professionnelles

• ✅ Interface FastAPI : Interface web moderne avec HTML/CSS/JS personnalisé

• ✅ Multilingue : Support Français et Anglais

• ✅ Parsing de dates : Conversion automatique de dates naturelles

• ✅ Validation stricte : L'application ne démarre que si les APIs sont configurées

Related MCP server: Google Flights MCP Server

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         UTILISATEUR                              │
│                    (Interface Web FastAPI)                       │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    app_fastapi.py                                 │
│              - Endpoint / : Page HTML                             │
│              - Endpoint /chat : API REST                          │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                  gemini_agent.py                                  │
│         - GeminiFlightAgent : Agent principal                     │
│         - Compréhension du langage naturel                        │
│         - Extraction des paramètres (origine, destination, date)   │
│         - Formatage des réponses                                  │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    flight_data.py                                 │
│         - search_flights() : Fonction principale                  │
│         - Gestion des données de vols                             │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    amadeus_api.py                                │
│         - search_flights_amadeus() : Recherche réelle             │
│         - get_airport_code() : Conversion ville → code IATA       │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                    date_parser.py                                │
│         - parse_date_with_context() : Parsing dates naturelles   │
│         - get_current_date_info() : Informations date actuelle    │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    mcp_server.py (Optionnel)                      │
│         - Serveur MCP pour intégration avec Cursor/Claude        │
│         - Exposition des mêmes outils via protocole MCP          │
└─────────────────────────────────────────────────────────────────┘

Flux de données

1. Utilisateur envoie une requête via l'interface web

2. FastAPI reçoit la requête et appelle gemini_agent.chat()

3. Gemini Agent analyse la requête et extrait les paramètres

4. Flight Data appelle amadeus_api.search_flights_amadeus()

5. Amadeus API retourne les données de vols réelles

6. Gemini Agent formate la réponse de manière conviviale

7. FastAPI retourne la réponse formatée à l'utilisateur

📁 Structure du Projet

Flight_Search_Agent/
├── app_fastapi.py              # Application FastAPI principale
├── gemini_agent.py            # Agent Gemini + logique conversation
├── amadeus_api.py             # Intégration API Amadeus
├── flight_data.py             # Gestion des données de vols
├── date_parser.py             # Parseur de dates naturelles
├── mcp_server.py              # Serveur MCP (optionnel)
├── mcp_config.json            # Configuration MCP
│
├── templates/                 # Templates HTML
│   └── index.html             # Interface web principale
│
├── static/                     # Fichiers statiques
│   └── Bg.jpg                 # Image de fond
│
├── requirements.txt           # Dépendances Python
├── .gitignore                 # Fichiers ignorés par Git
├── .env                       # Variables d'environnement (non versionné)
└── README.md                  # Documentation

🛠️ Installation

Prérequis

• Python 3.10+

• Clés API :

  • Google Gemini API : Google AI Studio

  • Amadeus API : Amadeus for Developers

1. Cloner le projet

git clone <repository-url>
cd Flight_Search_Agent

2. Installer les dépendances

pip install -r requirements.txt

3. Configurer les variables d'environnement

Créez un fichier .env à la racine du projet :

GEMINI_API_KEY=votre_cle_gemini_ici
AMADEUS_CLIENT_ID=votre_client_id_ici
AMADEUS_CLIENT_SECRET=votre_client_secret_ici

Important : L'application ne démarrera PAS si ces variables ne sont pas configurées ou si elles contiennent des valeurs placeholder.

4. Obtenir les clés API

Google Gemini API (Gratuit)

1. Allez sur Google AI Studio

2. Connectez-vous avec votre compte Google

3. Cliquez sur "Create API Key"

4. Copiez votre clé API

Amadeus API (Gratuit pour développeurs académiques)

1. Allez sur Amadeus for Developers

2. Créez un compte gratuit (compte académique/non-lucratif)

3. Créez une nouvelle application

4. Copiez votre Client ID et Client Secret

💻 Utilisation

Lancer l'application FastAPI

python app_fastapi.py

L'application sera accessible sur : http://localhost:8000

Utiliser le serveur MCP (Optionnel)

Pour intégrer avec Cursor/Claude Desktop :

python mcp_server.py

Puis configurez votre client MCP avec :

{
  "mcpServers": {
    "flight-search": {
      "command": "python",
      "args": ["mcp_server.py"],
      "cwd": "C:\\path\\to\\Flight_Search_Agent"
    }
  }
}

🎯 Exemples de Requêtes

L'agent comprend des requêtes en langage naturel :

"Je veux un vol de Casablanca à Paris demain"
"Trouve-moi un vol Marrakech - Bruxelles pour le 20 décembre"
"Quels vols sont disponibles de Rabat à Londres la semaine prochaine?"
"Vol pas cher de Fès à Barcelone le 15 janvier"

🌍 Villes Supportées

Maroc 🇲🇦

• Casablanca (CMN)

• Marrakech (RAK)

• Rabat (RBA)

• Fès (FEZ)

• Tanger (TNG)

• Agadir (AGA)

Europe 🇪🇺

• Paris (CDG/ORY)

• Londres (LHR)

• Madrid (MAD)

• Barcelone (BCN)

• Bruxelles (BRU)

• Amsterdam (AMS)

Autres 🌍

• Dubaï (DXB)

• Istanbul (IST)

• Montréal (YUL)

• New York (JFK)

• Washington (DCA)

🔧 Technologies Utilisées

• FastAPI - Framework web moderne et rapide

• Google Gemini API - LLM rapide et efficace (gemini-2.5-flash)

• Amadeus API - API professionnelle de recherche de vols

• MCP (Model Context Protocol) - Protocole d'exposition d'outils

• Python 3.10+ - Langage de développement

• Jinja2 - Moteur de templates HTML

• HTML/CSS/JavaScript - Interface web personnalisée

📋 Tools MCP Disponibles

1. search_flights

Recherche des vols entre deux villes avec date.

Paramètres :

• origin : Ville de départ (ex: "Casablanca", "CMN")

• destination : Ville d'arrivée (ex: "Paris", "CDG")

• date : Date de voyage au format YYYY-MM-DD

2. parse_date

Convertit une date naturelle en format ISO.

Paramètres :

• date_expression : Date en langage naturel (ex: "demain", "le 20 décembre")

3. get_current_date

Retourne la date actuelle et références.

4. list_airports

Liste les aéroports disponibles.

🐛 Dépannage

Erreur "APIs non configurées"

• Vérifiez que le fichier .env existe et contient les bonnes clés

• Vérifiez que les clés ne sont pas des placeholders

• L'application ne démarre PAS sans APIs configurées

Erreur "GEMINI_API_KEY not found"

• Vérifiez que vous avez défini la variable d'environnement GEMINI_API_KEY

• Obtenez votre clé sur Google AI Studio

Erreur "AMADEUS_CLIENT_ID not found"

• Vérifiez que vous avez défini les variables AMADEUS_CLIENT_ID et AMADEUS_CLIENT_SECRET

• Créez un compte sur Amadeus for Developers

Erreur de dépendances

pip install -r requirements.txt

L'API Amadeus retourne une erreur

• Vérifiez que vous utilisez l'environnement "test" (par défaut)

• Vérifiez les limites de votre compte Amadeus (gratuit pour développeurs)

• Vérifiez que les codes d'aéroport sont corrects

📝 Notes de Développement

Validation des APIs

L'application valide strictement la présence des APIs au démarrage. Si les clés sont manquantes ou contiennent des valeurs placeholder, l'application lève une exception et ne démarre pas.

Gestion des erreurs

• Les erreurs API sont capturées et retournées de manière conviviale à l'utilisateur

• L'historique de conversation est maintenu pour améliorer les réponses

• Les dates relatives sont automatiquement converties en format ISO

Interface utilisateur

• Arrière-plan avec image de ciel et nuages

• Étiquettes de villes flottantes avec animations

• Chat transparent avec bordures visibles

• Barre d'astuces rabattable depuis le haut

• Heure locale mise à jour en temps réel

📄 Licence

Ce projet est développé dans un contexte académique et non-lucratif.

👤 Auteur

Saad Bendahou
Projet académique - Deep Learning / Intelligence Artificielle
Année 2025

🙏 Remerciements

• Google pour l'API Gemini

• Amadeus pour l'API de recherche de vols (compte académique)

• La communauté open-source Python

Développé avec ❤️ pour l'apprentissage et la recherche académique