MuleSoft APIs as AI Assets: A Practical Guide to x-SFDC Tags

Unlock AI Power: How to Enable Your MuleSoft APIs as AI Assets!

Are you ready to make your APIs smarter and open them up to the world of Artificial Intelligence? The future of integration is here, and it involves turning your APIs into powerful AI assets. This means your APIs can be understood and used directly by AI tools, like Salesforce’s Agentforce.

Let’s dive into how you can enable your APIs to become these intelligent assets, using practical examples from an OAS 3 specification.

What Are AI Assets for APIs?

Traditionally, APIs are built for applications or other systems to call directly. But an AI asset is different. It’s an API that has extra information, or “metadata,” describing what it does in a way that an AI agent can understand. This allows the AI Agent to decide when and how to use your API without needing complex, pre-programmed logic. It makes your integrations much more flexible and powerful!

The Magic Behind the Scenes: x-sfdc Tags

To make your MuleSoft API an AI asset, you use special extensions in your OAS 3 specification. These are called x-sfdc tags. They provide the necessary context for AI agents. You can read more about it in MuleSoft “Enabling an API Project for Topics and Agent Actions”

Let’s look at an example from a Magical Potion Brewery API – because even magic needs robust integration!

x-sfdc:
  agent:
    topic:
      name: Magical Potion Brewery
      classificationDescription: This topic is designed for managing the mystical art of potion brewing, from ordering ingredients to delivering enchanting concoctions.
      scope: Your role is to facilitate the magical production and delivery of potions. You can brew new potions, check their brewing status, and discover daily specials.
      instructions:
        - To conjure a new potion, use the `brewPotion` action with the potion name, desired quantity, and a list of magical ingredients.
        - To check on a potion order, use the `checkDeliveryStatus` action with the unique order ID.
        - To discover today's special enchanting brew, use the `getDailySpecial` action.  

In this snippet:

• name: Gives a simple name for the topic, like “Magical Potion Brewery.”
• classificationDescription: Explains the general purpose of this API, this is topic description.
• scope: Describes the overall role of the API, what it helps achieve and what it can’t do.
• instructions: Provides detailed guidance to the AI on how to use the API’s operations. This is crucial for the AI’s orchestration capabilities!

Marking Operations as Agent Actions

Once you’ve defined the overall topic, you need to tell the AI which specific API operations it can call. This is done by adding x-sfdc tags directly to your API paths.

Here’s an example for a brewPotion operation:

paths:
  /potions/brew:
    post:
      summary: Conjure a New Potion
      operationId: brewPotion
      x-sfdc:
        agent:
          action:
            publishAsAgentAction: true # This line makes it an AI asset action!
      requestBody:
        required: true
        description: Details for brewing a new magical potion, including its name, quantity, and mystical ingredients.
        content:
          application/json:
            schema:
              additionalProperties: false # Important for strict validation
              type: object
              x-sfdc:
                agent:
                  action:
                    isUserInput: true # Marks these properties as inputs from the user
              properties:
                potionName:
                  type: string
                  description: The enchanting name of the potion to brew (e.g., 'Elixir of Euphoria').
                quantity:
                  type: integer
                  description: The number of potion vials to conjure.
              required:
                - potionName
                - quantity  

Key elements here:

• operationId: brewPotion: This is text identifier of the operaiton.
• publishAsAgentAction: true: This is the core tag that tells Agentforce this operation is available for AI use.
• isUserInput: true: For request body properties, this tag indicates that the values for potionName, quantity, and ingredients are expected to come directly from the user’s input to the AI agent.
• additionalProperties: false: This is a crucial validation rule. It ensures that only the properties explicitly defined in your schema are accepted, which is important for AI agents to correctly understand the data structure.

Controlling AI Output: Displaying Results

You can also control what information the AI agent displays back to the user from your API’s response. This is done using the isDisplayable tag.

Consider the response for retrieving today’s special potion:

paths:
  /potions/daily-special:
    get:
      summary: Get Today's Special Potion
      operationId: getDailySpecial
      description: Fetches the details of the magical potion special for the current day.
      x-sfdc:
        agent:
          action:
            publishAsAgentAction: true
      responses:
        '200':
          description: Details of today's special potion.
          content:
            application/json:
              schema:
                additionalProperties: false
                x-sfdc:
                  agent:
                    action:
                      isDisplayable: true # This makes the entire schema displayable
                type: object
                properties:
                  specialName:
                    type: string
                    description: The name of today's special potion.
                  effect:
                    type: string
                    description: The magical effect of the potion.
                  price:
                    type: number
                    format: float
                    description: The cost in enchanted coins.  

By setting isDisplayable: true at the schema level, you’re telling Agentforce that the entire JSON response structure should be presented to the user. You could also apply isDisplayable: true to individual properties if you only want specific fields to be shown.

Conclusion: Build Smarter Integrations

Enabling your MuleSoft APIs as AI assets with x-sfdctags is a powerful step towards building more intelligent and autonomous integrations. By clearly defining your API’s purpose, inputs, and outputs for AI agents, you unlock new possibilities for automation and enhanced user experiences, especially within the Salesforce ecosystem.

Start experimenting with these tags in your OAS 3 definitions and see how your APIs transform into truly smart components of the integration landscape!

You can find the full YAML specification for the Magical Potion Brewery API on GitHub Gist.

Let’s keep learning and make our connections truly smart!