Hear from Salesforce leaders on how to create and deploy Agentforce agents.
Contact Us 1-800-596-4880

Enabling an API Project for Topics and Agent Actions

Use MuleSoft for Agentforce: Topic Center (also known as Topic Center) to enable API specifications for topics and agents, which can then be synced to API Catalog in Salesforce. You can then augment agent functionality by assigning topics to Agentforce agents in Agent Builder.

Use the Topic Center visual editor to:

  • Enable the API specifications for topics and agents.

  • Apply governance rules to validate that your API is ready to generate agent actions and topics in Salesforce.

  • Add metadata to make your topic and action-enabled APIs available in Salesforce using Salesforce API Catalog.

Topics are bundles of actions and sets of instructions Agentforce agents use to complete tasks. Actions are tasks that the agent can do, and instructions help the agent understand how to use actions.

Topic Center automatically makes all of your API operations available as agent actions and topics. Agents perform common tasks autonomously, such as updating records, searching and summarizing data, and securely taking action in various systems. Agents are reusable across any set of topics and can contain multiple topics.

Before You Begin

Create an API Specification Project for Agent Actions and Topics

  1. In the activity bar of the IDE, click the (Anypoint Code Builder) icon.

    Anypoint Code Builder icon highlighted in the activity bar
  2. From Quick Actions, click Design an API:

    *Design an API* link highlighted in the *Quick Actions* section
  3. Select Enable this API for Agent Topics and Actions.

  4. Complete the API Specification form:

    Field Name Field Value

    Project Name

    Unique name for your project.

    This name is used as the API spec title in Exchange, the name of the spec file, and the name of the project’s root directory. For example, if the project name is Agent Example, the spec file name is agent-example.

    To reuse an existing project name, you must delete the project that is already using the name first. See Deleting API Specs and Fragments.

    Project Location

    Your home directory or another directory you create.

    Don’t create the project within another project directory.

    API Type

    Select REST API.

    API Specification Language

    Select OAS 3.0 (YAML) or OAS 3.0 (JSON).

    Only OAS 3.0 is supported for topics and actions.

    Business Group

    Select the business group the API will belong to. The business group is required for API governance and syncing centralized rulesets. When you publish your API spec to Exchange from Anypoint Code Builder, the IDE requests the name of the business group.

  5. Click Create Project.

    If prompted, trust the authors of the files in the folder.

  6. Continue designing your API spec.

    As you enter elements, use auto-complete (or press Ctrl+Space) to display available options within the context.

Add Topic Metadata to the API Project

  1. In Explorer, right-click the API specification and select Open API Project Properties.

    The API Project Properties tab opens and is auto-populated with:

    • Asset Version

    • API Version

    • Business Group

    • Asset ID

    • Asset Name

    • Tags

    • Categories

      These properties are used when you publish your API specification to Exchange.

      Tags and categories help users filter search results when they search Anypoint Exchange.

      The sf-api-catalog and sf-api-topic tags are applied automatically when you enable the API for agent actions and topics.

      API Project Properties tab with sf-api-catalog and sf-api-topic tags applied

      You can edit any of the fields.

  2. If you make any changes to the API project properties, click Apply.

Configure Topics

Configure your topic in the Agent Topics configuration panel:

  1. Click the # icon to open the Agent Topics configuration panel if it’s not already open.

  2. Configure these fields for topics:

    Field Name Description Example

    Topic Label

    Enter a unique name for the topic.

    Sales Agent

    Classification Description

    Enter one to three plain text sentences. An agent uses this description to determine when to use a topic in a conversation. When a user enters a message, the agent identifies the user’s intent, compares it to the topic name and classification description, and uses the best matching topic.

    These are some examples of classification descriptions:

    Answers questions about business policies, procedures, or products.

    Interacts with the user to draft or revise content.

    Answers questions related to a user’s order status, return status, or making a return.

    Scope

    The scope defines exactly what the agent can and can’t do for a given topic. The scope is most effective when it narrowly defines the agent’s job for a given topic as it helps limit the agent so it doesn’t try to respond outside the desired job or scope you want the topic to include.

    These are some examples of scope descriptions:

    Your job is to only handle tasks related to setting a closing strategy to close deals. This may include answering product-related pricing questions, briefing users on customer sentiment based on conversations, suggesting a close plan to help users close deals, or giving advice based on video and voice calls.

    Your job is to only educate the user with their reservation questions and only handle changing upcoming or existing reservations by resending the reservation confirmation email. You aren’t able to make new reservations.

    Instructions

    Plain text instructions help an agent make decisions about how to use the actions in a topic for different use cases. Each instruction is a single topic-specific guideline, usually phrased as “Always…”, “Never…”, “If x, then y…”, or “As a first step,…”.

    Instructions are nondeterministic, so they shouldn’t include sensitive or deterministic business rules.

    These are some examples of instructions:

    Always clarify what type of mobile device (iOS or Android) before using the Answer Questions with Knowledge function to retrieve troubleshooting information.

    Never ask the user for an ID. Instead, use the name or ask for the name of the record to use IdentifyRecordByName to get the ID to call other actions.

    If a user asks about the status of their order or order confirmation, ask if they have their order number or their email. If a user doesn’t have their email or order number, ask if they’d like to escalate to an agent or create a case.

Configure Actions

Create agent actions using a schema to define the required metadata. As you enter elements, use auto-complete (or press Ctrl+Space) to display available options within the context.

To enable an API for agent topics and actions, you need to annotate at least one operation to use as an agent with x-sfdc/agent/action/publishAsAgentAction and set the value to true.

Extension Description Default Value

x-sfdc/agent/action/publishAsAgentAction

Required. Set this attribute to true to enable the operation as an action.

false

x-sfdc/privacy/isPii

Optional. Set this attribute to true to enable PII service for queries sent under that operation

false

x-sfdc/agent/action/isUserInput

Required. Set this attribute to true to surface the field to the user for further input.

false

x-sfdc/agent/action/isDisplayable

Required. Set this attribute to true for the field to be displayable to the user.

false

Adding agent metadata in a schema that’s defined using $ref isn’t supported. The metadata must be defined inside the schema, for example:

Governance Rulesets

To make sure your API is ready to generate agent actions and topics in Salesforce, the SF API Topic and Action Enablement centralized ruleset is added to your topic-enabled API project automatically.

  1. Optionally, add additional rulesets that are required for your project.

  2. Validate the governance rulesets.

    If you remove the sf-api-catalog and sf-api-topic tags from your API project, the topic and action rulesets are automatically removed.

Publish the API spec to Exchange

After you validate your API specification rulesets, publish your API specification to Exchange.

After you publish your API to Exchange and create an active API instance in API Manager, it is available for use in API Catalog. For more information, see API CatalogLeaving the Site.

Disable the API Specification for Topics

  1. In Explorer, right-click the API specification and select Open API Project Properties.

  2. Deselect Enable this API for Agent Topic and Actions, and click Apply.

The sf-api-catalog and sf-api-topic tags and the SF API Topic and Action Enablement ruleset are removed from the API project.