Apex REST allows you to expose your custom Apex logic, including Apex classes and methods, as REST APIs for external applications to call. If you are developing agents and want to enhance their ability to perform jobs unique to your business, you’ll want them to be able to leverage your Apex REST investment and call your existing Apex REST APIs.
At TDX ’25, Salesforce announced a new Beta to make Apex REST APIs available as agent actions. These actions can then be incorporated into your agents, enabling them to call your Apex REST APIs to leverage your custom logic.
In this blog post, we’ll walk you through the steps to achieve this, including first creating an OpenAPI document that describes the Apex REST API, then registering that OpenAPI document in the API Catalog in your org, and finally creating agent actions from each Apex REST API operation defined in the OpenAPI document.
Understand your Apex REST API
Apex REST allow you to expose your Apex class and methods as a REST API, so that external applications can invoke them. This is done by defining annotations in your Apex class to expose the class as a REST resource. Below is an Apex class that uses Apex REST to expose a REST API that will return the average menu prices for storefronts with a provided minimum average review score. Notice the @RestResource and @HttpGet annotations. Refer to the documentation for more information on Apex REST.
When creating the OpenAPI document that describes your API, you will need to have a good understanding of the exposed behavior of the API, in particular the request and response formats. This will be important when you come to validating and enriching the generated OpenAPI document. We recommend that you first invoke your Apex REST API using a tool like Postman to make sure that you gain this understanding.
Create and configure the OpenAPI document
The first step is to create an OpenAPI document that describes your Apex REST API, using either VS Code or Code Builder. The documentation describes the pre-requisites needed for correctly installing the IDE and required extension packs, and setting up your Salesforce DX Project that includes your Apex REST API class. Note that you’ll also need to install the Agentforce for Developers extension in the IDE, which is included in both the Salesforce Extension Pack and the Salesforce Extension Pack (Expanded).
When your IDE and Salesforce DX Project are set up, you are ready to start creating the OpenAPI document for your Apex REST API.
The OpenAPI document can be generated by Agentforce for Developers. Open the Apex class in your Salesforce DX Project and use the SFDX: Create OpenAPI Document from This Class (Beta) command in the command palette as shown in the screenshot below.
This command will create two files in the externalServicesRegisterations folder:
<Apex class name>.yaml: The generated OpenAPI document<Apex class name>.externalServiceRegisteration-meta.xml: Metadata for deploying the API to the API Catalog
The API Catalog in your org uses External Services metadata “behind the scenes” to store the definitions of APIs registered in the catalog. This explains the naming of the ExternalServiceRegisterations folder and the .externalServiceRegisteration-meta.xml file. It does not mean that the APIs become External Services registered on the org — they are not, and they will not be listed in the External Services screen in Setup.
Below is the generated OpenAPI document for the StorefrontSummary Apex class for our example StorefrontSummary Apex class.
At this point, you should review the generated OpenAPI document to ensure that it accurately describes the REST API exposed by the Apex class based on your understanding of the Apex class implementation, and make improvements as required. The documentation lists a number of items in the OpenAPI document to review.
How comprehensive your OpenAPI document is depends on the current ability of Agentforce for Developers to generate the OpenAPI document from Apex REST API classes. Below, you can see the corrected OpenAPI document and compare it with the generated OpenAPI document above.
There are limitations in the current Beta, and we are looking for your feedback on your experience to make improvements. For example, is this shortcoming just an inconvenience or a blocker for using this feature? Are you able to overcome this challenge to complete the OpenAPI document if you have limited knowledge of the OpenAPI Specification? Please provide any feedback on your experience in the Agentforce for Developers Trailblazer Community.
The descriptions for the REST API, its operations and parameters, in the generated OpenAPI document may need to be enriched to better help agents consistently and accurately choose the API when processing a user request. The best practice is to ensure that these descriptions are as comprehensive as possible as agents will use them when selecting actions. Agentforce for Developers cannot be expected to know the role that your Apex REST API plays within your business, so be sure to add this context in the summary and description fields, so your agents know when to use your API. As an example, compare the generated descriptions in the above OpenAPI document, with the modified and enriched descriptions in the final OpenAPI document shown in the “Validating the OpenAPI document” section below..
Specifying agent actions in the OpenAPI document
You can add optional extension fields to the OpenAPI document to automatically create custom agent actions when your Apex REST API is registered in the API Catalog. This provides you as the owner of the Apex REST API with control over how your API is made available to your agents as agent actions. It also saves you setup time as this would otherwise have to be done in Agent Studio. The agent actions that are created will use the descriptions for the API operations and parameters defined in the OpenAPI document, enabling you to ensure that the descriptions are complete and accurate, so that your agents choose them correctly.
It also means that you don’t need to manually create the agent actions in the Agent Action Builder dialog. Finally, as the action metadata is included in your Salesforce DX Project along with your Apex class, you can then apply Salesforce DX best practices.
The documentation lists the Salesforce-specific extension fields to create agent actions; they are all located under a x-sfdc tag. In the “Validating the OpenAPI document” section below, the example OpenAPI document uses these extension fields to:
publishAsAgentAction: Create a custom agent action from the API.isUserInput: Indicate that theminAvgReviewScoreparameter should be populated by user input. This corresponds to theCollect data from usersetting in the Agent Action Builder.isDisplayable: Indicate that a successful response should be displayable to the user. This corresponds to theShow in conversationsetting in the Agent Action Builder.
Specifying the agent topic in the OpenAPI document
In Agentforce, an agent topic is a group of actions that are focused on a specific job done by agents. Agent actions are added to topics, and topics are added to agents to enable them to perform specific jobs.
You can also choose to define a topic in your OpenAPI document using the MuleSoft Topic Center feature. This complements and extends the control that you have over defining how your API is presented to agents, and it helps save setup time as this would otherwise need to be done in Agent Studio. The feature allows you to define the topic name, topic description, and agent instructions. These details are important as the agents use them to select the most relevant topic and actions to answer user requests, and defining them in the OpenAPI documents allows you to ensure that they are comprehensive.
When the API is registered with the API Catalog, the topic is automatically created in Agentforce, and any agent actions defined in the OpenAPI document are added to the topic. The topic can now be added to an agent, so the agent can perform the specific job that is the focus of the topic, and all the agent actions are available to the agent.
To use the MuleSoft Topic Center, you first must install the MuleSoft for Agentforce API Design Extension, available in the MuleSoft for Agentforce Extension Pack, in your IDE. Refer to the documentation for more details. Once this is installed in your IDE, open Topic Center for your OpenAPI document and define a topic (see the documentation on how to do this).
Validating the OpenAPI document
When you have followed all of the steps above and completed your OpenAPI document, you can then apply governance rules to verify its correctness. You do this by running the SFDX: Validate OpenAPI Document (Beta) command on the document.
However, if you have installed the MuleSoft for Agentforce Extension Pack (Beta), then this command will not be available. Instead, you will use the governance rules included in this extension pack. Run the Salesforce API Topic and Action Enablement governance ruleset that is available in the IDE Explorer on the left-hand side. You can find more details of these governance rules in the documentation.
Both approaches apply the same governance rules to validate your OpenAPI document. They will both flag any errors and warnings that need to be fixed before deploying your API to the API Catalog.
Another way of validating the correctness of your OpenAPI document is to import it into Postman to create a new collection, and use that to invoke your Apex REST API. If Postman can invoke your Apex REST API correctly, then the OpenAPI document is an accurate description. Note that you’ll need to authenticate Postman with your org and the OpenAPI document does not help here. If you used Postman earlier to gain an understanding of your Apex REST API, then you can leverage that authentication.
To make this concrete, below is the OpenAPI document that describes the Apex REST API for the example StorefrontSummary Apex class we introduced above. The OpenAPI document includes the extensions fields to specify the topic and agent action.
Register the Apex REST API in the API Catalog
When the OpenAPI document is complete, the Apex REST API must be registered in the API Catalog, so that it can be made available as an agent action. Agentforce uses the API Catalog to identify the APIs that can be activated as custom agent actions. Another benefit that the API Catalog provides is a central location where developers can discover what Apex REST APIs are available for them to use.
This registration is performed by deploying both the .yaml and .externalServiceRegisteration-meta.xml files in the ExternalServiceRegisterations folder to the target org. Right-click on the folder and select the
SFDX: Deploy this Source to Org command.
View Apex REST APIs in the API Catalog
The API Catalog is a single place where you can view API definitions from various sources and make them available for use in Salesforce. Today, the API Catalog supports viewing Apex REST APIs as a Beta feature (to learn more, refer to the documentation). The screenshot below shows the above Apex REST API registered in the API Catalog.
Agent actions and topics
Once the Apex REST API has been deployed to the API Catalog, then the operations in the API can be used to create agent actions and include those actions in topics. As we’ve seen above, both of these can be defined in the OpenAPI document and this is the recommended approach. However, if you choose not use this approach or if this agent configuration is performed by another user or persona in your organization, then you can create these actions using the Agent Action Builder dialog in the Agent Action screen in Setup.
Using in an agent
The final step is to include the topic containing the agent actions in your agents, and then those agents can start leveraging your Apex REST APIs to address user requests!
Lastly, you’ll need to ensure that the user for whom the agent will invoke the Apex REST API is authorized to access the Apex class. Do this by including the Apex class in the Enable Apex Class Access in that user profile or in the Apex Class Access in a permission set that is assigned to the user.
Conclusion
In this post, we’ve shown how you can leverage your investment in Apex REST APIs by making them available to agents as actions that can help answer user requests.
In addition to supporting your Agentforce journey, this capability also leads to creating OpenAPI documents that describe your Apex REST APIs for broader uses, such as generating client applications and communicating the description of your API to developers. And the API Catalog provides a centralized location where your Apex REST APIs are discoverable.
We need your feedback on the capabilities of this Beta, as well as how your Apex REST APIs will power your agent journey with Salesforce, as this will influence the GA release. Please post your questions and/or feedback on the Beta to the Agentforce for Developers Trailblazer Community. And if you want to highlight your use of Apex REST APIs with your agents, we’d love to co-present your use case at Dreamforce … just let us know!
Further resources
- Documentation: Build Custom Agent Actions using Apex REST (Beta)
- Developer Experience Roadmap at TDX ’25: Demo of Apex REST APIs as Agent Actions (Beta)
- Trailblazer Community: Agentforce for Developers
About the author
Jeremy Westerman is the Director of Product Management for Salesforce APIs. He is responsible for Salesforce APIs that access data on the core Salesforce Platform. You can find him on LinkedIn.