> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/fr/intelligence/ai-tools.md). # Outils IA Exposez des scripts PowerShell en tant qu'outils IA dans PowerShell Universal pour les utiliser avec des agents IA et des clients MCP externes comme GitHub Copilot, avec authentification, rôles et env Les outils IA vous permettent d'exposer des scripts PowerShell comme des outils appelables par des agents IA et des clients MCP externes. Ils sont utiles lorsque vous voulez qu'un modèle récupère des données PSU, exécute une action contrôlée ou retourne une sortie structurée dans une invite. Chaque outil peut exiger une authentification, appliquer des rôles, choisir un environnement d'exécution et, facultativement, être exposé via MCP. ## Créer un outil IA Naviguez vers **Build > AI > Tools** et sélectionnez **Create AI Tool**. Sélectionnez le script à exposer, puis décidez si l'outil doit être disponible : * Uniquement pour les agents IA de PSU. * Pour les agents IA et les clients MCP en activant **MCP**. Si **Authenticated** est activé, l'appelant doit être connecté. Si des rôles sont également attribués, l'appelant doit posséder au moins un de ces rôles. ### Description La description est l'une des parties les plus importantes de l'outil. Elle doit indiquer au modèle : * Quand utiliser l'outil. * Ce que l'outil retourne. * Si l'outil modifie l'état. * Toute attente importante concernant les paramètres. Les descriptions courtes et concrètes fonctionnent le mieux. ### Paramètres Les paramètres sont découverts automatiquement à partir du script PowerShell. L'aide basée sur les commentaires est fortement recommandée, car PSU l'utilise pour créer de meilleures descriptions d'outils et de meilleurs schémas de paramètres. Cet exemple de script constitue un bon outil IA parce qu'il a des paramètres clairs et une sortie prévisible : ```powershell <# .SYNOPSIS Returns the top running processes by CPU usage. .PARAMETER Count The number of processes to return. #> param( [Parameter()] [int]$Count = 5 ) Get-Process | Sort-Object CPU -Descending | Select-Object -First $Count Name, Id, CPU ``` Exposez-le en tant qu'outil : ```powershell New-PSUAiTool -Name 'Get Running Processes' ` -Description 'Returns the top running processes by CPU usage.' ` -ScriptFullPath '/tools/Get-RunningProcesses.ps1' ` -Authenticated ` -Role @('Operator') ` -Mcp ``` Les applets de commande utiles comprennent : * `Get-PSUAiTool` * `New-PSUAiTool` * `Set-PSUAiTool` * `Remove-PSUAiTool` Par exemple, passez les outils en revue avec : ```powershell Get-PSUAiTool Get-PSUAiTool -Name 'Get Running Processes' ``` ## Exécuter les outils dans un environnement persistant Par défaut, chaque invocation d'un outil IA démarre un nouveau processus PowerShell. Pour les outils appelés fréquemment par un agent IA ou un client MCP, attribuez un environnement local avec **Persistent Runspaces** activé afin de réutiliser le processus PowerShell en cours d'exécution et d'éviter le démarrage d'un processus à chaque appel. 1. Créez ou modifiez un environnement sous **Manage > Environments > Environments**. 2. Activez **Persistent Runspaces** et choisissez une valeur appropriée pour **Max Runspaces**. 3. Créez ou modifiez l'outil IA. Dans l'onglet **Execution**, sélectionnez cet environnement dans **Run In**. Vous pouvez également attribuer l'environnement dans la configuration avec `-Environment` : ```powershell New-PSUAiTool -Name 'Get Running Processes' ` -Description 'Returns the top running processes by CPU usage.' ` -ScriptFullPath '/tools/Get-Running-Processes.ps1' ` -Environment 'Persistent Tools' ` -Mcp ``` Chaque invocation crée toujours son propre enregistrement de tâche, son propre statut et sa propre sortie dans **Run > Jobs**. Les environnements persistants réutilisent le processus PowerShell et conservent l'état intentionnel du runspace entre les appels, tandis que la sortie des tâches et l'annulation demeurent isolées à l'invocation individuelle. L'exécution persistante s'applique aux environnements locaux non minimaux admissibles. Les environnements d'agent distant, de communication à distance PowerShell, de conteneur et Minimal continuent d'utiliser leurs chemins d'exécution normaux. Le redémarrage de l'environnement ou du serveur PSU démarre un nouveau processus persistant, de sorte que l'état du runspace en mémoire est réinitialisé. N'utilisez les environnements persistants que lorsque la réutilisation de l'état est intentionnelle, et fixez la limite de runspaces selon la concurrence dont vos outils ont besoin. ## Utiliser un outil dans les agents IA Dans un agent IA, attribuez les noms d'outils directement ou utilisez des modèles avec caractères génériques comme `ticket_*` ou `*`. PSU rend uniquement les outils correspondants disponibles pour cet agent. L'accès basé sur les rôles est appliqué aux deux niveaux : * L'utilisateur doit être autorisé à exécuter l'agent. * L'utilisateur doit également être autorisé à exécuter l'outil. Les exécutions d'outils lancées par un agent apparaissent comme des tâches enfants de la tâche d'invite IA. Exemple de configuration d'agent : ```powershell Set-PSUAiAgent -Name 'SupportAgent' -Tool @('Get Running Processes', 'ticket_*') ``` ## Utiliser un outil via MCP Le protocole Model Context Protocol (MCP) permet à des clients distants comme GitHub Copilot de découvrir et d'appeler vos outils. PSU expose MCP à `/api/v1/mcp`. Seuls les outils dont **MCP** est activé sont répertoriés pour les clients MCP. Lorsqu'ils sont exposés via MCP, les noms d'outils sont normalisés pour le client. Par exemple, les espaces et les points sont convertis en traits de soulignement. Lorsqu'un client MCP se connecte, PSU filtre les outils visibles selon : * Si l'outil est marqué pour MCP. * Si l'appelant est authentifié lorsque cela est requis. * Si l'appelant possède au moins un rôle requis. Les appels effectués par MCP apparaissent comme des tâches MCP dans la page Jobs. Si votre client prend en charge les jetons du porteur, fournissez un jeton d'application PSU lors de la connexion au terminal MCP. ## Accès dans GitHub Copilot GitHub Copilot peut appeler des outils PSU lorsque VS Code est configuré pour se connecter au serveur MCP de PSU. Dans cet exemple, l'outil encapsule un script qui retourne les processus en cours d'exécution : ```powershell Get-Process | Select-Object Name, Id ``` Avec l'extension MCP activée, appuyez sur `Ctrl+Shift+P` et exécutez `MCP: Add Server...`. Choisissez l'option HTTP et entrez l'URL du terminal MCP. Par défaut, il s'agit de `http://localhost:5000/api/v1/mcp`. Le contenu du fichier `settings.json` résultant ressemblera à ceci : ```json "mcp": { "servers": { "PSU": { "url": "http://localhost:5000/api/v1/mcp" } } } ``` Si la connexion est réussie, Copilot affiche le nombre d'outils disponibles. Vous pouvez ensuite demander à Copilot d'utiliser l'outil PSU. Par exemple : ``` Use the PSU tool to list the top 5 processes and create a PowerShell script that writes them to JSON. ``` Si vous exposez également un outil qui démarre un processus, une invite comme celle-ci peut déclencher cette action : ``` Use the PSU tool to start a new process named calc. ``` Gardez les descriptions d'outils et l'aide sur les paramètres claires afin que Copilot puisse choisir le bon outil sans essais et erreurs. ## Nommer les connexions au serveur MCP PowerShell Universal identifie son serveur MCP comme `Universal.Server` par défaut. Attribuez un nom distinct à chaque environnement afin que plusieurs connexions MCP de PowerShell Universal soient faciles à distinguer dans Visual Studio Code. Configurez le nom dans `appsettings.json` : ```json { "Mcp": { "ServerName": "Production PSU" } } ``` Pour les déploiements conteneurisés ou basés sur des variables d'environnement, utilisez : ``` Mcp__ServerName=Production PSU ``` Laissez le paramètre vide ou non spécifié pour conserver le nom `Universal.Server` par défaut. ## Encadrer l'accès à l'IA et à MCP Utilisez les paramètres globaux d'IA et de MCP pour limiter la capacité du serveur et pour désactiver les capacités d'IA lorsqu'elles ne sont pas permises dans un environnement. ### Limiter les requêtes et les tâches MCP Allez à **Settings gear > Automation** pour configurer : * **MCP requests per minute** : les requêtes dépassant le taux configuré sont rejetées avant l'exécution. * **MCP concurrent jobs** : les tâches MCP supplémentaires attendent qu'une plage d'exécution soit disponible. Une valeur de `0` signifie illimité. Les valeurs négatives ne sont pas valides. Fixez les deux limites en fonction de la capacité disponible pour PowerShell Universal et des scripts exposés comme outils MCP. ### Désactiver les fonctionnalités d'IA Sélectionnez **Disable AI Features** sous **Settings gear > Automation** pour désactiver les capacités d'IA du serveur. Cela masque AI Agents, AI Tools et AI Chat dans la console d'administration. La désactivation de l'IA retire également le terminal MCP de l'enregistrement des nouveaux terminaux et retourne immédiatement `404 Not Found` pour les requêtes vers `/api/v1/mcp`. Un redémarrage du serveur n'est pas requis. Pour les scripts de configuration, utilisez `Set-PSUSetting -DisabledFeatures` pour gérer les fonctionnalités de produit désactivées. `-Features` demeure un alias pour les configurations existantes. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.devolutions.net/powershell-universal/fr/intelligence/ai-tools.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.