Outils IA

Appelez des scripts PowerShell dans des agents IA et via MCP.

Les outils IA vous permettent d'exposer des scripts PowerShell en tant qu'outils appelables par des agents IA et des clients MCP externes. Ils sont utiles lorsque vous souhaitez 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 et être optionnellement exposé via MCP.

Créer un outil IA

Accédez à Intelligence / AI Tools et cliquez sur Create AI Tool. Sélectionnez le script à exposer, puis décidez si l'outil doit être disponible :

• uniquement pour les agents IA de PSU
• à la fois 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 assignés, l'appelant doit avoir 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

Des descriptions courtes et concrètes fonctionnent 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 construire de meilleures descriptions d'outils et des schémas de paramètres.

Cet exemple de script constitue un bon outil IA car il a des paramètres clairs et une sortie prévisible :

<#
.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

L'exposer en tant qu'outil :

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 cmdlets utiles incluent :

• Get-PSUAiTool
• New-PSUAiTool
• Set-PSUAiTool
• Remove-PSUAiTool

Par exemple, pour consulter les outils :

Get-PSUAiTool
Get-PSUAiTool -Name 'Get Running Processes'

Utiliser un outil dans des agents IA

Dans un agent IA, assignez des noms d'outils directement ou utilisez des motifs génériques tels que ticket_* ou *. PSU ne met à disposition de l'agent que les outils correspondants.

Le contrôle d'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 démarrées par un agent apparaissent en tant que tâches enfants de la tâche d'invite IA.

Exemple de configuration d'agent :

Set-PSUAiAgent -Name 'SupportAgent' -Tool @('Get Running Processes', 'ticket_*')

Utiliser un outil via MCP

Le Model Context Protocol (MCP) permet aux clients distants, tels que GitHub Copilot, de découvrir et d'appeler vos outils. PSU expose MCP à /api/v1/mcp.

Seuls les outils dont Mcp est activé sont listé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 tirets bas.

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 requis
• si l'appelant possède au moins un rôle requis

Les appels effectués via MCP apparaissent en tant que tâches MCP dans la page des tâches.

Si votre client prend en charge les jetons bearer, fournissez un jeton d'application PSU lors de la connexion au point de terminaison 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 :

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 point de terminaison MCP. Par défaut, il s'agit de http://localhost:5000/api/v1/mcp.

Le contenu résultant du fichier settings.json ressemblera à ceci.

"mcp": {
    "servers": {
        "PSU": {
            "url": "http://localhost:5000/api/v1/mcp"
        }
    }
}

Si la connexion réussit, Copilot affichera 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 pour que Copilot puisse choisir le bon outil sans essai-erreur.