> For the complete documentation index, see [llms.txt](https://cleyrop.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cleyrop.gitbook.io/docs/v4.7/la-fabrique/deployer-des-apps-et-des-tools.md). # Déployer des Apps et des Tools Créez et déployez vos applications et outils IA directement sur la plateforme via la Fabrique. {% hint style="info" %} La terminologie de La Fabrique a évolué : * La Fabrique à Agents devient **La Fabrique**, * les **Agent Apps** et **Agent Tools** deviennent les **Apps** et **Tools** — l'ensemble étant désigné par le terme **Apps** * les **Contextes IA** deviennent les **Agents**. {% endhint %} La Fabrique permet de **créer, déployer et administrer** des applications - **Apps** et serveurs MCP- **Tools** au sein de la plateforme Cleyrop. Elle offre un cadre sécurisé et standardisé pour développer des applications et des extensions basées sur des modèles d’IA et des connecteurs externes. *** ## Comprendre les types d'apps ### Application - App Une App est une **application** autonome déployée sur Cleyrop. Elle dispose d’une **URL dédiée** et fonctionne indépendamment du Druide. Elle peut être utilisée pour exposer une interface utilisateur interactive, par exemple un dashboard Gradio ou une mini-application de traitement, un modèle ML, une API... Les Apps peuvent être utilisées depuis l'extérieur via une IP whitelistée avec l'URL de l'app ou depuis la plateforme des services Cleyrop grâce à l'URL interne : un **Dataflow, une App, un DevSpace** ou un **Notebook du Codelab.** ### MCP serveur - Tool Un Tool dans Cleyrop correspond à un **serveur MCP** déclaré et géré depuis La Fabrique. Il permet d’étendre les **capacités du Druide** en lui donnant accès à des services externes, APIs ou outils internes. Il est également disponible pour être utilisé dans un **Dataflow, une App** ou un **Notebook du Codelab.** 👉 Pour les développeurs souhaitant créer leurs propres outils, consultez la documentation MCP officielle : **Principes clés** * Chaque Tool expose un **endpoint compatible MCP** : la plateforme appelle votre serveur avec des requêtes `POST /mcp`, **sans slash final**. Exposez votre serveur MCP sur ce chemin exact (`/mcp`), avec le transport HTTP du protocole. * Les outils définis dans le serveur peuvent être **activés ou désactivés** depuis Le Druide. * Les **variables utilisateur** (ex : clés API, filtres métiers) peuvent être configurées directement dans l’assistant ou au niveau du listing des apps. * La communication se fait en **temps réel** : l’assistant appelle le serveur, exécute l’action, puis restitue la réponse à l’utilisateur. **Exemples d’usages** * Génération automatique de documents (Word, PDF…). * Envoi de mails ou notifications. * Extraction de données depuis des API internes ou externes. * Interaction avec des outils métier (Jira, Lucca, CRM…). **Bonnes pratiques pour les développeurs de Tools** Pour garantir une intégration fluide et une utilisation optimale de vos outils : * Par défaut, l'ensemble des Tools sont activées dans Le Druide : **décrivez précisément** la fonction de chaque tool dans sa documentation. * Spécifiez clairement les entrées et sorties attendues : types, formats, contraintes, valeurs possibles, structure du retour, format JSON, champs clés. * Respectez la **cohérence des schémas** entre les outils pour faciliter leur combinaison dans un même contexte. * **Testez vos tools dans Le Druide** avant partage aux utilisateurs finaux. **Récupérer une variable utilisateur dans un Tool MCP** Lorsqu'un utilisateur configure une variable utilisateur d'un Tool (via l'engrenage de configuration dans le Druide, ou via la fiche détaillée du Tool), cette valeur n'est pas exposée au serveur MCP comme variable d'environnement. À la place, le Druide transmet les variables utilisateur dans les headers de chaque requête HTTP adressée au Tool. Chaque appel de tool comporte ainsi la ou les variables propres à l'utilisateur qui l'a déclenché. Pour récupérer ces valeurs dans le code de votre Tool, utilisez `get_http_request()` (fourni par FastMCP), puis lisez le header voulu sur `request.headers`. Le nom du header correspond à celui de la variable utilisateur. **Exemple de code :** ```python """Utility for extracting user access token from FastMCP request headers.""" import logging from typing import TYPE_CHECKING, Optional from fastmcp.server.dependencies import get_http_request from src.config.corpus_mcp_config import get_corpus_mcp_config if TYPE_CHECKING: from starlette.datastructures import Headers from starlette.requests import Request logger = logging.getLogger(__name__) def get_user_access_token() -> Optional[str]: """Extract the user access token from the request headers.""" request: Request = get_http_request() headers: Headers = request.headers return headers.get(get_corpus_mcp_config().user_access_token_header) ``` #### Rendre un Tool utilisable par Le Druide Une fois l'instance du Tool déployée, la plateforme interroge votre serveur pour récupérer la liste de ses outils. Pour que cette découverte réussisse : * **URL appelée** : `http://..svc.cluster.local:/mcp`. Le nom technique et le namespace sont indiqués dans la fiche de l'instance ; le port est celui déclaré à l'étape Déploiement. * **Chemin exact `/mcp`**, sans slash final : la plateforme ne suit pas les redirections. Un serveur qui ne répond que sur `/mcp/` renvoie une erreur 404 et n'expose aucun outil. * **Découverte au déploiement uniquement** : la liste des outils est lue lors du déploiement ou de la mise à jour de l'instance, jamais périodiquement. Si votre serveur n'était pas prêt à ce moment-là, ou si vous modifiez ses outils ou son chemin, **redéployez l'instance** pour relancer la découverte. * **Health check sans authentification** : le chemin de health check déclaré à l'étape Déploiement doit répondre sans jeton. {% hint style="warning" %} Si la découverte échoue, le Tool apparaît quand même comme déployé et activable dans Le Druide, mais son onglet **Outils** est vide et Le Druide ne peut rien exécuter. Vérifiez le chemin `/mcp`, le port exposé et les logs applicatifs de l'instance, puis redéployez-la. {% endhint %} #### Tools natifs Cleyrop Cleyrop met à disposition plusieurs **Tools natifs**, visibles dans la liste des Apps et Tools au même titre que les vôtres : * **Cleyrop Corpus** — permet d'[interroger un corpus de documents](/docs/v4.7/le-druide/interroger-un-corpus-de-documents.md) depuis Le Druide * **Cleyrop Dataset** — permet d'[interroger des datasets](/docs/v4.7/le-druide/interroger-des-datasets.md) depuis Le Druide * **Cleyrop Internet** — permet d'effectuer des recherches internet depuis Le Druide Contrairement à vos propres Apps et Tools, seule l'action **Configurer** (gestion du token) est accessible sur leur fiche. Les Tools natifs sont également appelables depuis vos propres Apps, DevSpaces ou notebooks par leur URL interne : voir [Utiliser Cleyrop Dataset depuis vos propres apps](/docs/v4.7/le-druide/interroger-des-datasets.md#utiliser-cleyrop-dataset-depuis-vos-propres-apps). {% hint style="info" %} Le tool **Cleyrop Internet** ne nécessite pas de configuration de token. {% endhint %} ## Créer une App La création se fait en deux temps : * d'abord la création de l'App (nom et description) * puis la configuration des images et instances. ### **Étape 1 : Créer l'App** 1. Accédez à **La** **Fabrique** → Apps 2. Cliquez sur **Créer** 3. Renseignez : * **Nom** : identifiant unique de votre App (50 caractères max, doublons interdits) * Activez **Marquer cette app comme Tool** s'il s'agit d'un serveur MCP * **Description** : texte libre supportant le markdown (titres, gras, italique, listes, liens) 4. Sélectionnez si besoin les **Apps et Tools** auxquels votre App pourra faire appel parmi la liste d'apps disponible sur la plateforme. Par défaut, aucun accès n'est configuré. 5. Cliquez sur **Créer** À ce stade, aucune image ni instance n'est configurée.
### **Étape 2 : Configurer les images et instances** Depuis la fiche de l'App, vous pouvez : * [**Créer et build une image**](/docs/v4.7/la-fabrique/gerer-les-images.md) depuis un repository Git dans le registre interne Cleyrop * [**Créer et déployer une instance**](/docs/v4.7/la-fabrique/gerer-les-instances.md) depuis une image du registre interne ou d'un registre externe {% hint style="info" %} La première instance créée devient automatiquement l'instance principale de l'App. {% endhint %} ### Démarrage de l'instance et accès réseau sortant Au déploiement, la plateforme attend que votre application réponde à son **Health check** (TCP ou HTTP, configuré à l'étape Déploiement). Ce délai de démarrage est d'environ **2 minutes** et ne dépend pas du **timeout de déploiement** de l'instance : une application qui ne répond pas dans ce délai est redémarrée et le déploiement échoue, même si l'image est correcte. Les flux sortants d'une instance sont **fermés par défaut**, sauf vers les services de la plateforme et les ports internet déclarés à l'étape Déploiement (à date, 443 pour HTTPS et 22 pour SSH). Une connexion vers une destination non autorisée n'est pas refusée : elle **reste en attente** jusqu'à expiration. Un appel réseau bloquant au démarrage (téléchargement d'un modèle, connexion à une base externe, installation de dépendances) peut donc empêcher l'application de répondre au health check à temps. Pour un démarrage fiable : * Exposez le chemin de health check **avant** les initialisations longues, et lancez celles-ci en arrière-plan ou à la première requête. * Embarquez les dépendances et les modèles dans l'image plutôt que de les télécharger au démarrage (pour les modèles Hugging Face, définissez `HF_HUB_OFFLINE=1`). * Si votre application doit joindre un service externe, déclarez le port nécessaire à l'étape Déploiement et vérifiez l'accès dans les logs applicatifs. ## Utiliser une App Vous pouvez retrouver la liste des apps utilisables depuis Applications > Apps/Tools. Vous pouvez les filtrer par Statut. * Une App peut être ouverte directement depuis sa card ou via son URL présente sur sa fiche. * Les Tools déployés en succès sont utilisables directement depuis Le Druide. Il est possible d’activer ou désactiver chaque outil présent sur chaque Tool déployé. {% hint style="warning" %} Les App sont accessibles par les **IP whitelistées** {% endhint %}
Certains Tools nécessitent d'être configurées pour être utilisées, vous verrez alors apparaitre un bouton :gear: sur la carte ou la fiche. Vous verrez alors la liste de variables d'environnement à renseigner afin de pouvoir utiliser le Tool avec vos accréditations.
### Consulter les outils d’un Tool Vous pouvez accéder à la liste complète des outils proposés par un Tool, ainsi qu’à leurs paramètres d’entrée et de sortie, pour comprendre les cas d’usage couverts. Dans la fiche d’un Tool, un onglet Outils apparaît automatiquement. Cet onglet n’est pas présent sur les App. Il permet de consulter la **liste des outils** et pour chaque outil disponible : * **Description** : ce que fait l’outil, et dans quel cas l’utiliser. * **Paramètres d’entrée** : les champs attendus, leur type et leur rôle. * **Paramètres de sortie** : la structure des données retournées. Cette vue permet à l’utilisateur de comprendre rapidement comment utiliser un Tool dans Le Druide ou lors de développements avancés. ### Accéder aux Apps depuis un DevSpace Les Apps créés dans La Fabrique peuvent être accessibles depuis un DevSpace pour faciliter le développement et les tests. **Configurer l'accès** 1. Lors de la création ou de la modification d'un DevSpace, accédez à la section "Apps". 2. Recherchez votre App par son nom. 3. Cochez les Apps auxquels le DevSpace doit pouvoir se connecter. 4. Sauvegardez les modifications. ### Surveiller les ressources Un récapitulatif des ressources réservées est accessible depuis le bouton **Ressources utilisées** en haut à droite de La Fabrique. Il affiche, en CPU et en RAM, la **Demande** (ressources garanties) et la **Limite** (plafond) de l'ensemble des Apps, Tools et DevSpaces déployés sur votre environnement. Le détail et les recommandations sont décrits dans [Surveiller les ressources](/docs/v4.7/administration/surveiller-les-ressources.md).
Encart Ressources utilisées de La Fabrique
*** ## Bonnes pratiques * Utilisez des images Docker légères, testées localement et compatibles **linux/amd64**. * Donnez des noms explicites et documentez les variables pour faciliter la maintenance. * Consultez régulièrement les logs et utilisez le rollback automatique en cas d’échec de déploiement. * Pensez à modulariser vos apps : un modèle, un module d’embedding, un outil métier → un Tool clair.