> 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/it/intelligence/ai-tools.md). # AI Tools Esponga gli script PowerShell come AI Tools in PowerShell Universal per l'utilizzo da parte di AI Agents e client MCP esterni come GitHub Copilot, con autenticazione, ruoli e ambienti persistenti. Gli AI Tools permettono di esporre script PowerShell come strumenti richiamabili per AI Agents e client MCP esterni. Sono utili quando si desidera che un modello recuperi dati PSU, esegua un'azione controllata o restituisca output strutturato in un prompt. Ogni strumento può richiedere l'autenticazione, imporre ruoli, scegliere un ambiente di esecuzione e, facoltativamente, essere esposto tramite MCP. ## Creare un AI Tool Vada a **Build > AI > Tools** e selezioni **Create AI Tool**. Selezioni lo script da esporre, quindi decida se lo strumento deve essere disponibile: * Solo per gli AI Agents di PSU. * Sia per gli AI Agents che 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 avere almeno uno di tali 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 individuati 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 output prevedibile: ```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 ``` Lo esponga come strumento: ```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 ``` I cmdlet utili includono: * `Get-PSUAiTool` * `New-PSUAiTool` * `Set-PSUAiTool` * `Remove-PSUAiTool` Ad esempio, esamini gli strumenti con: ```powershell Get-PSUAiTool Get-PSUAiTool -Name 'Get Running Processes' ``` ## Eseguire strumenti in un ambiente persistente Per impostazione predefinita, ogni invocazione di un AI Tool avvia un nuovo processo PowerShell. Per gli strumenti chiamati frequentemente da un AI Agent o da un client MCP, assegni un ambiente locale con **Persistent Runspaces** abilitato per riutilizzare il processo PowerShell in esecuzione ed evitare l'avvio del processo a ogni chiamata. 1. Crei o modifichi un ambiente in **Manage > Environments > Environments**. 2. Abiliti **Persistent Runspaces** e scelga un valore appropriato per **Max Runspaces**. 3. Crei o modifichi l'AI Tool. Nella scheda **Execution**, selezioni quell'ambiente in **Run In**. È possibile assegnare l'ambiente anche nella configurazione con `-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 ``` Ogni invocazione crea comunque il proprio record del job, stato e output in **Run > Jobs**. Gli ambienti persistenti riutilizzano il processo PowerShell e mantengono lo stato intenzionale del runspace tra le chiamate, mentre l'output del job e l'annullamento rimangono isolati alla singola invocazione. L'esecuzione persistente si applica agli ambienti locali non minimal idonei. Gli ambienti con agent remoto, PowerShell remoting, container e Minimal continuano a utilizzare i loro normali percorsi di esecuzione. Il riavvio dell'ambiente o del server PSU avvia un nuovo processo persistente, quindi lo stato del runspace in memoria viene reimpostato. Utilizzi gli ambienti persistenti solo quando il riutilizzo dello stato è intenzionale e imposti il limite dei runspace in base alla concorrenza richiesta dai suoi strumenti. ## Utilizzo di uno strumento negli AI Agents All'interno di un AI Agent, assegni direttamente i nomi degli strumenti oppure utilizzi pattern con caratteri jolly come `ticket_*` o `*`. PSU rende disponibili a quell'agent solo gli strumenti corrispondenti. L'accesso basato sui ruoli viene applicato a entrambi i livelli: * L'utente deve essere autorizzato a eseguire l'agent. * L'utente deve essere autorizzato anche a eseguire lo strumento. Le esecuzioni degli strumenti avviate da un agent compaiono come job figli del job del prompt AI. Esempio di configurazione dell'agent: ```powershell Set-PSUAiAgent -Name 'SupportAgent' -Tool @('Get Running Processes', 'ticket_*') ``` ## Utilizzo di uno strumento tramite MCP Il Model Context Protocol (MCP) consente a client remoti come GitHub Copilot di individuare e chiamare 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 ha 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ò chiamare gli strumenti PSU quando VS Code è configurato per connettersi al server MCP di PSU. In questo esempio, lo strumento racchiude uno script che restituisce i processi in esecuzione: ```powershell 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: ```json "mcp": { "servers": { "PSU": { "url": "http://localhost:5000/api/v1/mcp" } } } ``` Se la connessione va a buon fine, Copilot mostra il numero di strumenti disponibili. Può 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 affinché Copilot possa scegliere lo strumento corretto senza tentativi ed errori. ## Assegnare un nome alle connessioni del server MCP PowerShell Universal identifica il proprio server MCP come `Universal.Server` per impostazione predefinita. Imposti un nome distinto per ogni ambiente affinché più connessioni MCP di PowerShell Universal siano facili da distinguere in Visual Studio Code. Configuri il nome in `appsettings.json`: ```json { "Mcp": { "ServerName": "Production PSU" } } ``` Per le distribuzioni in container o basate su variabili d'ambiente, utilizzi: ``` Mcp__ServerName=Production PSU ``` Lasci l'impostazione vuota o non specificata per mantenere il nome predefinito `Universal.Server`. ## Governare l'accesso a AI e MCP Utilizzi le impostazioni globali AI e MCP per limitare la capacità del server e per disabilitare le funzionalità AI quando non sono consentite in un ambiente. ### Limitare le richieste e i job MCP Vada a **Settings gear > Automation** per configurare: * **MCP requests per minute**: le richieste superiori alla frequenza configurata vengono rifiutate prima dell'esecuzione. * **MCP concurrent jobs**: i job MCP aggiuntivi attendono fino a quando è disponibile uno slot di esecuzione. Il valore `0` significa illimitato. I valori negativi non sono validi. Imposti entrambi i limiti in base alla capacità disponibile per PowerShell Universal e agli script esposti come strumenti MCP. ### Disabilitare le funzionalità AI Selezioni **Disable AI Features** in **Settings gear > Automation** per disabilitare le funzionalità AI per il server. Questo nasconde AI Agents, AI Tools e AI Chat nella console di amministrazione. La disabilitazione dell'AI rimuove inoltre l'endpoint MCP dalla registrazione dei nuovi endpoint e restituisce immediatamente `404 Not Found` per le richieste a `/api/v1/mcp`. Non è necessario riavviare il server. Per gli script di configurazione, utilizzi `Set-PSUSetting -DisabledFeatures` per gestire le funzionalità del prodotto disabilitate. `-Features` rimane un alias per le configurazioni esistenti. --- # 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/it/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.