OpenAPI Toolset

Turn any OpenAPI 3 or Swagger 2 spec into callable agent tools with one import

Point an agent at a REST API’s spec and every operation becomes a tool it can call — no per-endpoint wrapper functions, no external MCP process.

Quick Start

1. Load a spec and start the agent

   Every operation in the spec becomes a tool the agent can call directly.

   import os
   from praisonaiagents import Agent
   from praisonaiagents.tools.openapi_toolset import OpenAPIToolset
   
   toolset = OpenAPIToolset(
       spec_url="https://api.example.com/openapi.json",
       auth={"type": "bearer", "token": os.environ["API_TOKEN"]},
   )
   
   agent = Agent(name="ops", tools=toolset.get_tools())
   agent.start("List the last 5 incidents and open a ticket for the top one")

2. Install httpx

   httpx is needed at call time.

   pip install httpx

   YAML specs also need PyYAML (already a dependency).

How It Works

get_tools() returns one callable OpenAPIOperation per spec operation. When the agent calls one, it builds the request, attaches auth headers, sends it with httpx, and returns the parsed JSON.

Loading a Spec

Provide the spec exactly one of three ways — otherwise a ValueError is raised.

Configuration Options

All constructor arguments are keyword-only.

Exactly one of spec_dict, spec_str, spec_url is required.

Methods

OpenAPIOperation

Each tool returned by get_tools() is an OpenAPIOperation.

Attributes: name, description, method, path, base_url, parameters, body_schema, body_param, input_schema, auth, header_provider, timeout.

Auth Shapes

The auth dict is keyed by type.

Safety Behaviour

The toolset refuses unsafe requests and never fetches arbitrary URLs while parsing.

Framework-injected kwargs are stripped on all paths — free-form, declared, and composed — so durable-execution metadata never leaks into a strict API.

Body Shapes

Every requestBody schema falls into one of three modes, decided in this order.

Framework-injected kwargs are dropped in every mode.

Common Patterns

Restrict the tool surface to read-only operations:

from praisonaiagents.tools.openapi_toolset import OpenAPIToolset

toolset = OpenAPIToolset(
    spec_url="https://api.example.com/openapi.json",
    tool_filter=lambda name, method, path: method.lower() == "get",
)

Namespace a spec when combining several on one agent:

stripe = OpenAPIToolset(
    spec_url="https://api.stripe.com/openapi.json",
    tool_name_prefix="stripe_",
)

Rotate auth per request:

def fetch_token() -> str:
    return "..."  # your token-refresh logic

toolset = OpenAPIToolset(
    spec_url="https://api.example.com/openapi.json",
    header_provider=lambda: {"Authorization": f"Bearer {fetch_token()}"},
)

Preview a request without calling the API:

tools = OpenAPIToolset(spec_url="https://api.example.com/openapi.json").get_tools()
request = tools[0].build_request(id="123")
print(request)   # {"method": ..., "url": ..., "headers": ...}

Call an operation whose body uses allOf — no special configuration:

from praisonaiagents import Agent
from praisonaiagents.tools.openapi_toolset import OpenAPIToolset

spec = {
    "openapi": "3.0.0",
    "servers": [{"url": "https://api.example.com"}],
    "paths": {"/pets": {"post": {
        "operationId": "createPet",
        "requestBody": {"content": {"application/json": {"schema": {
            "allOf": [
                {"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]},
                {"type": "object", "properties": {"age": {"type": "integer"}}},
            ],
        }}}},
    }}},
}

agent = Agent(name="pets", tools=OpenAPIToolset(spec_dict=spec).get_tools())
agent.start("Create a pet called Rex, age 3")

Both name and age are advertised to the model and forwarded to the API — a composed spec works with no extra wiring.

Force a base URL when the spec has a relative servers: entry:

from praisonaiagents.tools.openapi_toolset import OpenAPIToolset

toolset = OpenAPIToolset(
    spec_dict=my_spec,                   # servers: [{ url: "/v1" }]
    base_url="https://api.example.com",  # required — no spec_url to resolve against
    auth={"type": "bearer", "token": "..."},
)

OpenAPI Toolset vs MCP

Both expose external tools to an agent; reach for the toolset when the API already has a spec.

A workaround existed (MCP("npx -y @ivotoby/openapi-mcp-server ...")); the toolset removes the extra process and the npx dependency, and adds first-class tool_filter and tool_name_prefix.

Best Practices

Related