runAgent | Itential

FlowAI

The runAgent task invokes an agent from a workflow canvas. Use it to combine deterministic workflow logic with an agent’s dynamic reasoning. For example, retrieve data with standard tasks, pass it to an agent for analysis, and use the agent’s output in downstream workflow steps.

When the workflow reaches this task, it starts an agent session and waits for it to complete before continuing.

Before you begin

Before you begin, make sure you have the following:

FlowAI is enabled on your Platform instance.
You have access to at least one agent. Only agents you have access to are available for selection. For information about who can run an agent from this task, see Actor and permissions.

Task properties

Incoming

Variable	Type	Required	Description
`agent`	String	Yes	The agent to invoke. Required; the task can’t be saved without a bound agent.
`inputs`	Object	Varies	Input variables defined on the selected agent. Required inputs must be mapped before the task can be saved.

Outgoing

Variable	Type	Description
`status`	String	The terminal state of the session: `completed`, `failed`, or `canceled`.
`last_message`	String	The agent’s final inference output. Empty string if the session ended before producing a final message.

Configure the task

From the Studio canvas task library, add a Run Agent task.

Select the agent to invoke. Only agents you have access to are shown.

Map the agent’s input variables to values in the workflow. Each input can be set to a static value, a job variable, or a task output. Required inputs are clearly marked and must be mapped before you can save.

Save the task.

If the agent’s input schema changes after you save the task, Itential notifies you of the mismatch the next time you open the task configuration.

Actor and permissions

The task’s Actor, under Access Control in the task’s Advanced parameters, sets whose permissions the task uses to run the agent.

Actor	Behavior
Job Initiator	The task runs as the user who started the parent workflow. That user must have permission to run the agent, or the task fails with `Insufficient permissions to run agent: [agent name]`.
Pronghorn	The task runs as the Itential system user and skips the agent’s permission check. Use it for automated workflows that run without a specific operator identity.

For who can run an agent and how to grant access, see Create and run agents.

With the Pronghorn actor, anyone who can run the parent workflow can run the agent, regardless of the agent’s permissions.

Use the task output

Downstream tasks reference the task output using status and last_message. To have the agent return structured data, include formatting instructions in the agent’s prompt; the output appears in last_message.

Running a runAgent task in parallel over a list of inputs isn’t supported. To iterate over a list, wrap the task in a sub-workflow and loop over that sub-workflow, or pass the list as a single agent input and handle iteration inside the agent.