---
isPublished: true
template: "page.peb"
title: "Run Agent Action (AI) Flow Reference"
displayName: "Run Agent Flow Action"
description: "Configure the iDialogue Run Agent Action in Salesforce Flow, including inputs, outputs, execution modes, record and file context, dialogue continuation, and recovery."
category: "resources"
contentType: "reference"
audience: "admin,developer"
tags: "coding-agents,salesforce,flow,run-agent,background,chat,files,dialogue"
section: "resources"
seoTitle: "Run Agent Action (AI) Salesforce Flow Reference"
seoDescription: "Reference every Run Agent Action input and output, Chat and Background behavior, file mappings, dialogue continuation, acknowledgements, and errors."
---

# Run Agent Action (AI) Flow Reference

Use **Run Agent Action (AI)** to start an iDialogue agent from Salesforce Flow. Its Apex action name is
`RunAgentAction`.

This page documents observable Flow behavior and provides configuration examples. It does not authorize a coding
agent to connect to Salesforce, install a plugin, activate a Flow, run an agent, or perform DML. The visitor controls
connections and tools, reviews the proposed operation, and authorizes any state change.

## Choose an execution mode

| Run in Background | Process File Before Running Agent | Run Context | Immediate result |
| --- | --- | --- | --- |
| `false` | blank or `false` | Chat | Returns the immediate service result; a recoverable timeout can report that work is still pending. |
| blank or `true` | blank or `false` | Background | Returns after Salesforce accepts the request for asynchronous processing. |
| blank or `true` | `true` | Background | Waits for an explicit file-processing queue acknowledgement; file preparation and the agent continue later. |
| `false` | `true` | Invalid | Returns an error because file preparation requires Background. |

Blank **Run in Background** defaults to `true`. Blank **Process File Before Running Agent** behaves as `false`.

Chat runs receive prompts and tools configured for **All** or **Chat**. Background runs receive prompts and tools
configured for **All** or **Background**. Review the full Run Context table in
[File OCR with Run Agent](/support/idp/process-salesforce-files-with-run-agent.html).

## Inputs

The action shows 11 inputs. Ten are current inputs and **Eval Agent ID** is deprecated.

| Flow label | Variable | Required and behavior |
| --- | --- | --- |
| Agent Name (Alternative to Agent ID) | `agentName` | Required when Agent ID is blank. Names are not unique; use Agent ID unless the intended match is verified. |
| Agent ID (Alternative to Agent Name) | `systemAgentId` | Required when Agent Name is blank. When both are present, Agent ID takes precedence. |
| Eval Agent ID (Optional) | `userAgentId` | Deprecated and not used. Leave blank. |
| User Prompt (to initiate agent) | `userPrompt` | Optional starting instruction. Blank is valid. |
| Record ID | `recordId` | Optional related business record, such as an Account or Opportunity. |
| Content Document ID | `contentDocumentId` | Optional `ContentDocument` ID for the selected Salesforce File. |
| Content Version ID | `contentVersionId` | Primary `ContentVersion` ID. Required when file preparation is enabled. |
| Supporting Content Version ID | `supportingContentVersionId` | Optional distinct second `ContentVersion` ID for a two-file run. |
| Dialogue ID (Optional - Resume Existing) | `dialogueId` | Leave blank to start a dialogue, or supply an existing ID to continue it. |
| Run in Background (Default=True) | `runAsync` | Blank or `true` selects Background; `false` selects Chat. |
| Process File Before Running Agent | `processFileBeforeRunning` | Set `true` to prepare the referenced file before the Background agent starts. |

Use a valid primary `ContentVersion` ID. A supporting ID must also identify a `ContentVersion` and must differ from
the primary ID.

## Outputs

| Flow label | Variable | Meaning |
| --- | --- | --- |
| Success | `success` | Whether the immediate action step succeeded. It does not always mean the agent finished. |
| Error Message | `message` | Error details on failure; on success it can contain an acknowledgement or Chat completion. |
| Dialogue ID | `dialogueId` | The started or resumed dialogue when available. Ordinary Background immediate output is blank, even when the request supplied an ID. |

Branch on **Success** before interpreting **Error Message**. Do not assume that a nonblank message is an error.

## Understand acknowledgement and completion

- Ordinary Background success means Salesforce accepted asynchronous work. It is not an iDialogue queue receipt or
  proof that the agent completed.
- File-preparation success means iDialogue acknowledged the queued file request. OCR, agent execution, and record
  changes still happen later.
- Chat success is the immediate foreground result. Verify any durable business effect separately.
- A pending Chat response is not a terminal completion, and this Flow action exposes no polling outputs. Verify the
  eventual business result before retrying.
- A blank Dialogue ID starts a new dialogue. A supplied Dialogue ID continues the existing dialogue context.
- An acknowledgement does not prove that an agent changed a record, created a file, or completed another side effect.

Only configure tools and record permissions that the workflow needs. The customer decides whether an agent may read or
change Salesforce data. Test consequential actions with safe records and review the resulting records or files.

## Mapping examples

### 1. Start a record-based Background agent

| Input | Example Flow value |
| --- | --- |
| Agent Name | Exact configured agent name |
| Record ID | `$Record.Id` |
| User Prompt | A short, bounded assignment |
| Dialogue ID | Blank |
| Run in Background | `true` |
| Process File Before Running Agent | `false` or blank |

The immediate success response only confirms asynchronous acceptance. The
[Email Assistant for Salesforce](/support/agents/email-assistant-salesforce.html) uses this pattern.
Because names are not unique, prefer **Agent ID** when uniqueness has not been verified, especially for an agent that
can change data.

### 2. Request a direct Chat response

| Input | Example Flow value |
| --- | --- |
| Agent ID | Selected `rooms__AIModel__c` record ID |
| Record ID | Current business record ID |
| User Prompt | The instruction whose response the Flow needs now |
| Dialogue ID | Blank for new, or an existing dialogue ID |
| Run in Background | `false` |
| Process File Before Running Agent | `false` or blank |

Use this mode only when the Flow needs the immediate response and the work fits a foreground transaction.

### 3. Prepare one Salesforce File

| Input | iDialogue Event value |
| --- | --- |
| Record ID | `rooms__RelatedRecordID__c` |
| Content Document ID | `rooms__ContentDocumentID__c` |
| Content Version ID | `rooms__ContentVersionID__c` |
| Dialogue ID | Blank to start a new Background dialogue |
| Run in Background | `true` |
| Process File Before Running Agent | `true` |

Do not map `rooms__RecordId__c` to **Record ID** for a Content Version event; that event field contains the file version
ID. Keep the related business record separate from the file IDs. Do not put file content in **User Prompt**. Follow the
complete [Salesforce file-processing procedure](/support/idp/process-salesforce-files-with-run-agent.html) for trigger
selection, permissions, monitoring, and verification.

For a two-version Image Scanner Flow, the separate `IMAGE_SCAN_SUBMITTED` event supplies the primary and supporting
Content Version IDs. Map its related business record separately, require two distinct versions, and use the same
Background-plus-file settings. Do not treat `CONTENT_VERSION_INSERT` as a two-version scanner event.

## Visible failures and recovery

| Visible message or condition | Recovery |
| --- | --- |
| `Either Agent ID or Agent Name must be provided.` | Map one agent selector. |
| `Agent with name "..." not found.` | Check the exact connected-org agent name or use its ID. |
| `Process File Before Running Agent requires Run in Background.` | Set Run in Background to `true`. |
| `Process File Before Running Agent requires a Content Version ID.` | Map the primary `ContentVersion` ID. |
| Supporting ID is invalid or matches the primary ID. | Map a different valid supporting `ContentVersion` ID. |
| `Agent does not define a backgroundModel.` | Configure the selected agent's Background Model before retrying. |
| `Deferred file processing did not receive a queue acknowledgement.` | Review the Flow inputs, agent configuration, connection, and iDialogue Events. |
| `Run Agent file request could not be started. Review iDialogue Events.` | Open iDialogue Events and use the reference ID for support. |
| `(No response from API. See iDialogue event logs.)` | Review iDialogue Events and verify the expected business result before retrying. |

Ordinary Background failures can occur after the Flow has received its acceptance response. Verify the expected outcome.
Connect and test the Flow element's **Fault** path as well: invalid IDs, transaction failures, and asynchronous-limit
failures can fault the Apex action before these outputs are returned.
For file mode, an error can create an iDialogue Event with available agent, record, file, and reference IDs. The event
does not contain file content or extracted text. The absence of an error event does not prove completion. Verify the
expected dialogue, record update, file, message, or other business outcome before marking work complete or retrying.