OpenAPI Universal Client

Overview

If an API publishes a spec (a menu of what it can do), this tool reads the menu and can call any operation on it. One tool that becomes whatever API your agent needs to reach — no custom integration code required.

How it works

Loads an OpenAPI 3.x spec from a URL or inline string (parsed once and cached). Two operations: 'list_operations' returns every operationId with its HTTP method, path, and parameter schema; 'invoke' calls a specific operationId with path/query/header/body parameters and an optional bearer token. Flagged DANGEROUS because any endpoint in the spec becomes reachable.

Example

When a user asks:

Create a new issue in our GitHub repo.

the agent calls the tool:

openapi_call(spec_url="https://api.github.com/openapi.json", operationId="issues/create", params={…})

and gets back: the response from GitHub's API — the newly created issue.

Configuration

Set these before calling the tool. Values marked required must be present or the tool call will fail.

spec_url (per-call) optional

URL to the OpenAPI 3.x spec (YAML or JSON). Cached per location. Preferred over inline spec.

spec (per-call) optional

Inline spec contents (YAML or JSON) as an alternative to spec_url.

bearer_token (per-call) optional

Optional bearer token passed as the Authorization header on invoke calls.

Use it in a workflow

Wire this tool into a SwarmAI crew. Use the YAML DSL for declarative workflows, or the Java builder API when you want full programmatic control.

YAML DSL

# api-gateway.yaml
name: api-gateway-crew
process: SEQUENTIAL

agents:
  - id: bot
    role: Integration Bot
    goal: Call any REST API described by an OpenAPI spec
    tools:
      - openapi_call

tasks:
  - id: api-gateway-task
    agent: bot
    description: Using the GitHub OpenAPI spec, create a new issue in acme/webapp titled 'Broken link on homepage'.

Java

import ai.intelliswarm.swarmai.agent.Agent;
import ai.intelliswarm.swarmai.task.Task;
import ai.intelliswarm.swarmai.swarm.Swarm;
import ai.intelliswarm.swarmai.swarm.SwarmOutput;
import ai.intelliswarm.swarmai.process.ProcessType;
import ai.intelliswarm.swarmai.tool.integrations.OpenApiToolkit;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.beans.factory.annotation.Autowired;

@Autowired ChatClient chatClient;
@Autowired OpenApiToolkit openApiToolkit;

Agent bot = Agent.builder()
    .role("Integration Bot")
    .goal("Call any REST API described by an OpenAPI spec")
    .chatClient(chatClient)
    .tool(openApiToolkit)
    .build();

Task botTask = Task.builder()
    .description("Using the GitHub OpenAPI spec, create a new issue in acme/webapp titled 'Broken link on homepage'.")
    .agent(bot)
    .build();

SwarmOutput result = Swarm.builder()
    .agent(bot)
    .task(botTask)
    .process(ProcessType.SEQUENTIAL)
    .build()
    .kickoff();

What it's good for

Real scenarios where agents put this tool to work.

Discover a partner API's operations before the agent invokes them

Drive a bespoke internal service without writing a dedicated tool

One-off integration with Stripe, GitHub, or any public REST API via its spec

Generate agent-readable API documentation with list_operations for prompt grounding

Source

Implementation lives at swarmai-tools/src/main/java/ai/intelliswarm/swarmai/tool/integrations/OpenApiToolkit.java in the swarm-ai repository.

Open openapi_call on GitHub →