> 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). # 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: ```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 ``` Tra i cmdlet utili: * `Get-PSUAiTool` * `New-PSUAiTool` * `Set-PSUAiTool` * `Remove-PSUAiTool` Ad esempio, per esaminare gli strumenti: ```powershell 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: ```powershell 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: ```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 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. --- # 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.