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.
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 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 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.