Last updated July 14, 2025

With Heroku AppLink, you can publish your Heroku app’s OpenAPI spec to Salesforce and generate actions. This article describes how to configure your OpenAPI spec to enable specific actions such as enabling Agentforce actions and define permission sets in Salesforce.

Enable Agentforce Topics and Actions

An agent topic contains actions an Agentforce agent can do.

To enable topics for an action, you must define the topic with the following annotations. If you have one topic defined, you must have at least one action defined as well. See SF Topic and Action Enablement for more information.

To designate API operations as Agentforce agent actions, you must annotate at least one operation with the x-sfdc/agent/action/publishAsAgentAction parameter set to true. Agent actions require a schema that specifies the requisite metadata for their creation. This annotation activates the API for agent topics and actions.

Here’s an example of an OpenAPI spec that enables agent actions and topics:

openapi: 3.1.0
info:
 title: Test API
 version: '1.0'
x-sfdc:
  agent:
    topic:
      classificationDescription: This API allows agents to book, modify, and cancel hotel reservations, as well as apply loyalty upgrades.
      scope: Your job is to assist customers in booking hotel rooms based on their preferences, loyalty status, and availability. You should also be able to recommend upgrades if the customer qualifies.
      instructions:
        - If the customer asks to create a reservation, check for a check-in date, checkout date, roomType, or any special requests.
        - If the preferred room type is unavailable, suggest alternative options with similar amenities.
paths:
 /thing/{id}:
   parameters:
     - name: id
       in: path
       required: true
       description: AI-friendly description
       schema:
      type: string
       x-sfdc:
         agent:
           action:
      isUserInput: true
   get:
     x-sfdc:
       agent:
         action:
           publishAsAgentAction: true
     operationId: get-a-thing
     description: AI-friendly description
     responses:
       '200':

Customize Heroku App Settings

Optionally, you can define the connected app or the permission sets in Salesforce to elevate your user’s permission from the default user mode to user-plus mode.

Assign the specified permission set, along with the app’s standard permission set, to the users who need elevated permissions while the app is running. When the SDK is initialized, it combines the user’s Salesforce permissions with the permissions from this set, applying them to DML operations.

Here’s an example of an OpenAPI spec that specifies a connected app and permission set to use:

openapi: 3.0.0
info:
  ...
paths:
  /accounts:
    get:
      x-sfdc:
        heroku:
          authorization:
            connectedApp: MyConnectedApp
            permissionSet: MyPermSet

Additional Reading

• Getting Started with Heroku AppLink
• Working with Heroku AppLink
• Invoking Heroku AppLink Apps