Create a Custom Agent Action in the Legacy Builder
With custom actions, you can extend your agent with Salesforce functionality so that it’s ready to assist users with tasks specific to your business. Build custom actions using Apex, flows, prompt templates, and API integrations.
Required Editions
| Available in: Lightning Experience |
| Available in: Enterprise, Performance, Unlimited, and Developer Editions. Required add-on licenses vary by agent type. |
| User Permissions Needed | |
|---|---|
| To create a custom agent action: | Manage AI Agents AND the required permissions for your agent type |
| To create or modify prompt templates: | Prompt Template Manager |
| To create or modify flows: | Manage Flow |
Before you begin:
- Review the considerations for custom actions.
- create the underlying Salesforce functionality you want to use with your agent. When you create a custom action, you configure the functionality to use with your agent. You can create a custom action that calls invocable methods and REST Apex classes, external services, autolaunched flows, MuleSoft APIs, or prompt templates.
Access to a custom agent action depends on the type of Salesforce functionality it references. For example, if a custom action is built using a flow, the custom action adheres to the permissions, field-level security, and sharing settings configured in the flow. To run the action, the user or Agent User must have the Run Flows permission and access to the specific flow, depending on the type of agent.
- From Setup, in the Quick Find box, enter Agent, and then select Agentforce Assets to view all the actions in your Salesforce org.
- Click New Agent Action.
- From the Reference Action Type dropdown, select the type of functionality that you want to use to build your agent action, such as a flow or prompt template. Then select the category, if prompted, and the reference action.
- The agent action label and API name are populated with the reference action name and API name. Review these fields and, if necessary, edit the values to accurately describe the action. Then click Next.
-
The instructions for the custom action and each input and output are populated with the
descriptions from the reference action. Review these fields and make changes. See Best Practices for Agent Action
Instructions.
We copy over the descriptions from the reference action to give you a head start, but agent action instructions differ from traditional descriptions. An agent uses a large language model (LLM) and the reasoning engine to determine when to launch subagents and actions in a conversation. The instructions for the action, inputs, and outputs tell an agent what your action does and when and how to use it. Effective instructions vary by action and use case. Plan to test and iterate on your instructions to ensure that your action performs as expected.
-
For each input and output, specify any applicable settings.
Setting Details Collect data from user Require this parameter to be provided by the user. Filter from agent action When you create an agent action, all inputs and outputs from the reference action are added to the agent action. Enable this setting when you don’t want to use a parameter from the reference action with your agent action. At least one output must be used with the agent action. Require input Require this parameter in order to execute the action. All other inputs are treated as optional. If an input is required by the reference action, this setting is enabled by default and read-only. Show in conversation When this setting is enabled for some or all outputs, the outputs where the setting is enabled are included in the agent's response. On some channels, some outputs are converted to structured content (for example, the Agentforce panel in Lightning Experience recognizes record pages).
When this setting is disabled for all outputs, the agent uses the LLM to summarize the outputs in natural language in the agent's response.
Show loading text for this action Show loading text in the agent conversation while the action is running in the background.
For a custom action, you can specify the loading text for the action in the Loading Text field. In 1–3 words with no punctuation, tell your users what your action is doing. For example, “Crafting your email,” “Making updates,” or “Getting activity details.”
When this setting is disabled, or when this setting is enabled but no loading text is specified, default loading text is shown. For example, “Working,” “Making progress,” or “Checking my notes.”
To show loading text in enhanced Messaging channel conversations, additional configuration is required for Enhanced Chat and Bring Your Own Channel.
Tip When an action makes a change to a record, you can require an agent to ask the user to confirm the change before the agent can execute it. On the record page for the action, enable the Require user confirmation setting. - Click Finish.
After you create your action, assign it to a subagent to add it to your agent.
To test your action and preview how the output appears in an agent conversation, open the agent in Agentforce Builder and start a preview conversation. Enter utterances that you expect to trigger your subagent and action, and then adjust the agent action and subagent instructions based on your results. Your action must be assigned to an agent to test it. Every agent that uses your custom action has its own independent copy of the action. You can update your custom action for a specific agent, and the updates won't be shared with any other agent.
- Best Practices for Agent Action Instructions
Action instructions tell an agent what your action does and when to use it. When you create a custom action, carefully plan and test your instructions to ensure that your action performs as expected. - Enhance Agent Action UI with Custom Lightning Types
Customize the user interface (UI) for an agent action’s input and output by using custom Lightning types.
