Strumenti IA

Gli AI Tools consentono di esporre script PowerShell come strumenti richiamabili per gli AI Agents e per i client MCP esterni. Sono utili quando si desidera che un modello recuperi dati PSU, esegua un'azione controllata o restituisca un output strutturato in un prompt.

Ogni strumento può richiedere l'autenticazione, applicare ruoli ed essere facoltativamente esposto tramite MCP.

Creare un AI Tool

Vada a Intelligence / AI Tools e faccia clic su Create AI Tool. Selezioni lo script da esporre, quindi decida se lo strumento debba essere disponibile:

• solo per gli AI Agents di PSU
• sia per gli AI Agents sia per i client MCP abilitando MCP

Se Authenticated è abilitato, il chiamante deve aver effettuato l'accesso. Se sono assegnati anche dei ruoli, il chiamante deve possedere almeno uno di questi ruoli.

Descrizione

La descrizione è una delle parti più importanti dello strumento. Dovrebbe indicare al modello:

• quando utilizzare lo strumento
• cosa restituisce lo strumento
• se lo strumento modifica lo stato
• eventuali aspettative importanti sui parametri

Le descrizioni brevi e concrete funzionano meglio.

Parametri

I parametri vengono rilevati automaticamente dallo script PowerShell. La guida basata sui commenti è fortemente consigliata perché PSU la utilizza per creare descrizioni degli strumenti e schemi dei parametri migliori.

Questo script di esempio è un buon AI Tool perché ha parametri chiari e un output prevedibile:

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

Lo esponga come strumento:

New-PSUAiTool -Name 'Get Running Processes' `
    -Description 'Returns the top running processes by CPU usage.' `
    -ScriptFullPath '/tools/Get-RunningProcesses.ps1' `
    -Authenticated `
    -Role @('Operator') `
    -Mcp

Tra i cmdlet utili:

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

Ad esempio, per esaminare gli strumenti:

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

Utilizzare uno strumento negli AI Agents

All'interno di un AI Agent, assegni direttamente i nomi degli strumenti oppure utilizzi modelli con caratteri jolly come ticket_* o *. PSU rende disponibili a quell'agente solo gli strumenti corrispondenti.

L'accesso basato sui ruoli viene applicato a entrambi i livelli:

• l'utente deve essere autorizzato a eseguire l'agente
• l'utente deve essere autorizzato anche a eseguire lo strumento

Le esecuzioni degli strumenti avviate da un agente compaiono come job figli del job del prompt IA.

Esempio di configurazione di un agente:

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

Utilizzare uno strumento tramite MCP

Il Model Context Protocol (MCP) consente a client remoti come GitHub Copilot di individuare e richiamare i suoi strumenti. PSU espone MCP su /api/v1/mcp.

Ai client MCP vengono elencati solo gli strumenti con Mcp abilitato.

Quando vengono esposti tramite MCP, i nomi degli strumenti vengono normalizzati per il client. Ad esempio, gli spazi e i punti vengono convertiti in trattini bassi.

Quando un client MCP si connette, PSU filtra gli strumenti visibili in base a:

• se lo strumento è contrassegnato per MCP
• se il chiamante è autenticato quando richiesto
• se il chiamante possiede almeno uno dei ruoli richiesti

Le chiamate effettuate tramite MCP compaiono come job MCP nella pagina Jobs.

Se il suo client supporta i bearer token, fornisca un token dell'app PSU durante la connessione all'endpoint MCP.

Accesso in GitHub Copilot

GitHub Copilot può richiamare gli strumenti PSU quando VS Code è configurato per connettersi al server MCP di PSU.

In questo esempio, lo strumento incapsula uno script che restituisce i processi in esecuzione:

Get-Process | Select-Object Name, Id

Con l'estensione MCP abilitata, prema Ctrl+Shift+P ed esegua MCP: Add Server....

Scelga l'opzione HTTP e inserisca l'URL dell'endpoint MCP. Per impostazione predefinita è http://localhost:5000/api/v1/mcp.

Il contenuto risultante di settings.json sarà simile a questo.

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

Se la connessione ha esito positivo, Copilot mostrerà il numero di strumenti disponibili.

Potrà quindi chiedere a Copilot di utilizzare lo strumento PSU. Ad esempio:

Use the PSU tool to list the top 5 processes and create a PowerShell script that writes them to JSON.

Se espone anche uno strumento che avvia un processo, un prompt come questo può attivare tale azione:

Use the PSU tool to start a new process named calc.

Mantenga chiare le descrizioni degli strumenti e la guida dei parametri, in modo che Copilot possa scegliere lo strumento corretto senza procedere per tentativi.