# Creating OpenAPI Tools for AI Agents

> AI Agents can use tools to interact with data systems and services outside of the conversation In Kustomer tools help an AI Agent take action or retrieve in

Source: https://help.kustomer.com/en_us/creating-openapi-tools-for-ai-agents-ByVUWqvAg

Last updated: 2026-05-05T15:59:29.914Z

AI Agents can use tools to interact with data, systems, and services outside of the conversation. In Kustomer, tools help an AI Agent take action or retrieve information so it can respond more accurately and complete customer requests.

### In this article

*   [Understanding OpenAPI tools](#understanding)
*   [Creating an OpenAPI tools](#creating)
*   [Adding a name and description](#adding)
    *   [Add API authentication](#authentication)
    *   [Provide an OpenAPI specification](#specification)
*   [Example: Getting weather data for a city](#example)
*   [Example OpenAPI specification](#example-specification)
*   [Tuning request parameters](#tuning)
*   [Reasoning attributes](#reasoning)
*   [Preset attributes](#preset)
*   [Supported OpenAPI fields](#supported-fields)
*   [Best Practices](#best-practices)

### Understanding OpenAPI tools

OpenAPI tools let AI Agents interact with external APIs. You provide an OpenAPI specification that describes the API endpoint, the inputs it accepts, and the response it returns. The AI Agent can then decide when to use that tool based on the customer’s request and the tool’s name, description, and parameters.

### Creating an OpenAPI tool

All tools are created from the **Kustomer AI** page. Click **Tools** to open the tools page. 

To create a tool from an OpenAPI specification:

1.  Click **Add a Tool**.
2.  Select **OpenAPI**.
3.  Enter a descriptive **Name** and **Description**.
4.  Configure **Authentication**, if the API requires it.
5.  Provide the **OpenAPI Specification**.
6.  Assign the tool to an AI Agent.

Each OpenAPI tool should represent one API operation. In practice, this means one server URL, one path, and one operation such as `GET`, `POST`, `PUT`, or `DELETE`, depending on what is supported for your tool configuration.

The next sections cover each of these steps in more detail. 

### Adding a name and description

The tool name and description help the AI Agent decide when and how to use the tool. Make these fields clear, specific, and action-oriented.

For example, a tool that retrieves current weather data could use:

**Name:** Get Weather Data  
**Description:** Use this tool to get current weather data for a specific city.

A good description should explain what the tool does, when the AI Agent should use it, and what information the tool needs.

#### Add API authentication

If the external API requires authentication, configure authentication for the tool instead of hard-coding credentials into the OpenAPI specification.

Supported authentication methods include:

Authentication method

Use case

Bearer Token

APIs that expect an `Authorization: Bearer <token>` header

API Key

APIs that require a key in a header or query parameter

Basic Authentication

APIs that require a username and password

You can add a new authentication method by selecting **Add an Authentication**, or you can choose an existing authentication method if one has already been configured.

#### Provide an OpenAPI specification

The OpenAPI specification (usually in YAML or JSON format) provides the capabilities your automations can use when calling the API. It should describe the endpoint, supported parameters, and expected response.

The specification should be simple and focused. Because each OpenAPI tool maps to a single API operation, avoid including multiple unrelated paths or operations in the same specification.

### Example: Getting weather data for a city

This example uses the OpenWeather API to get current weather data for a city. This example also assumes the OpenWeather API key is configured through the tool’s authentication settings, rather than included directly in the OpenAPI specification.

Assume a customer asks:

> Hi, what’s the weather in London?

An AI automation with an OpenAPI weather tool assigned can:

1.  Understand that the customer wants current weather information for London.
2.  Review the tools available to it.
3.  Identify the weather tool as relevant.
4.  Call the tool with the city parameter set to `London`.
5.  Receive the weather data from the API.
6.  Summarize the result for the customer in a friendly, natural way.

For example, the tool may make a request like:

```
GET https://api.openweathermap.org/data/2.5/weather?q=London&lang=en
```

### Example OpenAPI specification

We have included a sample YAML file to help illustrate this example further. 

```
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: Get current weather data for one location
      description: Get current weather information for a specific city.
      operationId: CurrentWeatherData
      parameters:
        - $ref: "#/components/parameters/q"
        - $ref: "#/components/parameters/lang"
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WeatherResponse"

components:
  parameters:
    q:
      name: q
      in: query
      description: City name. Optionally include the ISO 3166 country code separated by a comma, such as London,GB.
      required: true
      schema:
        type: string

    lang:
      name: lang
      in: query
      description: Language to use when returning the city name and weather description.
      required: true
      schema:
        type: string
        enum:
          - en

  schemas:
    WeatherResponse:
      title: WeatherResponse
      type: object
      properties:
        coord:
          $ref: "#/components/schemas/Coord"
        weather:
          type: array
          items:
            $ref: "#/components/schemas/Weather"
        main:
          $ref: "#/components/schemas/Main"
        visibility:
          type: integer
          description: Visibility in meters.
          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: London
        cod:
          type: integer
          description: Response code.
          format: int32
          example: 200

    Coord:
      type: object
      properties:
        lon:
          type: number
          description: City longitude.
          example: -0.13
        lat:
          type: number
          description: City latitude.
          example: 51.51

    Weather:
      type: object
      properties:
        id:
          type: integer
          description: Weather condition ID.
          format: int32
          example: 803
        main:
          type: string
          description: Group of weather parameters, such as Rain, Snow, or Clouds.
          example: Clouds
        description:
          type: string
          description: Weather condition description.
          example: broken clouds
        icon:
          type: string
          description: Weather icon ID.
          example: 50d

    Main:
      type: object
      properties:
        temp:
          type: number
          description: Temperature. Default unit is Kelvin unless units are configured separately.
          example: 293.25
        pressure:
          type: integer
          description: Atmospheric pressure in hPa.
          format: int32
          example: 1019
        humidity:
          type: integer
          description: Humidity percentage.
          format: int32
          example: 83
        temp_min:
          type: number
          description: Minimum temperature at the moment.
          example: 289.82
        temp_max:
          type: number
          description: Maximum temperature at the moment.
          example: 295.37
        sea_level:
          type: number
          description: Atmospheric pressure at sea level in hPa.
          example: 984
        grnd_level:
          type: number
          description: Atmospheric pressure at ground level in hPa.
          example: 990

    Wind:
      type: object
      properties:
        speed:
          type: number
          description: Wind speed.
          example: 5.1
        deg:
          type: integer
          description: Wind direction in degrees.
          format: int32
          example: 150

    Clouds:
      type: object
      properties:
        all:
          type: integer
          description: Cloudiness percentage.
          format: int32
          example: 75

    Rain:
      type: object
      properties:
        3h:
          type: number
          description: Rain volume for the last 3 hours.
          example: 3

    Snow:
      type: object
      properties:
        3h:
          type: number
          description: Snow volume for the last 3 hours.
          example: 6

    Sys:
      type: object
      properties:
        country:
          type: string
          description: Country code.
          example: GB
        sunrise:
          type: integer
          description: Sunrise time, Unix UTC.
          format: int32
          example: 1435610796
        sunset:
          type: integer
          description: Sunset time, Unix UTC.
          format: int32
          example: 1435650870
```

### Tuning request parameters

When uploading your specification, parameter values can be either reasoned or preset attributes. In this example, we have two components `q` and `lang`:

```
    q:
      name: q
      in: query
      description: City name. Optionally include the ISO 3166 country code separated by a comma, such as London,GB.
      required: true
      schema:
        type: string

    lang:
      name: lang
      in: query
      description: Language to use when returning the city name and weather description.
      required: true
      schema:
        type: string
        enum:
          - en
```

Each value is derived from inside the query. The automation will use conversation context to determine that the customer wants weather information for London. It then calls the weather tool with the `q` query parameter set to `London`.

A request parameter commonly includes both **reasoning attributes** and **preset attributes**.

### Reasoning attributes

Reasoning attributes are populated by the automation at the time the tool is used, using the context available to it at the time of determination.

That context can include:

Context source

Example

Conversation messages

The customer asks, “What’s the weather in London?”

Customer data

The customer’s location, plan, or account details

Knowledge Base articles

Relevant information from your help center

Prior tool output

Information returned by another tool earlier in the conversation

Use reasoning attributes when the value should change based on the conversation.

In our example, the weather tool’s city parameter should be a reasoning attribute because the customer may ask about London, New York, Tokyo, or any other city.

## Preset attributes

Preset attributes are static values configured in advance. When the automation uses the tool, it always sends the preset value.

Use preset attributes when a parameter should always have the same value.

## Supported OpenAPI fields

OpenAPI specifications can be very detailed, but AI Agent Studio only needs the fields required to describe a callable tool. For best results, keep your OpenAPI specification focused on the one operation the tool should perform.

The following OpenAPI features are not currently supported:

Unsupported feature

Notes

`security` and `securitySchemes`

Configure authentication in AI Agent Studio. Do not include credentials or secrets in the spec.

`requestBody` and `components.requestBodies`

Request bodies are not currently supported. Use supported parameter types instead.

Cookie parameters

Cookie-based parameters are not currently supported.

Optional parameters

Define the parameters the Agent must provide as required. If you need different parameter combinations, create separate tools.

Multiple servers

A tool should call one API server. Only one server URL is supported.

Multiple paths or operations

Each OpenAPI tool should represent one path and one operation. Create separate tools for separate API actions.

* * *

## Best practices

Use clear, specific tool names and descriptions. The AI Agent uses these fields to decide when a tool is relevant.

Keep each OpenAPI specification focused on one API operation. If you need the Agent to perform multiple actions, create multiple tools.

Mark required inputs clearly. The Agent performs best when it knows exactly which values it needs to provide.

Use preset attributes for values that should not change, such as a fixed language, region, product ID, or account setting.

Use reasoning attributes for values that should be inferred from the conversation, customer data, Knowledge Base content, or previous tool output.

Configure authentication in AI Agent Studio. Do not include secrets, tokens, usernames, passwords, or API keys directly in the OpenAPI specification.[Best Practices](#best-practices)