Agent Action
An Agent Action is one discrete capability an Agentforce agent can take during a conversation, such as running an Apex method, executing a flow, calling a prompt template, searching a Data Library, or invoking a built-in record action.
Definition
An Agent Action is one discrete capability an Agentforce agent can take during a conversation, such as running an Apex method, executing a flow, calling a prompt template, searching a Data Library, or invoking a built-in record action. Each Agent Action carries a name, a natural-language instruction that tells the Atlas Reasoning Engine when to use it, an input schema, and an output schema.
Agentforce agents do nothing on their own without actions. When a user sends a message, the reasoning engine compares the message against the instructions on every Agent Action available to the agent's active topics, picks one or more, and executes them. Actions live inside Agent Topics, which group related skills into recognizable buckets like Order Lookup, Returns, and Account Updates.
Why Agent Actions are the whole job
Where Agent Actions live in setup
Open Setup, search Agent Builder, and pick the agent you want to edit. Each agent has a Topics panel on the left. Drill into a topic and you see the list of Agent Actions attached. The same action can attach to multiple topics if the underlying capability is shared. You can also see actions in the Agent Action Library at Setup, Agent Actions, which lists every action across the org. The library is the better entry point when you want to inventory what already exists before building a duplicate. Actions you create at the org level can be reused across agents. Actions you create inline inside Agent Builder are scoped to that agent.
The five action types and when to pick each
Apex actions wrap a public invocable method, give you full code control, and run with the calling user's permissions. Flow actions wrap autolaunched or screen flows for admins who do not write Apex. Prompt Template actions invoke a prompt that calls the LLM with grounded data and return its response. Standard actions are the built-ins shipped by Salesforce: Identify Record, Query Records, Update Record, Send Email, Trigger Flow, plus channel-specific ones. Data Library Search actions do retrieval-augmented generation against an Agentforce Data Library. Pick Apex for complex orchestration, Flow for admin-built logic, Prompt Template for free-form text generation, Standard for record CRUD, and Data Library Search when the answer lives in your knowledge base.
How instructions guide the reasoning engine
The instruction field on an Agent Action is the most important field in the entire Agentforce stack. The reasoning engine reads instructions, not code. A vague instruction like "use this to look up orders" loses to a specific one like "Use this action when the user asks for order status, order tracking, or where their package is. Do not use it for refund requests." Write instructions in the second person, name the user phrases the action should match, and call out negative cases. The same logic applies to inputs and outputs: each input parameter has its own description that the engine uses to extract the right value from the conversation.
Input and output schemas
Every Agent Action declares input parameters and output values. Inputs are the values the agent extracts from the conversation and passes to the underlying code. Outputs are what the action returns, which the agent uses in the response or as input to the next action. Inputs need clear types (Text, Number, Boolean, Date, sObject, List). The instruction on each input tells the engine where to find the value: "the customer's order number in the format ORD-XXXX" beats "order number." Outputs are typed too. If the action returns a record, declare the sObject so the engine knows what fields are available for the response.
Action grouping under Agent Topics
Agent Topics are skill groups. Each topic has a classification description that helps the engine decide if a user message falls under this topic at all. Actions attached to a topic are only considered when the topic is active for the current turn. Without topics, the engine would have to scan every action on every message, which kills latency and accuracy. A common pattern is one topic per business outcome (Returns, Renewals, Account Updates), each with three to seven actions. Topics also gate context: an action that needs a specific channel or user permission can be scoped via topic-level rules rather than per-action.
Testing actions in the Plan Trace
The Conversation Preview pane in Agent Builder shows a Plan Trace for every test message. The trace lists which topic the engine chose, which actions it invoked, the input values it extracted, the outputs returned, and the final response. If an action did not fire when you expected it to, the trace tells you why. The two most common findings are wrong topic classification and overlapping instructions. The Agentforce Testing Center runs a saved test set against the agent on every change so you catch regressions before they ship.
Versioning, governance, and permission sets
Apex actions inherit the calling user's permissions through "without sharing" or "with sharing" as you write them. Flow actions respect the running user context flag on the flow definition. Agent Builder shows a version history per action that lets you roll back to a prior instruction or schema. Changes to an action's instructions or schema do not need a new agent version, but adding or removing an action from a topic does. The Agentforce Service Agent User permission set assigns the runtime entitlement to anyone the agent acts on behalf of, while the Agentforce Builder permission lets admins edit actions and topics.
How to ship your first custom Agent Action
Most teams ship their first custom Agent Action in a single afternoon. The work is split between defining the action (instructions, inputs, outputs) and writing the underlying flow or Apex. Get the action working in the Plan Trace before you wire it into a topic and let real users hit it.
- Decide the action type
Pick Apex if you need loops, callouts, or sObject orchestration. Pick Flow if an admin can build the logic. Pick Prompt Template if the action's job is generating text against grounded data. Standard and Data Library Search are usually obvious by the use case.
- Build the underlying flow or Apex method first
For Apex, write a public class with one @InvocableMethod and matching InvocableVariable inputs and outputs. For Flow, build an autolaunched flow with input and output variables marked Available for Input and Output.
- Create the Agent Action record
Setup, Agent Actions, New Agent Action. Pick the type. Pick the reference (Apex class, Flow API name, prompt template, etc.). Salesforce reads the input and output signatures from the underlying artifact.
- Write the action instruction and parameter descriptions
The action instruction tells the reasoning engine when to use this action. Write it in the second person, name the user phrases the action should match, and call out negative cases. Each parameter gets its own description for value extraction.
- Attach the action to a topic
Open Agent Builder, open the agent, open the topic. Click Add Action and pick your action from the org library. The action is now considered for any message that the topic classifier sends to it.
- Test in the Conversation Preview and read the Plan Trace
Send messages that should and should not trigger the action. The Plan Trace shows the decision path. Refine the instruction or parameter descriptions until the action fires when it should and stays silent when it should not.
- Save the test cases to Agentforce Testing Center
Capture both the positive and negative test messages as a saved test set. Testing Center re-runs the set on every agent change and flags regressions before deploy.
Apex, Flow, Prompt Template, Standard, or Data Library Search. Drives what underlying artifact the action wraps.
The specific Apex class, Flow, prompt template, or Data Library the action invokes. Required and immutable after creation.
Natural-language description the reasoning engine uses to decide when to invoke this action. The most important configuration field on the record.
Per-parameter natural-language descriptions used for value extraction from the conversation and for downstream actions to consume the output.
Toggles the action on or off across all topics it is attached to. Useful for emergency rollback without unwiring topics.
- The action instruction is the only thing the reasoning engine uses to pick actions. Vague instructions ("use this for orders") match too much and trigger the wrong action.
- Apex actions need the @InvocableMethod annotation and matching InvocableVariable inputs. A regular @AuraEnabled method will not surface as an Agent Action.
- Changing an Apex method's signature breaks the bound Agent Action. The action keeps the old schema until you re-bind, and runtime calls fail with a parameter mismatch.
- Flow actions run with the running user's context. A flow that updates fields the agent's user cannot edit fails silently from the agent's point of view.
- Custom actions attached inline inside Agent Builder are scoped to that agent. Create org-level actions in the Agent Action library if you want reuse.
Trust & references
Straight from the source - Salesforce's reference material on Agent Action.
- Agent Actions OverviewSalesforce Help
- Agent TopicsSalesforce Help
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. How does the Einstein Trust Layer relate to Agent Action?
Q2. What does Agent Action need to work effectively?
Q3. What technology powers Agent Action in Salesforce?
Discussion
Loading discussion…