Invoke-PSUAiAgent

Invokes a PowerShell Universal AI agent.

SYNOPSIS

Invokes a PowerShell Universal AI agent.

SYNTAX

Invoke-PSUAiAgent [-AiAgent] <Object> [-Prompt] <String> [-Parameters <Hashtable>] [-ComputerName <String>]
 [-AppToken <String>] [-Credential <PSCredential>] [-UseDefaultCredentials] [-Integrated] [-TrustCertificate]
 [-Cookies] [-Wait] [-WaitTimeout <Int32>] [<CommonParameters>]

DESCRIPTION

Starts a prompt job for an AI agent and returns the created job. The AiAgent parameter accepts either the name of an AI agent or an AI agent object from Get-PSUAiAgent. Additional values supplied through Parameters are serialized and passed to the agent job as supplemental parameters. PowerShell Universal still enforces execute permission and any roles assigned directly to the target AI agent.

EXAMPLES

Example 1

PS C:\> Invoke-PSUAiAgent -AiAgent SupportAgent -Prompt "Summarize the deployment status."

Starts a prompt job for the SupportAgent AI agent.

Example 2

PS C:\> Get-PSUAiAgent -Name SupportAgent | Invoke-PSUAiAgent -Prompt "Draft a response for the ticket." -Parameters @{ TicketId = 42; Customer = 'Contoso' }

Invokes the piped AI agent object and passes additional job parameters that the agent can use when building its response.

Example 3

PS C:\> Invoke-PSUAiAgent -AiAgent SupportAgent -Prompt "Summarize the deployment status." -Wait

Starts a prompt job for the SupportAgent AI agent and waits for it to complete, returning the agent's response instead of the job object.

Example 4

PS C:\> Invoke-PSUAiAgent -AiAgent SupportAgent -Prompt "Summarize the deployment status." -Wait -WaitTimeout 60

Waits up to 60 seconds for the agent job to complete. Throws a timeout exception if the job does not finish within the allotted time.

PARAMETERS

-AiAgent

Specifies the AI agent to invoke. You can pass the AI agent name directly or pipe an AI agent object returned by Get-PSUAiAgent.

Type: Object
Parameter Sets: (All)
Aliases: Name

Required: True
Position: 0
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

-Prompt

Specifies the prompt to send to the AI agent.

Type: String
Parameter Sets: (All)
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Parameters

Specifies additional user-defined parameters to pass to the AI agent job. Each key becomes a job parameter and each value is serialized as PowerShell CliXml before execution.

Type: Hashtable
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ComputerName

The HTTP address of the PSU Management API server.

Type: String
Parameter Sets: (All)
Aliases: Uri

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-AppToken

An app token to access the PSU Management API.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Credential

Specifies the credential used when authenticating to the PSU Management API.

Type: PSCredential
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-UseDefaultCredentials

Uses the current Windows identity when authenticating to the PSU Management API.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Integrated

Executes the command internally rather than using the Management API. This only works when running inside PowerShell Universal.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-TrustCertificate

Disables TLS certificate validation for Management API requests.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Cookies

Uses the current PSU cookie container for authentication.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Wait

Waits for the AI agent job to complete and returns its output rather than the job object. When specified, the command will block until the job finishes or the timeout is reached.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-WaitTimeout

Specifies the maximum number of seconds to wait for the job to complete when using -Wait. If the timeout is reached, the command throws a timeout exception.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False

INPUTS

System.Object

You can pipe an AI agent object from Get-PSUAiAgent or pass an agent name string.

OUTPUTS

PowerShellUniversal.Job

Returns the prompt job created for the AI agent invocation.

NOTES

Additional connection parameters are inherited from GrpcCommand.