> 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/v-4.5/la-fabrique/deployer-des-apps-et-des-tools.md). # Déployer des Apps et des Tools {% 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** (/mcp/metadata, /mcp/tools, /mcp/run). * 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) ``` ## 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/v-4.5/la-fabrique/gerer-les-images.md) depuis un repository Git dans le registre interne Cleyrop * [**Créer et déployer une instance**](/docs/v-4.5/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 %} {% hint style="warning" %} A date, pour les flux sortants vers internet seul les ports 443 et 22 sont autorisés {% endhint %} ## 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 de la consommation des ressources est accessible depuis le bouton **Ressources utilisées** en haut à droite de La Fabrique. Il affiche la consommation CPU et RAM (minimum et maximum) de l'ensemble des Apps, images et DevSpaces déployés sur votre environnement.
*** ## 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.