Overview

API skill serves as an essential skill for interacting with various systems by allowing you to send input variables and receive outputs. This interaction facilitates the display of relevant information to customers. To effectively utilize an API skill, specific configurations must be set up.

Steps to Add an API Skill

Refer to this article for detailed steps on adding a skill to an AI Agent.

1. On the Skills window, click Add Skill in the top right corner of the window and select API from the dropdown.

   

2. On the API Skill window, enter the Name and Description.

   

   Guidelines for Skill Names:

   • Be Clear and Direct: Use action-oriented, unambiguous verbs.

   • Keep It Concise: Aim for 2-4 words that clearly describe the function's purpose.

   • Avoid Generic Names: Ensure the name is distinct from other functions.

   • Use a Noun or Output Indicator: Reflect the returned value (such as fetch_exchange_rate, not convert_money).

   Guidelines for Skill Descriptions:

   • Start with a Clear Action Verb: Use verbs like "Retrieves," "Fetches," or "Generates."

   • Clearly State Function Purpose: Describe what the function does without assuming prior knowledge.

   • Mention Key Inputs: Include relevant inputs, but avoid specifying types (handled separately).

   • Specify Expected Output: Clarify what the function returns.

   • Keep it Concise: Aim for a description under 20 words.

3. In the Setup Functions field, select an API and API Endpoint based on the chosen action.

4. In the Input Variables field, define necessary input variables in API Input and map the input to specific variables in Value to Send to API.

5. Enter the Output Variable to store the information retrieved from the API.

6. Enter the Error Variable to capture any error messages from the API.

7. Enter the Adapt Response and Adapted Response Variable:

   1. Adapt Response: Allows users to write Groovy code to parse, update, or format API responses and store the result in an Adapted Response Variable for later use.

   2. Adapted Response Variable: Stores the modified API output for reuse in the dialogue flow.

8. Enter the Gen AI Output: Allows users to write Groovy code to parse, update, or format the API response before it is sent to OpenAI for publishing. The modified output is what gets published. Groovy code should be written inside ${}.

   

9. Click Save to add the API Skill to your AI Agent.

Use Case of API Skill

Configuring a Customer Credit Card Inquiry API

For example, there is a user who needs to configure and use the API to retrieve credit card information, and an API backend system that provides the credit card inquiry functionality.

Prerequisites

• The user has access to the API documentation.

• The user possesses a valid API key.

• The user has a customer credit card number to input.

Process Flow

• The user accesses the configuration interface and selects the "Customer Credit Card Inquiry API" from the drop-down menu.

• The user selects an endpoint from the available options:

  • Get Credit Card Balance

  • Get Credit Card Summary

  • Get Credit Card Transactions

• The user inputs the necessary variables:

  • Credit Card Number: Entered in a designated input field.

  • API Key: Entered for authentication.

• The system maps the inputs to variables for processing.

• The user specifies an output variable name (such as creditCardOutput) to store the retrieved information.

• The user defines an error variable name (such as error) to capture any error messages from the API.

• The user decides whether to pass the raw output data to the system for further processing.

• If desired, the user configures a process output box to transform API responses into a human-readable format.

• The user submits the configuration and triggers the API call with the provided inputs.

• The system receives the API response, which is either:

  • Successful: The output variable is populated with credit card information.

  • Error: The error variable contains details about the issue.