> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# runAgent

> Reference for the runAgent workflow task, which invokes an agent as a step in a workflow.

On Itential Platform Cloud, the Run Agent task is available on the Scale and Enterprise tiers, where Studio is included.

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](#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](/itential-platform/flowai/agent-projects/agent-builder).

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.

## Related information

* [Agent Sessions](/itential-platform/flowai/agent-sessions)
* [Create and run agents](/itential-platform/flowai/agent-projects/agent-builder)