HomeGuidesAPI ReferenceRelease notes
Log In
Guides

OpenAPI tool

Suggest Edits

The OpenAPI tool is designed to integrate seamlessly with any external API that supports an OpenAPI schema. This functionality enables you to enhance your application's capabilities by leveraging a variety of external resources and services. By connecting with these APIs, you can enrich your models with a broader array of data inputs and functionalities, or include external AI agents in your app, thereby enriching your model's knowledge and expanding its potential. Learn more about the tool concept here

Here’s how you can do it:

🚧

Important Considerations!

  • OpenAPI Version Compatibility: The OpenAPI tool is compatible only with OpenAPI versions 3.0 and above.
  • Schema Format: The OpenAPI tool supports schemas only in JSON format.
  • Supported Routes: Only GET and POST request methods are supported by the OpenAPI tool.
  • Authorization: Currently, SWE supports APIs that use either Bearer Token authentication or require no authorization.

📘

Additional information

To read more on OpenAPI specifications follow the following link

Using the UI

Step 1: Add the DB tool

Click on the "+ Tool" button, and then OpenAPI tool" start setting up the database connection.

Step 2: Configure the tool

  • Assign a meaningful name to the tool. This name will help the model understand the context in which the data will be used.
  • Add a description: Provide a detailed description of the API and its purpose. This information helps the model contextualize the data, influences the prompts generated by the system, and guides the model on when to effectively utilize this tool.
  • Add OpenAPI schema: Upload a JSON-based OpenAPI schema that includes all the routes you want your application to access.
  • Select authentication method: Select the authentication method and supply the relevant key if needed.

Usage example

This JSON represents an OpenAPI schema for an API, which enables you to input an IP address and retrieve the corresponding country. To utilize this schema, simply copy and paste it into the OpenAPI schema section of your tool. 

{
  "info": {
    "title": "IP to Country API",
    "version": "1.0.0",
    "description": "A simple API to translate IP addresses to country codes."
  },
  "paths": {
    "/{ip}": {
      "get": {
        "summary": "Get country code from IP address",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ip": {
                      "type": "string",
                      "format": "ipv4",
                      "example": "9.9.9.9"
                    },
                    "country": {
                      "type": "string",
                      "example": "US"
                    }
                  }
                }
              }
            },
            "description": "Successful response"
          },
          "400": {
            "description": "Bad request (invalid IP address format)"
          },
          "404": {
            "description": "IP address not found"
          },
          "500": {
            "description": "Internal server error"
          }
        },
        "parameters": [
          {
            "in": "path",
            "name": "ip",
            "schema": {
              "type": "string",
              "format": "ipv4"
            },
            "required": true,
            "description": "The IP address to get the country code for."
          }
        ],
        "description": "Returns the country code associated with the provided IP address."
      }
    }
  },
  "openapi": "3.0.3",
  "servers": [
    {
      "url": "https://api.country.is"
    }
  ]
}

Using the SDK

To begin crafting your OpenAPI tool with the help of the SDK, refer to the provided code snippet below as an invaluable guide. This snippet will lead you through integrating the OpenAPI tool into your workflow.


from superwise_api.models.tool.tool import ToolDef, ToolConfigOpenAPI, ToolType
from superwise_api.models.application.application import AdvancedAgentConfig

openapi_tool = ToolDef(
    name="My tool name",
    description="Describe this tool for the LLM",
    config=ToolConfigOpenAPI(
        type=ToolType.OPENAPI,
        openapi_schema= openapi_schema,
        # if no authentication is required, then authentication=None
        authentication={
            "type": "Bearer",
            "token": "your_token_here",
        },
    ),
)

updated_app = sw.application.put(str(app.id), 
                                 llm_model=model, 
                                 prompt=None, 
                                 additional_config=AdvancedAgentConfig(tools=[openapi_tool]),
                                 name="My application name")

Overriding Authentication header when using the API

If the authentication methods we provide ( None / Bearer token) doesn't match the authentication method you use, you can override the header by using:

payload = {
    "input": "user input here",
    "chat_history": [],
    "custom_headers": {
        "Authorization": "YOUR AUTH METHOD HERE"
    }
}

For example:

import requests

url = f"https://api.staging.superwise.ai/v1/app-worker/{app.id}/v1/ask"
token ='TOKEN'

payload = {
    "input": "user input here",
    "chat_history": [],
    "custom_headers": {
        "Authorization": f"Bearer {token}"
    }
}

headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "x-api-token": "Applicatoin api token"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Updated 2 months ago