Enabling an API Project for Topics and Agent Actions | MuleSoft Documentation
# 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 makes 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
  * Establish a tenant relationship between your Anypoint Platform organization and a trusted Salesforce organization that has agent entitlements.
  * Verify that API Catalog is enabled for the connected Salesforce organization.
  * Verify that you have the required permissions:
    * Anypoint Exchange permissions so that users can download and publish assets:
    * Runtime Manager permissions to enable services related to CloudHub and CloudHub 2.0, such as deploying applications:
      * **Read applications**
      * **Create applications**
      * **Delete applications**
    * Design Center Developer permission so that users can view and create APIs.
  * In **Anypoint Platform → API Governance** , make sure you opt in to govern APIs by version.
  * Set up and access the web or desktop IDE.
  * Understand the basics of designing API specs.
See the Tutorials for details.
  * Have some familiarity with business groups.


## Create an API Specification Project for Agent Actions and Topics
  1. In the activity bar of the IDE, click the (**Anypoint Code Builder**) icon.
  2. From **Quick Actions** , click **Design an API** :
  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. See Adding Folders to Your Home Directory. Don’t create the project within another project directory.  
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.
The Agent Topics configuration panel opens.
  6. In the Agent Topics configuration panel, configure agent topic metadata and instructions, and click **Apply**.
  7. Continue designing your API spec.
As you enter elements, use auto-complete (or press Ctrl+Space) to display available options within the context.


## Add 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**
The asset version for your API project must follow the semantic versioning model. For more information, see Asset Versions.
     * **API Version**
The major version for the API.
     * **Business Group**
Select the Anypoint Platform business group this API will be available in.
     * **Asset ID**
     * **Asset Name**
     * **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.
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  
---|---|---  
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.  
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 must 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.  
x-sfdc/privacy/isPii | Optional. Set this attribute to `true` to enable PII service for queries sent under that operation  
x-sfdc/agent/action/isUserInput | Required. Set this attribute to `true` to surface the field to the user for further input.  
x-sfdc/agent/action/isDisplayable | Required. Set this attribute to `true` for the field to be displayable to the user.  
Adding agent metadata in a schema that’s defined using `$ref` isn’t supported. The metadata must be defined inside the schema, for example:
```
... (Inside response, request body, etc..)
schema:
 $ref: '#/components/schemas/Pet'
...
components:
 schemas:
  Pet:
   x-sfdc:
    agent:
      action:
        isDisplayable: true
   required:
    - name
    - photoUrls
   properties:
    id:
     type: integer
     format: int64
     example: 10
    name:
     type: string
     example: doggie
    status:
     type: string
     description: pet status in the store
     enum:
      - available
      - pending
      - sold
```
## Topic and Agent 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 Catalog.
## 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.
## See Also
  *   * The Building Blocks of Agents
  * Creating and Importing API Specifications
  * Publishing API Projects to Exchange