Introduction

• playground  You can see the demo code on the playground.

This tutorial guides you through setting up a fully functional Swagger Agent using Agentica. With the following code block, you can create an agent that interacts with a Swagger-defined API—such as the Pet Store API—powered by OpenAI’s GPT model. By providing a Swagger (OpenAPI) document, the agent automatically integrates all the API functions defined therein, and the connection property specifies the actual host for API requests.

The Complete Swagger Agent

First, install the required packages:

npm install @samchon/openapi

Then, add the following code to your project:

import { Agentica, assertHttpLlmApplication } from "@agentica/core";
import dotenv from "dotenv";
import OpenAI from "openai";
 
dotenv.config();
 
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
 
export const SwaggerAgent = async () =>
  new Agentica({
    model: "chatgpt",
    vendor: {
      api: openai,
      model: "gpt-4o-mini",
    },
    controllers: [
      {
        name: "PetStore", // Name of the connector (can be any descriptive name)
        protocol: "http", // Indicates an HTTP-based connector
        application: assertHttpLlmApplication({
          // Convert the Swagger JSON document to an OpenAPI model for Agentica.
          document: await fetch(
            "https://petstore.swagger.io/v2/swagger.json",
          ).then((r) => r.json()),
          model: "chatgpt",
        }),
        connection: {
          // This is the actual API host where the API requests will be sent.
          host: "https://petstore.swagger.io/v2",
          headers: {
            Authorization: "Bearer *****",
          },
        },
      },
    ],
  });

Swagger API Setup

Before running your agent, ensure you have a valid OpenAPI (Swagger) document. In this example, the agent fetches a Swagger JSON from a remote URL and converts it using OpenApi.convert. The connection property specifies the host where API requests should be directed, in this case, https://petstore.swagger.io/v2.

What This Does

With this configuration, the Swagger Agent can:

• Interact with a Swagger API: By supplying the Swagger document, all the API functions defined in the document (for example, the Pet Store API functions) are automatically integrated.
• Leverage GPT for API Interactions: Use OpenAI’s GPT model to interpret natural language queries and map them to corresponding API calls.
• Maintain Type Safety: Benefit from Agentica’s strong typing to ensure that your API interactions are predictable and secure.
• Streamline API Testing and Integration: Quickly test and interact with your API using natural language, with the Swagger document serving as the source of truth for available endpoints and methods.

Running the Agent

1. Set Up Environment Variables:
   Create or update your .env file with the following variable:

   OPENAI_API_KEY=your-openai-api-key

2. Run the Code:
   Import and invoke SwaggerAgent() in your application. The agent will:

   • Fetch and convert the Swagger document.
   • Establish a connection with the API host defined in the connection property.
   • Allow you to interact with the API through natural language queries.

Use Case Example

Imagine asking the agent:

“Find all available pets in the store.”

The agent processes your query by matching it to the corresponding API endpoint defined in the Swagger document, sends the request to https://petstore.swagger.io/v2, and then relays the API response back in a human-readable format.

Security Note

Warning:
This example is provided for demonstration purposes only. Ensure that you handle your API keys securely and do not expose them in production environments without proper security measures.