> 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-agents.md). # Agenti IA Gli AI Agents consentono di eseguire prompt job direttamente in PowerShell Universal. Un agente combina un modello, impostazioni del provider, istruzioni, autorizzazione e AI Tools opzionali, in modo che gli utenti possano eseguire prompt ripetibili all'interno del sistema di job di PSU. Può eseguire gli agenti dall'interfaccia utente, dai workflow, dalla Management API o dal modulo PowerShell Universal. ## Creare un AI Agent ### Provider e modelli Vada su Intelligence / AI Agents e clicchi su Create AI Agent. Selezioni un provider: * Anthropic * OpenAI * Custom Quindi inserisca il nome del modello. Ad esempio: * `gpt-5.5` * `claude-sonnet-4.6` * `qwen3.6-27B` Per i modelli ospitati, fornisca una variabile con la chiave API in modo che PSU possa autenticarsi per suo conto. Per `Custom`, fornisca un URL di endpoint assoluto compatibile con OpenAI. Questo è utile per modelli locali o self-hosted. Gli endpoint personalizzati tipici includono gateway locali come vLLM o API compatibili con Ollama. ### Contesto Ogni agente può includere istruzioni utilizzate per ogni prompt. Dopo aver creato l'agente, clicchi sull'icona a forma di matita per modificare il relativo file di istruzioni in markdown. Utilizzi questo file per indicazioni stabili come: * tono e stile di scrittura * formato di output previsto * regole operative * riferimenti ai nomi degli strumenti disponibili Mantenga le istruzioni concentrate. Inserisca i dati specifici della richiesta nel prompt stesso invece di integrarli nell'agente. ### Strumenti Gli agenti possono chiamare gli [AI Tools](/powershell-universal/it/intelligence/ai-tools.md) durante l'esecuzione. Nel campo AI Tools, assegni uno o più nomi di strumenti o modelli con caratteri jolly come: * `Get Running Processes` * `ticket_*` * `weather*` * `*` Lasci il campo vuoto per disabilitare l'accesso agli strumenti per quell'agente. ### Autorizzazione Come le altre risorse PSU, gli agenti possono definire i ruoli autorizzati a eseguirli. Il chiamante deve essere autorizzato sia per l'agente sia per qualsiasi strumento che l'agente tenta di utilizzare. ## Esecuzione dei prompt Può eseguire i prompt ad hoc, nei workflow, tramite la Management API o con i cmdlet PowerShell. ### Ad hoc Clicchi sull'icona di esecuzione accanto a un agente per avviare un prompt job. Il prompt viene eseguito come un normale job PSU, quindi può esaminare la cronologia e l'output dei job dalla pagina Jobs. ### Workflow Può aggiungere passaggi AI Prompt ai workflow. I dati del passaggio precedente sono disponibili per l'agente nel parametro `PSUItem` come CliXml di PowerShell. Ad esempio, questo prompt chiede all'agente di esaminare l'input del workflow e restituire JSON: {% code overflow="wrap" %} ``` Return the top 5 processes by CPU usage as JSON. The list of all processes is available in PSUItem as CliXml. ``` {% endcode %} L'output viene quindi passato all'attività successiva del workflow come `PSUItem` per un altro passaggio prompt o `$PSUItem` per un passaggio PowerShell. ### Invoke-PSUAiAgent Utilizzi il modulo PowerShell Universal per creare, esaminare, aggiornare e invocare gli agenti. I cmdlet comuni includono: * `Get-PSUAiAgent` * `New-PSUAiAgent` * `Set-PSUAiAgent` * `Remove-PSUAiAgent` * `Invoke-PSUAiAgent` Creare un agente: {% code overflow="wrap" %} ```powershell $apiKey = Get-PSUVariable -Name 'OpenAIKey' New-PSUAiAgent -Name 'SupportAgent' ` -Description 'Summarizes incidents and drafts operator-facing responses.' ` -Provider OpenAI ` -Model 'gpt-5.5' ` -ApiKey $apiKey ` -Tool @('ticket_*', 'Get Running Processes') ` -Role @('HelpDesk', 'Operator') ``` {% endcode %} Invocare un agente e attendere la risposta finale: {% code overflow="wrap" %} ```powershell Invoke-PSUAiAgent -AiAgent 'SupportAgent' ` -Prompt 'Summarize the last deployment and call out any failures.' ` -Wait ``` {% endcode %} Passare parametri aggiuntivi al prompt job: {% code overflow="wrap" %} ```powershell Invoke-PSUAiAgent -AiAgent 'SupportAgent' ` -Prompt 'Draft a status update for the incident.' ` -Parameters @{ IncidentId = 42 Customer = 'Contoso' Severity = 'High' } ` -Wait ``` {% endcode %} Questi parametri aggiuntivi vengono serializzati come CliXml e aggiunti al contesto del prompt per l'agente. ### Management API Può anche eseguire un agente tramite la Management API all'indirizzo `/api/v1/aiagent/run`. {% code overflow="wrap" %} ```powershell Invoke-RestMethod -Method Post ` -Uri 'http://localhost:5000/api/v1/aiagent/run' ` -Headers @{ Authorization = 'Bearer ' } ` -Body (@{ agentName = 'SupportAgent' prompt = 'Summarize the deployment status for today.' } | ConvertTo-Json) ` -ContentType 'application/json' ``` {% endcode %} L'API restituisce l'ID del job creato o l'ID di esecuzione, che può utilizzare per leggere l'output del job. ## Accesso agli strumenti Gli agenti possono utilizzare gli AI Tools per interrogare i dati di PSU o eseguire azioni tramite script PowerShell approvati. L'accesso agli strumenti viene valutato in fase di esecuzione. Anche se un agente è autorizzato all'esecuzione, una chiamata a uno strumento fallirà se il chiamante non soddisfa i requisiti di autenticazione o di ruolo dello strumento. Per le esecuzioni pianificate dei workflow, il chiamante è l'account di sistema PSU, quindi le esecuzioni pianificate possono accedere a tutti gli strumenti assegnati che il sistema è autorizzato a utilizzare. --- # 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-agents.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.