Async Agent Processing
What Async Means Here
REDA AI runs the agentic loop synchronously by default. The user’s message arrives, the platform calls the model, the agent uses tools, the model produces a final answer, and the conversation record is updated — all within the calling transaction. The user (or Flow, or external system) gets the reply in the response.
Some requests can’t fit in a single transaction. The most common reason is a file payload large enough to exceed Salesforce’s synchronous processing limits. When the platform detects that condition, it switches to async processing instead of failing.
What the Caller Sees
Async-routed requests return immediately with two telltale fields on the response:
| Field | Meaning |
|---|---|
isAsync | true when the request was routed to background processing. |
asyncRequestId | The Id of the Async Request record tracking the work. |
conversationId | The conversation the request belongs to. The agent’s eventual reply lands as a new Message on this conversation. |
The synchronous response field is empty when isAsync is true — the actual reply hasn’t been generated yet. Callers should branch on isAsync and either poll for completion or wait for the conversation to receive the new Message.
The Async Request Lifecycle
Each async-routed request creates an Async Request record that the platform updates as work progresses:
| Status | Meaning |
|---|---|
| Queued | The Queueable has been enqueued; processing hasn’t started yet. |
| Processing | The background processor has picked up the request and is calling the model. |
| Complete | Work finished cleanly; the reply is available on the conversation. |
| Error | Work failed even after retry. The Error Message field on the record contains the reason. |
Other fields on the record give you the full context: the related Conversation and user message, the agent definition that handled the request, the record context the request was bound to, the file IDs being processed, the retry counters, and a timestamp for when the work finished.
Failure handling
A failed async request is not retried. When the background processor hits an error, it writes Error to the Async Request’s Status and the reason to Error Message, and stops there. Nothing re-queues it — not a transient model error, not an interrupted callout.
Build your own retry if the work matters. A Flow that calls an agent asynchronously and
treats delivery as guaranteed will lose the turn on any transient failure. Check the Async Request’s
Status, and re-invoke on Error.
The record carries Retry Count and Max Retries fields. Retry Count is incremented once when the request is picked up, but no code compares it to Max Retries, so neither field currently changes what happens.
Errors are still visible: unless the caller turned incident logging off, the failure is captured in the AI Incident Logs with its class, method and stack trace, which is where to look first.
How Channels Handle Async
Internal Salesforce UI (chat widget on a record page)
The chat widget detects isAsync and shows a friendly waiting state. When the conversation receives the new agent message, the widget updates in place. Users see a brief delay; the conversation is otherwise unchanged.
External Widget
The external widget on a public website detects isAsync and shows a similar waiting state. Because the widget is polling rather than streaming, the user sees the reply land within a few seconds of completion.
Flow / API callers
For Flow-driven and direct-API callers, async needs explicit handling. The simplest pattern is a record-triggered Flow on the Async Request object: when the record reaches Complete, fire whatever follow-up the integration needs — post the reply back to a messaging system, update a record, send an email. See Messaging Channel Integration for the broader pattern.
Email Channel — Inbound
Inbound document-intake emails always run asynchronously by design. The Email Service handler stores attachments and enqueues a Queueable; the agent runs in the background. See Email Channel — Inbound.
Observability
- The async request record is the primary source of truth: status, retry count, error message, completion timestamp.
- The conversation shows the user’s message immediately and the agent’s response when the async work completes — no “in-progress” messages.
- The Conversation Debugger shows the assembled prompt, tool calls and credits used for the eventual agent run, identical to a sync run.
- The Incident Log captures any failure that exhausts the retry budget. See AI Incident Logs.
Designing Agents for Async
Most agents don’t need any special design for async — the routing is automatic and the conversation behaves the same. There are two design considerations worth thinking about:
Token budget. The async path runs in a Queueable, which has its own governor limits. Very long agentic loops or oversized prompts can still hit limits in async mode. Keep the agent’s token budget realistic, and split very long-running work across multiple turns where possible.
Confirmation cards. Action confirmations require a UI that can render a card. On async-only channels (email intake, Flow-driven runs, messaging integrations), enable Auto Execute Actions on the agent or constrain the toolset to non-confirmable tools. See Action Confirmation.
Best Practices
Branch on isAsync in custom callers. Treating the response as synchronous when isAsync is true will leave callers waiting for a reply that never arrives in that response.
Use a record-triggered Flow on the Async Request object for follow-ups. It’s the cleanest way to react when an async run completes — firing a callback, posting a reply through another channel, or updating a status field.
Don’t expect retries to fix every failure. Most async failures are not transient. If a request lands in Error, the Incident Log entry is the right place to start investigating — long retry chains rarely turn a real failure into a success.
Monitor the queue depth. A backlog of Queued records means async work is arriving faster than it can be processed. Adjust agent design (slimmer tool sets, smaller token budgets) before increasing concurrency.
Automation and reliability
Bulk Flow invocations can return deferred request IDs instead of immediate answers. Review downstream Flow elements that expect response, credits or action-result output in the same transaction. Automated action handling carries the configured channel and execution mode, and retains actual outcomes in conversation context; this does not guarantee an extra narrated turn. Explicit datetime offsets are preserved in supported event, scheduled-action, field-write and CSV paths. Offset-free values retain the running user's interpretation. Routine System-mode processing no longer raises warning incidents merely because it uses that mode; ERROR-level notifications and incident logs remain. File extraction respects the configured output limit, semantic status colours work across the supported Salesforce themes, and packaged tests avoid static Account record-type references that blocked installation in orgs without those record types.
Frequently Asked Questions
The most common trigger is a file payload too large to fit inside Salesforce’s synchronous processing limits. The platform detects the condition before calling the model and routes the request to a background job instead.
Async routing is decided by the platform based on the request’s shape, not toggled by the caller. To structure work as async by design — e.g. a Flow-driven background run with no user waiting on the response — route through the Flow invocable and let the platform decide whether to run inline or hand off.
The model call itself costs the same; async is just where the work runs. The only credit difference comes from retries on failure — each retry that calls the model again consumes credits in the normal way.
The chat widget shows a waiting state while the async request is in flight. For non-interactive channels, design the integration to surface the status — for messaging integrations a typing indicator, for email a holding reply, for Flow callers a status field on the parent record.
The async request lands in Error with the error message captured. An Incident Log record is also created. The conversation contains the user’s message but no agent reply — integrations should detect the Error status and either retry the user or surface the failure cleanly.
Yes. The async path runs the same agentic loop as the sync path; tools execute the same way. Note that confirmation cards require a UI to render; on async-only channels, configure the agent for Auto Execute Actions or restrict the toolset to read tools and non-confirmable actions.
In the Conversation Debugger for that conversation. The Debugger shows the prompt assembly, every tool call, the model’s replies and the credits consumed — identical to inspecting a sync run.
Next Steps
Read Messaging Channel Integration for an end-to-end pattern that uses async processing, or Invoking REDA AI from Flows for the Flow caller’s side of the contract.