---
isPublished: true
knowledgeIndex: false
hidden: true
noindex: true
template: "page.peb"
title: "Run Agent Action (AI) Flow Reference"
description: "Inputs, outputs, transaction effects and troubleshooting for Run Agent Action (AI) in Salesforce Flow."
contentType: "reference"
audience: "admin,developer"
---

# Run Agent Action (AI)

Start an DialogueOne agent with record, File or dialogue context.
The namespaced Apex action name is `rooms__RunAgentAction`.

## Transaction summary

| Effect | Behavior |
| --- | --- |
| API callout | Conditional. Chat and file-preparation requests make a direct callout. Ordinary Background mode makes the callout later. |
| Record writes | A new dialogue can create or update a Dialogue record after a callout. Errors can create DialogueOne Event records. Enabled tools can make additional record changes. |
| Background work | Ordinary Background mode schedules asynchronous execution. File-preparation mode requests deferred file work. |
| Platform event | The action does not directly publish a platform event. |
| Email | The action does not directly send email. Approved enabled tools can send email. |

Blank Run in Background defaults to `true`. Ordinary Background Success means Salesforce accepted the asynchronous request. It does not confirm agent completion and normally returns no Dialogue ID.

Set Run in Background to `false` for Chat when the Flow needs the immediate response. With file preparation enabled, keep Background enabled and supply an exact Content Version ID. The immediate file result confirms only that the request was acknowledged.

A blank Dialogue ID starts a dialogue. An existing Dialogue ID resumes it. Prefer Agent ID when agent names are not unique. Eval Agent ID is deprecated and is not used.

See the existing [Run Agent guide and examples](/content/build/flows/run-agent.md).

```mermaid
flowchart TD
    A[Select agent and context] --> B{Run in Background?}
    B -- No --> C[Callout and immediate Chat result]
    B -- Yes --> D{Prepare File first?}
    D -- No --> E[Queue work and return acceptance]
    D -- Yes --> F[Callout and file-request acknowledgement]
    C --> G[Check result and business effects]
    E --> G
    F --> G
```

## Inputs

Required describes the Flow input setting. Additional conditions are stated in the guidance.

| API name | Flow label | Required | Default or guidance |
| --- | --- | --- | --- |
| `agentName` | Agent Name (Alternative to Agent ID) | No | Alternative to Agent ID. Verify the intended match because names are not unique. |
| `systemAgentId` | Agent ID (Alternative to Agent Name) | No | The configured AI Agent record ID. Takes precedence over Agent Name. |
| `userAgentId` | Eval Agent ID (Optional) | No | Deprecated. Leave blank. |
| `userPrompt` | User Prompt (to initiate agent) | No | The starting instruction for the selected agent. |
| `recordId` | Record ID | No | Optional source-record context. |
| `contentDocumentId` | Content Document ID | No | Optional Salesforce File ID. |
| `contentVersionId` | Content Version ID | No | The primary File version. Required when file preparation is enabled. |
| `supportingContentVersionId` | Supporting Content Version ID | No | Optional distinct supporting File version. |
| `dialogueId` | Dialogue ID (Optional - Resume Existing) | No | Blank starts a new dialogue. Supply an existing identifier to resume. |
| `runAsync` | Run in Background (Default=True) | No | Defaults to `true` when blank. `false` selects Chat. |
| `processFileBeforeRunning` | Process File Before Running Agent | No | Blank behaves as disabled. Requires Background and a primary File version when enabled. |

## Outputs

| API name | Flow label | Meaning |
| --- | --- | --- |
| `success` | Success | Whether the immediate action step was accepted or succeeded. Background acceptance is not completion. |
| `message` | Error Message | Error details, an acknowledgement or a Chat response. Read it with Success and the mode. |
| `dialogueId` | Dialogue ID | The dialogue identifier when available. Ordinary Background immediate output is blank. |

## Configure the Flow

1. Select the agent by Agent ID or a verified name.
2. Set the permitted record, File or dialogue context.
3. Select Chat or Background deliberately.
4. For file preparation, set Process File Before Running Agent and keep Background enabled.
5. Store Success, Error Message and Dialogue ID when returned.
6. Check the eventual business result before repeating a request that can change records.

Confirm the Flow user's action access and the required access to the referenced records.
Review the configured Salesforce API connection user's access when the action makes a callout.
Connect the action's Fault path.

## Troubleshooting

**You have uncommitted work pending.** Check earlier record writes, queued work and other actions in the same transaction.
Review the [transaction settings and debugger limits](/content/build/flows/index.md#resolve-uncommitted-work-pending).

**Process File Before Running Agent fails.** Background must be enabled and Content Version ID must identify the primary File version. A supporting version must be distinct.

**Success is true but work is unfinished.** Ordinary Background Success confirms acceptance only. Inspect the eventual record, File or dialogue result.

**A later callout fails.** This action can enqueue work, save a Dialogue or record an Event. Review the later transaction boundary.

**The agent was repeated after a timeout.** Verify existing business results before starting a new dialogue or run.

Confirm that the action and its fields exist in the installed package.
See the [Flow action index](/content/build/flows/index.md) for related actions and transaction guidance.
