Outils de discussion

Chat peut autoriser le modèle à appeler des outils. Lorsqu’ils sont activés, un tour exécute une boucle native en plusieurs étapes : le modèle demande un outil, Libre WebUI l’exécute sous l’identité et avec les autorisations de la personne qui l’appelle, le résultat est renvoyé au modèle, puis la boucle continue jusqu’à ce que le modèle réponde. Un tour est limité à huit étapes, avec au plus huit appels par étape. Le bouton Arrêter annule l’appel au modèle, tout appel d’outil en cours et toute attente d’approbation.

Les appels d’outils sont enregistrés sous forme d’événements normalisés (chat.tool-call.v1, chat.tool-result.v1, chat.approval.v1) qui transitent de façon identique par le canal WebSocket privé et le flux d’événements durable. Après une actualisation ou une reconnexion, le même état est donc rejoué. Une fois le tour terminé, ses appels et des aperçus bornés de leurs résultats sont stockés dans le message de l’assistant.

Activer les outils

Les outils sont désactivés par défaut. Un administrateur les ouvre dans Paramètres → Gestion des utilisateurs → Accès et politiques → Accès aux outils (aux administrateurs uniquement ou à tout le monde). Chaque tour les active ensuite avec la clé plate de la zone de rédaction, qui ouvre un sélecteur : un interrupteur général et une case par outil intégré et par serveur enregistré. Le tour n’utilise ainsi que les outils choisis. Le sélecteur peut restreindre les liaisons d’un profil, jamais les élargir. Les discussions privées (incognito) ne proposent jamais d’outils : un appel d’outil est une action tournée vers l’extérieur et peut laisser des approbations et des journaux d’audit.

L’interrupteur Accès aux outils enregistre immédiatement. Cliquez dessus, ou utilisez Tab pour lui donner le focus et Space pour le basculer. Changer l’accès laisse la fenêtre des paramètres et sa position de défilement en place.

Un profil d’assistant (persona) peut limiter les outils proposés : les serveurs d’outils liés, un sous-ensemble d’outils intégrés, les compétences liées et les collections de connaissances liées restreignent ce que voit le modèle dans les sessions qui utilisent ce profil.

Outils intégrés

Treize outils propriétaires sont fournis avec Chat (tous en lecture seule, à l’exception des outils qui modifient les notes et le calendrier et passent par le flux d’approbation des effets) :

• web_search — utilise le moteur de recherche configuré par l’administrateur et respecte le mode d’accès à la recherche web.
• search_documents — effectue une recherche hybride dans les documents importés et les collections de connaissances de l’utilisateur, y compris les collections qui lui sont partagées (les liaisons du profil peuvent limiter les collections) ; chaque passage indique le fragment et l’emplacement source qui le citent.
• list_documents — répertorie les documents compris dans le périmètre de cette discussion, avec leur identifiant, leur type et leur taille, afin que le modèle puisse décider lesquels lire.
• read_document — lit une fenêtre bornée d’un document disponible à partir de son identifiant et d’un décalage, avec son emplacement source, afin de parcourir un fichier auquel la récupération seule ne permet pas de répondre.
• load_skill — charge les instructions complètes d’une compétence à partir de son slug ; la description de l’outil contient le manifeste des compétences activées de l’utilisateur, de sorte qu’elles restent différées jusqu’à ce que le modèle en ait besoin. Si la compétence comprend des fichiers associés, les instructions chargées se terminent par l’inventaire des fichiers.
• read_skill_file — lit un fichier associé inclus dans une compétence à partir de son slug et de son chemin relatif ; un document de référence volumineux ne consomme ainsi du contexte que lorsque le modèle l’ouvre réellement.
• list_notes — répertorie les notes personnelles et partagées de l’utilisateur avec leurs identifiants.
• read_note — lit l’intégralité du contenu d’une note à partir de son identifiant.
• create_note — crée une note (produit un effet et nécessite une approbation).
• update_note — remplace le contenu d’une note ; l’état précédent est conservé sous forme de révision restaurable, de sorte que toute modification par un modèle reste réversible (produit un effet et nécessite une approbation).
• list_calendar_events — répertorie les événements personnels et partagés du calendrier de l’utilisateur dans une plage exprimée en millisecondes depuis l’époque Unix.
• create_calendar_event — crée un événement de calendrier (produit un effet et nécessite une approbation).
• delete_calendar_event — supprime un événement de calendrier à partir de son identifiant (produit un effet et nécessite une approbation).

Serveurs d’outils

Les administrateurs enregistrent des serveurs d’outils externes sous Paramètres → Outils (les modèles de démarrage préremplissent le formulaire, notamment avec une API publique de démonstration sûre) :

• OpenAPI : une spécification JSON OpenAPI 3.x est récupérée une fois et fixée à l’aide d’une empreinte SHA-256. Chaque opération devient un outil ; les opérations GET sont classées en lecture seule et toutes les autres comme produisant un effet, sauf si un administrateur modifie ce classement pour l’outil concerné. L’exécution reconstitue l’appel à partir de l’opération fixée : les arguments du modèle ne choisissent jamais la destination.
• MCP (HTTP avec diffusion) : la liste des outils du serveur est récupérée par JSON-RPC et fixée de la même manière. annotations.readOnlyHint marque un outil comme accessible en lecture seule. Les serveurs MCP stdio ne sont volontairement pas pris en charge : aucun processus externe ne s’exécute dans le processus web.

Un inventaire modifié ne prend effet que lorsqu’un administrateur actualise le serveur. La révision fixée avance alors et les remplacements propres à chaque outil sont préservés. La disponibilité d’un serveur peut être réservée aux administrateurs, ouverte à tout le monde ou fondée sur des autorisations par l’intermédiaire du modèle commun d’autorisation des ressources (autorisations d’utilisateur et de groupe sur le serveur d’outils).

Identifiants

Les serveurs qui nécessitent une authentification utilisent des identifiants propres à chaque utilisateur (jeton Bearer ou en-tête nommé). Chaque secret est chiffré avec des données authentifiées supplémentaires qui le lient exactement à l’utilisateur et au serveur. Chaque personne le saisit sous Paramètres → Outils, et il n’est jamais partagé entre les comptes.

OAuth interactif (MCP)

Un serveur MCP peut aussi authentifier chaque personne individuellement. Enregistrez-le avec le mode d’authentification OAuth interactif : Libre WebUI lit le défi WWW-Authenticate renvoyé par le serveur, le suit jusqu’aux métadonnées de la ressource protégée, puis jusqu’aux métadonnées du serveur d’autorisation, et enregistre un client de façon dynamique (RFC 7591) lorsque le serveur d’autorisation propose l’enregistrement. Les fournisseurs qui n’enregistrent pas de clients automatiquement reçoivent un identifiant client fourni par un administrateur, avec un secret facultatif, sur le formulaire d’enregistrement ; le secret est chiffré aux côtés des points de terminaison découverts.

Chaque personne appuie ensuite sur Connecter sur la fiche du serveur et est redirigée vers le fournisseur. Le flux utilise PKCE (S256) avec un état CSRF, le vérificateur PKCE étant conservé dans un cookie HttpOnly propre à ce seul serveur. Le rappel échange le code côté serveur, stocke les jetons chiffrés avec la même liaison utilisateur-serveur qu’un secret statique, et renvoie le navigateur vers l’application avec un indicateur d’état : les jetons d’accès et de rafraîchissement n’atteignent jamais la page. Les jetons d’accès se rafraîchissent automatiquement une minute avant leur expiration, une fois par personne et par serveur même lorsque plusieurs appels d’outils se disputent la course. Lorsqu’un rafraîchissement est impossible, l’appel d’outil revient en demandant de se reconnecter plutôt que d’échouer anonymement. Déconnecter supprime les jetons de cette personne et laisse l’enregistrement en place ; supprimer le serveur efface aussi la configuration découverte.

Un serveur qui refuse une liste d’outils non authentifiée est tout de même enregistré : son inventaire est fixé lors de la première connexion réussie (et à chaque actualisation par un administrateur), afin que rien ne soit proposé à un modèle avant d’être connu.

Politique de sortie réseau

Chaque requête d’outil résout elle-même sa destination, refuse les plages d’adresses privées, de bouclage et de métadonnées, puis fixe la connexion à l’adresse résolue afin qu’une nouvelle liaison DNS ne puisse pas rediriger l’appel. Les réponses de redirection sont refusées. La taille des réponses est plafonnée et chaque appel possède un délai maximal strict. Des noms d’hôte internes exacts peuvent être autorisés avec TOOLS_PRIVATE_NETWORK_ALLOWLIST (séparés par des virgules) ; les hôtes autorisés restent fixés et plafonnés. La sortie des outils est renvoyée au modèle comme texte non fiable.

Approbations

Les outils en lecture seule s’exécutent sans demande. Un outil produisant un effet suspend le tour et interroge l’utilisateur : autoriser une fois, autoriser pour cette discussion, toujours autoriser cet outil sur ce serveur, ou refuser. Les décisions sont durables : une autorisation permanente subsiste après les redémarrages et peut être révoquée sous Paramètres → Outils. Une demande en attente expire après deux minutes, ce que le modèle interprète comme un refus. Un refus ou une expiration n’exécute jamais l’appel. Chaque décision et chaque appel laisse un événement de sécurité expurgé dans le journal d’audit.

Exemples

Activez d’abord la clé plate dans la zone de rédaction ; chacun des exemples suivants est un message de discussion ordinaire.

web_search — rechercher une information

Qu’est-ce qui a changé dans la dernière version de SQLite ? Recherchez sur le web avant de répondre.

Le modèle appelle web_search avec une requête telle que {"query": "SQLite latest release changelog"}. La carte de l’appel présente les extraits de résultats reçus et la réponse cite les informations trouvées. La recherche web doit être configurée et autorisée pour votre compte.

search_documents — interroger vos propres fichiers

Importez un PDF ou ajoutez des documents à une collection de connaissances, puis demandez :

Recherchez dans mes documents la clause de résiliation et citez-la exactement.

Le modèle appelle search_documents avec {"query": "termination clause"} et reçoit les passages correspondants accompagnés de leur document source, ce qui lui permet de les citer et de les attribuer.

load_skill — appliquer une compétence enregistrée

Créez une compétence sous Paramètres → Compétences (par exemple $release-notes, qui décrit la façon dont vous souhaitez rédiger les notes de version), puis demandez :

Rédigez les notes de version de cette différence avec $release-notes.

Le modèle voit la compétence dans son manifeste, appelle load_skill {"slug": "release-notes"} pour récupérer les instructions complètes, puis les suit. Saisir $ dans la zone de rédaction complète automatiquement les slugs de vos compétences.

Un serveur OpenAPI — par exemple une API météo

1. Paramètres → Outils → Enregistrer un serveur : nom Weather, type OpenAPI, URL de base https://api.example-weather.dev, URL de la spécification https://api.example-weather.dev/openapi.json, mode d’authentification bearer.

2. La spécification est fixée et ses opérations apparaissent comme des outils, par exemple getForecast (GET, lecture seule) et createAlert (POST, produit un effet).

3. Chaque personne qui souhaite l’utiliser enregistre sa propre clé d’API sur la carte du serveur.

4. Dans la discussion :

   Quelles sont les prévisions à Montréal ce week-end ?

   Le modèle appelle weather__getForecast {"city": "Montreal"} et l’outil s’exécute immédiatement : les outils en lecture seule ne demandent jamais d’approbation.

   Avertissez-moi si la température descend sous -20 cette nuit.

   weather__createAlert produit un effet. Le tour se suspend donc avec une carte d’approbation : Autoriser une fois, Autoriser pour cette discussion, Toujours autoriser ou Refuser. Rien n’est envoyé avant votre choix.

Exa MCP — rechercher et récupérer des pages web

Dans Paramètres → Outils → Partir d'un modèle, choisissez Exa pour préremplir un enregistrement MCP avec :

https://mcp.exa.ai/mcp?tools=web_search_exa,web_fetch_exa

L'URL sélectionne web_search_exa et web_fetch_exa grâce au paramètre de sélection d'outils d'Exa. Le modèle n'utilise aucune authentification et limite l'accès aux administrateurs par défaut. Vérifiez le formulaire et choisissez Enregistrer pour vous connecter et épingler l'inventaire des outils. Ouvrir ou annuler le modèle ne contacte pas Exa. Les requêtes de recherche et les URL demandées sont envoyées à Exa lorsque ces outils s'exécutent.

Un serveur MCP — par exemple un outil de suivi des tickets

1. Paramètres → Outils → Enregistrer un serveur : nom Issues, type MCP, URL de base https://mcp.example-tracker.dev/mcp, mode d’authentification header avec le nom d’en-tête X-Api-Key.

2. Sa liste d’outils est fixée ; les outils que le serveur marque en lecture seule (comme search_issues) s’exécutent librement, tandis que tous les autres (comme create_issue) demandent d’abord une approbation.

3. Dans la discussion :

   Recherchez les tickets ouverts qui mentionnent « database lock » et créez-en un nouveau qui résume le schéma récurrent.

   issues__search_issues s’exécute immédiatement ; issues__create_issue affiche les arguments exacts dans la carte d’approbation afin que vous puissiez lire ce qui sera créé avant de l’autoriser.

Variables d’environnement

Variable	Effet
TOOLS_ACCESS_MODE	Fixe la fonctionnalité Outils sur admins ou all-users et verrouille le bouton de l’administrateur.
TOOLS_PRIVATE_NETWORK_ALLOWLIST	Noms d’hôte exacts que les serveurs d’outils peuvent résoudre vers des adresses privées (liste séparée par des virgules).

Limites

• Les appels d’outils s’exécutent sur le canal WebSocket (le transport des sessions privées est volontairement exclu) et le chemin de génération durable utilisé pour les discussions persistantes. L’ancien point de terminaison REST en diffusion n’exécute pas la boucle d’outils.
• Les mentions @model dans les canaux exécutent la même boucle sur le catalogue du membre mentionnant, avec une différence : il n’y a personne à qui demander, si bien qu’un outil produisant un effet sans approbation permanente est refusé immédiatement plutôt que mis en attente. Les outils en lecture seule s’exécutent normalement.
• Les agents Work appellent les mêmes serveurs par la même passerelle : uniquement pour les exécutions disposant du réseau, les serveurs sans identifiants étant écartés au moment de l’offre et les outils à effet soumis aux approbations Work.
• Les modèles Gemini et d’interface de ligne de commande agent ne reçoivent pas d’outils ; les fournisseurs Ollama, compatibles avec OpenAI, compatibles avec l’API Responses et Anthropic les prennent en charge.
• L’OAuth interactif est réservé à MCP : un serveur OpenAPI utilise toujours un identifiant statique propre à chaque utilisateur. Le flux est l’octroi par code d’autorisation avec PKCE ; les flux par code d’appareil et par identifiants client ne sont pas proposés, et un serveur d’autorisation qui ne publie aucune métadonnée (ou aucun point de terminaison d’enregistrement et aucun identifiant client fourni par un administrateur) ne peut pas être connecté.
• Les points de terminaison OAuth découverts doivent être en https ; le http en clair n’est accepté que pour le bouclage local, pour un fournisseur s’exécutant sur la même machine en développement.
• L’URI de redirection est dérivée de BASE_URL (ou du premier CORS_ORIGIN), cette valeur doit donc être l’adresse que le navigateur atteint réellement et doit être enregistrée auprès des fournisseurs qui fixent les URI de redirection.