The Short Answer
Actions are where an agent stops talking and starts doing, which is why they concentrate most of the risk and maintenance costs. There are four implementation methods: Standard Actions, Flow, Apex, and External Services via an external API. The choice between them isn't about capability—almost any action is possible with all of them—but about who maintains it, how quickly it can be changed, and how it’s tested.
The recommended order of choice is top-down: start with a Standard Action, move to Flow when business logic is needed, to Apex when complexity is real, and to External Services when the source of truth is outside Salesforce. Each step down the ladder adds maintenance cost and thus requires justification.
The Decision Table
| Implementation | When Suitable | Who Maintains | Cost of Option |
|---|---|---|---|
| Standard Action | Retrieve, update field, open Case, summarize record | Platform administrator | Limited flexibility for business rules |
| Flow | Changing business rules, multiple steps, validation | Admin or process owner | High-volume performance, limited error handling |
| Apex | Complex logic, massive processing, error control | Developer only | Every change requires deployment cycle and testing |
| External Services / API | Source of truth outside Salesforce | Integration team | Dependence on availability, latency, and third-party versions |
First Rule: Description Before Implementation
Before choosing a technology, write a description of the action. This might sound procedural, but it’s the element that determines whether the agent triggers the correct action. The agent doesn't read the code—they read the description and decide based on it.
A good description includes three parts: what the action does, when to use it, and explicitly when not to use it. The third part is often forgotten, and it's what prevents the agent from triggering a refund action when the customer merely inquired about refund policy.
Parameters should be minimal and of a defined type. A free-text parameter where the agent is supposed to fill in a value from a closed list is an invitation to errors; a defined picklist solves this without additional logic.
When Flow and When Apex
Flow is the default for business rules because it's visual and allows the process owner to see what’s happening. For agents, an additional advantage is the speed of correction: if it's discovered that an action doesn't check eligibility conditions, it can be fixed the same day.
Apex is justified in four situations: logic with many branches that makes Flow unreadable, processing large volumes in a single call, requiring precise control over error handling and transactions, and integration that demands complex response processing. Outside of these situations, Apex primarily increases the cost of the next change.
The choice is also related to existing technical debt. An organization already carrying thousands of lines of Apex without tests should think twice before adding another layer—the full considerations are in Flow vs. Apex.
Actions with External Systems
This is the area where failures reach the end-user. Three decisions must be made before building: what is the maximum waiting time, what does the agent say if the call fails, and is a retry allowed?
Idempotency is the crucial concept. A read operation can be safely retried. An action that creates a record, sends a message, or charges a card—retrying could lead to duplication. The solution is a unique key for each request that the receiving system recognizes, or a conscious decision to forgo retries.
Latency is an experience consideration, not just a technical one. A call taking a few seconds is acceptable in a chat channel if the agent says they are checking; a call taking longer requires an asynchronous path—the agent confirms receipt and updates when the answer arrives.
Patterns for handling integration failures are detailed in Salesforce Integration Error Handling.
Action-Level Permissions
Every Action should be restricted by a separate permission. A common mistake is to grant the agent a broad profile covering all actions, which then makes it impossible to open one action to a specific group without opening all of them.
The working principle: minimum permission for each action, validation within the action itself and not just in the instructions to the agent, and verification that the action respects the user's context. Do not rely on instructions to prevent activation—instructions are guidance, not control.
When to Split an Action
An action that does three things is difficult to test and difficult to approve. A sign for splitting: when part of the action requires human approval and part doesn't, when different parts require different permissions, or when a failure in the middle leaves the process in an inconsistent state.
Splitting slightly increases orchestration cost but pays off: each part is tested separately, the agent can pause between parts, and permissions are precise. The practical rule—one action, one judgment.
Planning the breakpoints between parts is detailed in Human-in-the-Loop in Agentforce.
Scenario: An Organization Switched from Apex Back to Flow
A service company built six Apex Actions in a pilot, assuming this would give them full control. Within two months, it became clear that four of them changed logic three times each—not due to bugs, but because business rules became clear during use. Each change required a developer, testing, and a deployment cycle of several days.
In the second round, the two actions that remained in Apex were those with multiple calls to an external system and response processing. The other four were moved to Flow, and the platform administrator took responsibility for them. The average time to repair dropped from days to hours.
The lesson wasn't that Apex is bad, but that at a stage where rules are still evolving, the cost of change is more important than the initial build cost.
Risks and Preventative Actions
| Risk | How it Manifests | Preventative Action |
|---|---|---|
| Ambiguous action description | Agent triggers the wrong action | Description with "when yes" and "when no" and defined parameters |
| Blind retry | Duplicate records or charges | Unique request key or waive retry |
| Broad agent permission | Sensitive action accessible to all users | Separate permission for each Action and validation within the action |
| All logic in Apex | Every business change becomes a development project | Flow for evolving rules, Apex for true complexity |
| Action does three things | Failure in the middle leaves an inconsistent state | Split by judgment and permission |
Metrics for Actions
| Metric | What It Reveals | Frequency |
|---|---|---|
| Action success rate | Percentage of successful executions | Weekly |
| Wrong action rate | Percentage of cases where the wrong action was chosen | Per version |
| Median action latency | Whether the experience remains reasonable | Weekly |
| Integration failure rate | Stability of target systems | Weekly |
| Mean time to repair | Does the chosen implementation allow rapid change | Monthly |
When guidance is needed in planning the Actions layer and adapting it to the existing architecture, the Agentforce and AI Service is the practical next step.
Checklist for Each Action
- ☐ Description written with "what," "when yes," and "when no"
- ☐ Parameters are minimal and of a defined type
- ☐ The highest sufficient implementation method was chosen
- ☐ A separate permission was defined for the action
- ☐ Validation resides within the action, not just in instructions
- ☐ It was determined whether the action is idempotent and what the retry policy is
- ☐ Maximum waiting time and user failure message were defined
- ☐ Multi-judgment actions were split
- ☐ A test scenario exists for failure, not just success