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 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:

Return the top 5 processes by CPU usage as JSON.
The list of all processes is available in PSUItem as CliXml.

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:

$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')

Invocare un agente e attendere la risposta finale:

Invoke-PSUAiAgent -AiAgent 'SupportAgent' `
	-Prompt 'Summarize the last deployment and call out any failures.' `
	-Wait

Passare parametri aggiuntivi al prompt job:

Invoke-PSUAiAgent -AiAgent 'SupportAgent' `
	-Prompt 'Draft a status update for the incident.' `
	-Parameters @{
		IncidentId = 42
		Customer   = 'Contoso'
		Severity   = 'High'
	} `
	-Wait

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.

Invoke-RestMethod -Method Post `
	-Uri 'http://localhost:5000/api/v1/aiagent/run' `
	-Headers @{ Authorization = 'Bearer <app-token>' } `
	-Body (@{
		agentName = 'SupportAgent'
		prompt    = 'Summarize the deployment status for today.'
	} | ConvertTo-Json) `
	-ContentType 'application/json'

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.