You are here:
Run Agent Element
Use an Agentforce agent to handle tasks dynamically in your flow. Select an existing agent or create an agent with custom instructions and actions.
Required Editions
Permissions
To use existing agents in your flows, you need the View Setup user permission. To create agents from Flow Builder, you need the Customize Application, Einstein Copilot Builder, Einstein Agent Platform Builder, or Self-Service Copilot Builder user permission. Users with the System Administrator profile can both create and use agents.
If you don't have permissions to create agents, the Create Agent button doesn't appear in the agent selection panel. You can only select existing agents.
Usage
Add a Run Agent element to your flow. In the Agent field, search for and select an active agent, or click Create Agent to build a new one.
Select an Existing Agent
To use an existing agent, search for the agent by name in the Agent field. Only active agents appear in the list. After selecting an agent, configure the agent's inputs and outputs in the property panel.
Create a New Agent
To create an agent, click Create Agent. In the New Agent window, configure the agent's basic information.
| Field | Description |
|---|---|
| Label | The name for the agent. |
| API Name | The requirement for uniqueness applies only to elements within the current flow. Two elements can have the same API name, provided they're used in different flows. An API name can include underscores and alphanumeric characters without spaces. It must begin with a letter and can’t end with an underscore. It also can’t have two consecutive underscores. |
| Description | A description of what the agent does. |
| User Access | The user record that the agent runs as. Select an existing user or have the system create a user. |
| Instructions | Instructions that describe what the agent does and guide its reasoning. |
| Actions | The actions that the agent can use. Select existing actions from the asset library or create custom actions. |
Add Actions to the Agent
The agent requires at least one action to perform tasks. Add actions before you click Create & Activate or in Agentforce Builder after you activate the agent.
To select existing actions, click Select Actions. Search for and select one or more actions from the asset library, then click Add to Agent. Available actions include knowledge actions, flows configured as invocable actions, and standard actions.
To create an action, click Create Action. In the Create Action window, configure the action.
| Field | Description |
|---|---|
| Agent Tool Label | The name for the action. |
| API Name | The requirement for uniqueness applies only to elements within the current flow. Two elements can have the same API name, provided they're used in different flows.An API name can include underscores and alphanumeric characters without spaces. It must begin with a letter and can’t end with an underscore. It also can’t have two consecutive underscores. |
| Description | The name for the action. The agent uses this information to determine how and when to use this action. |
| Reference Action Type | The type of action, such as Flow or Apex. |
| Reference Action Category | The subtype of the reference action type. Not all actions have a reference action category. |
| Reference Action | The name of the action to reference. |
For each input, add a description about what the input does. The agent uses the description to determine how to use the input when calling the action. Select Require input to execute action to make the input required.
For each output, add a description about the output returns and how to use the result in the flow. Select Filter from agent context to exclude the output from the agent’s reasoning. Select Show in conversation to include this output in the agent’s response.
Click Create & Activate to create and activate your agent.
Configure the Element
After selecting or creating an agent, configure the Run Agent element in the property panel.
| Field | Description |
|---|---|
| Label | The label for the action on the canvas and in Toolbox Manager. |
| API Name | The requirement for uniqueness applies only to elements within the current flow. Two elements can have the same API name, provided they're used in different flows.An API name can include underscores and alphanumeric characters without spaces. It must begin with a letter and can’t end with an underscore. It also can’t have two consecutive underscores. |
| Description | The description for the element. |
Set Input Values
Configure the Run Agent element's inputs in the property panel.
| Field | Description |
|---|---|
| Agent Request | A question or request to send to the agent for this flow run. The agent applies its instructions to this specific request to generate output. |
| Session ID | Optional. Use the Session ID returned by a Run Agent element that runs earlier in the flow. The agent retains its full reasoning context and memory from that conversation. If you don't provide a Session ID, the agent starts a new conversation, but you can always specify outputs from previous Run Agent elements as inputs. |
Configure Structured Output
To configure the agent to return structured data that your flow can use, define structured output fields. Each field represents a piece of information that the agent extracts or generates.
If you configure structured output, the agent returns only structured data in the Structured
Agent Response field. The Agent Response field returns null. If you don't
configure structured output, the agent returns only unstructured text in the Agent Response
field.
To configure structured output, click Configure. Configure the fields for each structured output field:
| field | Description |
|---|---|
| Field Name | Required. The unique alphanumeric name for the structured output field. The name can't contain special characters or spaces. |
| Description | A brief description used with the field name to increase large language model (LLM) accuracy. |
| Data Type | Required. The data type of the field. Valid values: String, Number, Boolean. |
| Required | Indicates that the LLM must generate a response for this output field. Requiring output rows can result in inaccurate or harmful responses by the LLM. |
Store Output Values
| Field | Description |
|---|---|
| Agent Response | The unstructured response from the agent. Returns null if structured output is configured. |
| Session ID | The ID of the conversation session that the agent response is in. |
| Structured Agent Response | The structured output from the agent. Returns null if no structured output is configured. |
Structured Output Usage
Before you configure structured output, enter a label and API name for the Run Agent element, and then save the flow.
When you configure structured output, define at least 1 structured output field before you save.
For each defined structured output field, two fields are created: one with the defined name
and a related Boolean _set field. For example, if you defined a structured output field named
summary, then a Boolean field named summary_set is also
created.
| Field | Description |
|---|---|
| True | The field was included in the structured agent response, but it had no set value. |
| False | The field wasn't included in the structured agent response. |
When a defined structured output returns null, use its related _set field
later in the flow to determine why the field is null.
Usage Notes
- Test your flow before activating to ensure the Run Agent element functions as expected.
- You can find and edit agents created in Flow Builder in Agentforce Builder at any time.
- Starting in API version 67.0, AI Agent actions are no longer available from the Action element. Use the Run Agent element to work with agents. When you open a flow with an Action element that references an AI Agent action, it automatically appears as a Run Agent element. Your original configuration is preserved.
