Connecting Your APIs

Learn how to connect your APIs to GenerativeAgent

Fundamental to GenerativeAgent’s effectiveness is being able to call your APIs to get data or perform an action. When configuring GenerativeAgent, this is represented by a Function. Functions are easier to work with for nontechnical users, but they point to API Connections which are the explicit connection to your API.

While many AI tools require you to create and expose custom API endpoints for an LLM to understand, we handle this via API Connections, allowing you to use your already existing APIs.

Typically, a developer or other technical user will create API Connections. If you need help, reach out to your ASAPP team.

GenerativeAgent looks at the fields necessary to call an API and will populate them based on the conversation and information it has.

We also support Mocking API Connections to test that your API Connection returns what you expect.

API Connections

An API connection represents a connection from ASAPP into your API. An API Connection separates the interface shown to internal services and a JSONata transformation to map to the actual API call that is made. This is defined in three parts:

• API Source: The information about the underlying API endpoint.
• Request interface: The request interface that is shown to GenerativeAgent and the translation of the internal request to the API.
• Response interface: The response interface that is shown to GenerativeAgent and the translation of the API response to the internal response.

API Source

The API source for an API connection is all the details on how to call an API.

API Connections require you to provide an OpenAPI spec which should contain endpoint information such as the path, verb, request schema and response schema.

Separate from the endpoint specific information in from the API spec, you also need to specify:

• Authentication Method
• Static Headers
• Error Handling
• Default Mock Response

Request Interface

The request interface is the request fields exposed to GenerativeAgent (or any of ASAPP services) and the transformation logic to correspond to the underlying API.

The Request Schema is the JSON schema that is exposed to GenerativeAgent.

The Request Transformation is a JSONata transformation where the request is passed as input, and your JSONata outputs a combination of path parameters, query parameters, headers, and a body.

Input

The JSONata is passed the input as defined in the request schema:

{
   /* The request object as defined by the Request Schema */
}

Output

ASAPP expects the transformation to output the underlying API request made to the Endpoint specified in API Source.

{
    "pathParameters": {},
    "queryParameters": {},
    "headers": {},
    "body": {}
}

Field Name	Type	Description
pathParameters	Map <string, string>	These are key-value pairs to fill in the path as specified in your OpenAPI spec.
queryParameters	Map <string, string>	These are key-value pairs that will be added as query parameters. ?example-key=example-value
headers	Map <string, string>	These are key-value pairs to pass as headers. DO NOT provide authentication data here and use Authentication Methods to handle authentication.
body	Object	This is an object that will be sent as a JSON body in the API.

Response Interface

The response interface is the response fields exposed to GenerativeAgent (or any of ASAPP services) and the transformation logic to convert the underlying API response to the internal response.

The Response Schema is the JSON schema that is exposed to GenerativeAgent.

The Response Transformation is a JSONata transformation where the API response headers and body are passed as input, and your JSONata outputs a response that should match the response schema.

Input

ASAPP expects the response transformation to transform the raw API response into an output that matches the Response Schema.

{
    "clientApiCall": {
        "data":{
            /* JSON Body of the response. */
        }
    }
}

Field Name	Type	Description
clientApiCall.data	Object	An object of the body response the API.

Output

The output of the JSONata must match the JSON Schema.

Create an API Connection

To create an API Connection:

1. Navigate to GenerativeAgent > API Connections
2. Click “Create Connection”
3. Select an API spec or upload one if you haven’t yet.
4. Provide: a. Name of the API Connection b. Description of the Connection c. An endpoint from the spec.
5. You are taken to the API connection detail page where you can provide additional API Source connection information or edit the Request and Response interfaces.

After you have created the API connection, share the name with your colleague who is creating the Tasks and Functions.

API Versioning

Every update to an API Connection requires a version change. This is to ensure that no change can be made to an API connection that impacts a live function.

If you make a change to an API connection, the Function that references that API connection will need to be explicitly updated to point to the new version.

Testing transformations

When editing an API Connection’s API Source, Request, or Response transformations, you need to test the transformations using the testing pane.

While we only enforce a single test in order to save, we recommend you try several different possible values to ensure your transformations work correctly with real traffic.

Improving an API Connection for GenerativeAgent

To improve GenerativeAgent’s ability to understand and use your APIs, aim to make the internal request schema simple, use plain English, and flatter structure.

Additionally consider removing non-required fields and expose the bare minimum for the specific goal of the API Connection.

As an example scenario:

• You have a Task where users can inquire about their current balance.
• You have an account API that returns the balance amongst many other fields.
• You then create an API connection for “Get account balance” that uses the account API, but removes all response fields except the current balance.

Default API Spec Settings

You can set default information in an API spec. These default settings are used as a template for newly created API connections, copying those settings for all API connections created for that API spec.

You can make further changes to API connections as necessary.

You can also change the defaults and it will not change existing API connections, though the new defaults will be used on any new connections made with that Spec.

Example

This example is where you want to let a user update their name for a flight. The API Spec defines an endpoint which calls the following:

PUT /flight/[flightId]/passenger/[passengerId]
{
  "name": {
    "first": [Passenger FirstName],
    "last": [Passenger LastName]
  }
}

And then returns an object that matches the following:

{
  "id": "pax-12345",
  "flightId": "XZ2468",
  "updatedAt": "2024-10-04T14:30:00Z",
  "passenger": {
    "id": "PSGR-56789",
    "name": {
      "first": "John",
      "last": "Doe"
    },
    "seatAssignment": "14A",
    "checkedIn": true,
    "frequentFlyerNumber": "FF123456"
  },
  "status": "confirmed",
  "specialRequests": ["wheelchair", "vegetarian_meal"],
  "baggage": {
    "checkedBags": 1,
    "carryOn": 1
  }
}

Let’s define the configuration for the request and response.

Request Configuration

For the request, we’ll define a schema that GenerativeAgent can understand and provide a transformation to map it to the API’s expected format. Here’s how to set up the request configuration:

1. Request Schema:

{
  "type": "object",
  "properties": {
    "externalCustomerId": {"type": "string"},
    "passengerFirstName": {"type": "string"},
    "passengerLastName": {"type": "string"},
    "flightId": {"type": "string"}
  },
  "required": ["externalCustomerId", "passengerFirstName", "passengerLastName", "flightId"]
}

2. Request Transformation:

{
  "headers": {},
  "pathParameters": {
    "flightId": request.flightId,
    "passengerId": request.externalCustomerId
  },
  "queryParameters": {},
  "body": {
    "name": {
      "first": request.passengerFirstName,
      "last": request.passengerLastName
    }
  }
}

This transformation does the following:

• Maps the externalCustomerId to the passengerId path parameter
• Uses the flightId as a path parameter
• Constructs the request body with the passenger’s first and last name

To test this transformation, you can use the following sample request:

{
  "externalCustomerId": "CUST123",
  "passengerFirstName": "Johnson",
  "passengerLastName": "Doe",
  "flightId": "XZ2468"
}

This configuration simplifies the request for GenerativeAgent, allowing it to easily provide the necessary information for updating a passenger’s name on a flight.

Response Configuration

For the response, we’ll simplify the information returned to GenerativeAgent by confirming the status of the API call and returning a simple success indicator.

1. Response Schema:

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean"
    }
  },
  "required": ["success"]
}

2. Response Transformation:

{
  "success": $exists(clientApiCall.data.id) and 
             $exists(clientApiCall.data.passenger.name.first) and 
             $exists(clientApiCall.data.passenger.name.last) and 
             clientApiCall.data.status = "confirmed"
}

This transformation does the following:

• Checks if the response contains an id field
• Verifies that the passenger’s first and last name exist in the response
• Confirms that the status is “confirmed”
• Returns true if all these conditions are met, false otherwise

To test this transformation, you can use the following sample API response:

{
  "clientApiCall": {
    "data": {
      "id": "pax-12345",
      "flightId": "XZ2468",
      "updatedAt": "2024-10-04T14:30:00Z",
      "passenger": {
        "id": "PSGR-56789",
        "name": {
          "first": "John",
          "last": "Doe"
        },
        "seatAssignment": "14A",
        "checkedIn": true,
        "frequentFlyerNumber": "FF123456"
      },
      "status": "confirmed",
      "specialRequests": ["wheelchair", "vegetarian_meal"],
      "baggage": {
        "checkedBags": 1,
        "carryOn": 1
      }
    }
  }
}

This configuration simplifies the response for GenerativeAgent, allowing it to easily determine if the name update was successful without dealing with unnecessary details.

Next Steps

After creating API connections for your various functions and tasks, GenerativeAgent can now interact with APIs and do all the same things a live agent is capable of doing.

You may find it helpful to check out these other sections:

Previewer

Integrating GenerativeAgent

Connecting Your Knowledgebase