See related
No related articles

Use an external API with AI Agents for Customers

Last Update: Feb 2025 • Est. Read Time: 12 MIN
To check plan availability, see the pricing page.

AI Agents can connect to external systems using tools powered by OpenAPI specifications, allowing them to retrieve real-time data and provide more accurate responses to customers. By integrating an API with an OpenAPI spec, you can extend your AI Agent’s capabilities and perform actions such as:

  • Get customer data from external systems
  • Place orders on external e-commerce systems
  • Adjust bookings on travel booking systems
  • Check stock levels from warehouse inventory systems
Who can access this feature?
User typesAdmins can access the AI Agents Studio page.


This article provides an example specification you can use as a guideline to create your own.

In this article:

Prerequisites

Before creating the tool, you must have an OpenAPI specification for the API you want to use with AI Agents. The specification must adhere to the OpenAPI format.

Example OpenAPI specification

This example uses the free OpenWeather API to get current weather data for a particular city. When using a tool with this specification, the AI Agent will determine which city to get weather for by reasoning about the conversation and the user's intent. For example, let's say the following message is sent to an AI Agent that has this tool assigned: "Hi, what's the weather in London?"

The AI Agent will:

  1. Determine that the user intends to obtain current weather information about London
  2. Look at which tools it has to help the customer
  3. Identify that it has a tool assigned to it
  4. Determine that this tool will address the customer’s need for current weather in London
  5. Call the tool and sets the input parameter of q to “london”
  6. Return the weather data output from the tool in a friendly tone to the customer

Example OpenWeather API:

openapi: 3.0.0
info:
  title: OpenWeatherMap API
  description: Sample OpenWeather API.
  version: "2.5"
servers:
  - url: https://api.openweathermap.org/data/2.5
paths:
  /weather:
    get:
      summary: Call current weather data for one location
      description: Get the current weather info
      operationId: CurrentWeatherData
      parameters:
        - $ref: "#/components/parameters/q"
        - $ref: "#/components/parameters/lang"
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/200"
components:
  parameters:
    q:
      name: q
      in: query
      description: For the query value, type the city name and optionally the country code divided by comma; use ISO 3166 country codes.
      required: true
      schema:
        type: string
    lang:
      name: lang
      in: query
      description: the language to return the city name and description in when retreiving the weather
      required: true
      schema:
        type: string
        enum:
          - en
  schemas:
    "200":
      title: Successful response
      type: object
      properties:
        coord:
          $ref: "#/components/schemas/Coord"
        weather:
          type: array
          items:
            $ref: "#/components/schemas/Weather"
          description: (more info Weather condition codes)
        base:
          type: string
          description: Internal parameter
          example: cmc stations
        main:
          $ref: "#/components/schemas/Main"
        visibility:
          type: integer
          description: Visibility, meter
          example: 16093
        wind:
          $ref: "#/components/schemas/Wind"
        clouds:
          $ref: "#/components/schemas/Clouds"
        rain:
          $ref: "#/components/schemas/Rain"
        snow:
          $ref: "#/components/schemas/Snow"
        dt:
          type: integer
          description: Time of data calculation, unix, UTC
          format: int32
          example: 1435658272
        sys:
          $ref: "#/components/schemas/Sys"
        id:
          type: integer
          description: City ID
          format: int32
          example: 2172797
        name:
          type: string
          example: Cairns
        cod:
          type: integer
          description: Internal parameter
          format: int32
          example: 200
    Coord:
      title: Coord
      type: object
      properties:
        lon:
          type: number
          description: City geo location, longitude
          example: 72.85
        lat:
          type: number
          description: City geo location, latitude
          example: 19.01
    Weather:
      title: Weather
      type: object
      properties:
        id:
          type: integer
          description: Weather condition id
          format: int32
          example: 803
        main:
          type: string
          description: Group of weather parameters (Rain, Snow, Extreme etc.)
          example: Clouds
        description:
          type: string
          description: Weather condition within the group
          example: broken clouds
        icon:
          type: string
          description: Weather icon id
          example: 50d
    Main:
      title: Main
      type: object
      properties:
        temp:
          type: number
          description: "Temperature. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit."
          example: 293.25
        pressure:
          type: integer
          description: Atmospheric pressure (on the sea level, if there is no sea_level or grnd_level data), hPa
          format: int32
          example: 1019
        humidity:
          type: integer
          description: Humidity, %
          format: int32
          example: 83
        temp_min:
          type: number
          description: "Minimum temperature at the moment. This is deviation from current temp that is possible for large cities and megalopolises geographically expanded (use these parameter optionally). Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit."
          example: 289.82
        temp_max:
          type: number
          description: "Maximum temperature at the moment. This is deviation from current temp that is possible for large cities and megalopolises geographically expanded (use these parameter optionally). Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit."
          example: 295.37
        sea_level:
          type: number
          description: Atmospheric pressure on the sea level, hPa
          example: 984
        grnd_level:
          type: number
          description: Atmospheric pressure on the ground level, hPa
          example: 990
    Wind:
      title: Wind
      type: object
      properties:
        speed:
          type: number
          description: "Wind speed. Unit Default: meter/sec, Metric: meter/sec, Imperial: miles/hour."
          example: 5.1
        deg:
          type: integer
          description: Wind direction, degrees (meteorological)
          format: int32
          example: 150
    Clouds:
      title: Clouds
      type: object
      properties:
        all:
          type: integer
          description: Cloudiness, %
          format: int32
          example: 75
    Rain:
      title: Rain
      type: object
      properties:
        3h:
          type: integer
          description: Rain volume for the last 3 hours
          format: int32
          example: 3
    Snow:
      title: Snow
      type: object
      properties:
        3h:
          type: number
          description: Snow volume for the last 3 hours
          example: 6
    Sys:
      title: Sys
      type: object
      properties:
        type:
          type: integer
          description: Internal parameter
          format: int32
          example: 1
        id:
          type: integer
          description: Internal parameter
          format: int32
          example: 8166
        message:
          type: number
          description: Internal parameter
          example: 0.0166
        country:
          type: string
          description: Country code (GB, JP etc.)
          example: AU
        sunrise:
          type: integer
          description: Sunrise time, unix, UTC
          format: int32
          example: 1435610796
        sunset:
          type: integer
          description: Sunset time, unix, UTC
          format: int32
          example: 1435650870


Tune request parameters

AI Agents can provide different arguments for tools for different use cases. In this example spec, the AI Agent determines that it will need to call the GetWeather tool with the q parameter set to “london” to address the customer’s needs. There are two ways to set up different input parameters when configuring any tool in the AI Agent Studio:

  1. Reasoning attributes
    Reasoning attributes are populated by the AI Agents when the tool is used to help a customer, based on all of the information at its disposal, such as:
    • Conversation data (messages, etc)
    • Customer data
    • Knowledge base articles
    • Prior tool output

  2. Preset Attributes
    Preset attributes are static, and do not change when the tool is used. When an AI Agent uses a tool with preset attributes, the tool is always called with the preset value configured for the preset attribute. A common use case for this is when you want the tool to always use the same value.

When it comes to OpenAPI tools that send requests to other systems, these parameters can be used to form a query string, a request body, a path parameter, or a header value. In the example above, we used a mixture of Preset and Reasoning attributes to fill in the query string of the request, with the primary goal of retrieving weather information for any city, in English.

Unsupported OpenAPI fields

Not all fields in an OpenAPI specification are pertinent when considering tools to be used by an AI Agent. Kustomer has simplified this process by supporting only the most critical fields from the expansive OpenAPI Specification. 

The below fields and features are not supported today:

  • security and securitySchemas
    Kustomer AI Agent Studio allows you to create an Authentication through UI form, therefore we do not need to provide Security information in the OpenAPI Specification itself

  • requestBodies
    Since AI Agent Studio creates one tool from your OpenAPI Specification, there is no need to use this field for sharing amongst different OpenAPI paths

  • Cookie parameters

  • Optional fields
    AI Agents work best when they have explicit instructions and parameters to work from. We find it most effective to create tools that have required parameters. If you need different variations of input parameters, we suggest creating multiple tools. This means every parameter needs to be marked as “required” in your OpenAPI Specification.

  • Multiple Servers
    Tools should only talk to one API, therefore, we only support one Server URL.

  • Multiple Paths or Operations
    As mentioned previously, AI Agent Studio only supports one tool at a time when created from an OpenAPI Specification. Tools have a 1:1 relationship with Paths and Operations in an OpenAPI Specification.

Create a tool that connects to the OpenAPI spec

Once you have your OpenAPI specification, you can create a tool in AI Agent Studio that uses it to respond to customer inquiries.

  1. Go to Settings > Kustomer IQ > AI Agent Studio.
  2. Select the Tools tab and go to OpenAPI.
  3. Enter a name and description for the tool. These should be descriptive of what the tool will do, as both of these fields will be used by your AI Agent to determine when and how to use the tool. Since this example tool will retrieve weather data, we will name it “Get Weather Data” and set the description to “This tool is used to get current weather data for a particular city”.
  4. Next, select the authentication required to connect to your API by selecting Add Authentication, and setting up the required fields. 
    Currently, the supported authentication methods are:
    • Bearer Token
    • API Key
    • Basic Authentication

  5. Finally, enter the API spec in the area provided. 

  6. Select Create.