OpenAPI Tools API

Hand these factories an OpenAPI 3.x spec and they hand back AI SDK tools, one per operation, with Zod input schemas converted from the spec’s JSON schemas and an execute(args) that performs the HTTP call. Drop the result straight into an agent’s tools. Each operation’s summary / description becomes the tool description, so the agent already knows what each call does.

import {
  createOpenApiTools,
  createOpenApiToolsSync,
  createOpenApiTool,
  createOpenApiToolSync,
  listOperations,
} from "smithers-orchestrator";

The async factories (createOpenApiTools, createOpenApiTool) fetch URL specs. The *Sync variants take only an object or a local file path; they do not fetch URLs. Pick async when the spec lives behind an HTTP URL.

createOpenApiTools

Build a record of tools from an entire spec, keyed by operationId. Async, so it can load a spec from a URL.

function createOpenApiTools(
  input: string | OpenApiSpec,
  options?: OpenApiToolsOptions,
): Promise<Record<string, Tool>>;

input

string | OpenApiSpec

required

The spec as a parsed object, a file path, an HTTP URL, or raw JSON/YAML text.

options

OpenApiToolsOptions

Auth, filtering, base URL, and per-operation curation.

Show OpenApiToolsOptions

baseUrl

string

Override the request base URL. Defaults to the spec’s first servers[].url.

headers

Record<string, string>

Static headers merged into every request.

auth

OpenApiAuth

Authentication applied to every request. See Types.

include

string[]

Allowlist of operationIds. Only listed operations become tools.

exclude

string[]

Blocklist of operationIds. If both include and exclude are set, exclude wins.

namePrefix

string

Prefix added to generated tool names. Does not change the operationId used for filtering.

operations

Record<string, false | OperationCuration>

Per-operation curation keyed by the original operationId. Set an entry to false or { include: false } to skip it, name to rename the tool, description to replace the agent-facing text, and responseExamples to append concrete response shapes to the description.

Promise<Record<string, Tool>>

object

A record of AI SDK tools keyed by operationId (or the curated name).

import { ToolLoopAgent } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { createOpenApiTools } from "smithers-orchestrator";

const tools = await createOpenApiTools("https://api.example.com/openapi.json", {
  baseUrl: "https://api.example.com",
  auth: { type: "bearer", token: process.env.API_TOKEN! },
  include: ["listPets", "getPetById"],
});

const agent = new ToolLoopAgent({ model: anthropic("claude-fable-5"), tools });

Source createOpenApiTools.js · OpenApiToolsOptions.ts · Tests tool-factory.test.js · See also OpenAPI tools, Tools

createOpenApiToolsSync

Synchronous createOpenApiTools. Accepts only a spec object or a local file path, never a URL. Use it when you can resolve the spec on disk at build time.

function createOpenApiToolsSync(
  input: string | OpenApiSpec,
  options?: OpenApiToolsOptions,
): Record<string, Tool>;

input

string | OpenApiSpec

required

A parsed spec object, a local file path, or raw JSON/YAML text. URLs are not fetched.

options

OpenApiToolsOptions

Identical to createOpenApiTools.

Record<string, Tool>

object

A record of AI SDK tools keyed by operationId.

const tools = createOpenApiToolsSync("./petstore.json", {
  exclude: ["deletePet"],
});

Source createOpenApiToolsSync.js · Tests tool-factory.test.js · See also OpenAPI tools

createOpenApiTool / createOpenApiToolSync

Build a single tool from one operation, selected by operationId. Same options as the bulk factories; the only extra argument is the operationId. createOpenApiTool is async (fetches URL specs); createOpenApiToolSync is synchronous and object/file-only.

function createOpenApiTool(
  input: string | OpenApiSpec,
  operationId: string,
  options?: OpenApiToolsOptions,
): Promise<Tool>;

function createOpenApiToolSync(
  input: string | OpenApiSpec,
  operationId: string,
  options?: OpenApiToolsOptions,
): Tool;

input

string | OpenApiSpec

required

The spec. createOpenApiTool accepts a URL; createOpenApiToolSync does not.

operationId

string

required

The operationId of the operation to turn into a tool.

options

OpenApiToolsOptions

Same shape as createOpenApiTools. include / exclude are ignored here since one operation is named directly.

Tool

object

A single AI SDK tool. createOpenApiTool returns a Promise<Tool>.

const getPet = await createOpenApiTool("./petstore.json", "getPetById", {
  auth: { type: "apiKey", name: "X-API-Key", in: "header", value: KEY },
});

Source createOpenApiTool.js · createOpenApiToolSync.js · Tests tool-factory.test.js · See also Tools

listOperations

Introspect a spec without building any tools. Returns one entry per operation, useful for auditing what an agent would be able to call before wiring it up.

function listOperations(input: string | OpenApiSpec): Array<{
  operationId: string;
  method: string;
  path: string;
  summary: string;
}>;

input

string | OpenApiSpec

required

A parsed spec object, a local file path, or raw JSON/YAML text.

Array<OperationSummary>

array

One entry per operation.

Show OperationSummary

operationId

string

The operation’s operationId, the key tools are generated under.

method

string

HTTP method (get, post, put, delete, patch).

path

string

The path template, e.g. /pets/{id}.

summary

string

The operation’s summary, or an empty string when absent.

for (const op of listOperations("./petstore.json")) {
  console.log(`${op.method.toUpperCase()} ${op.path} → ${op.operationId}`);
}

The same preview is available from the CLI:

bunx smithers-orchestrator openapi list ./api/openapi.yaml

Source listOperations.js · Tests spec-parser.test.js · See also OpenAPI tools

Types

OpenApiAuth, OpenApiSpec, and OpenApiToolsOptions are exported from smithers-orchestrator. Tool is the AI SDK tool type from the ai package.

OpenApiAuth

Applied to every request. A discriminated union on type.

OpenApiAuth

union

Show type: "apiKey"

name

string

required

Header or query-parameter name carrying the key.

value

string

required

The API key value.

"header" | "query"

required

Where to place the key.

Show type: "bearer"

token

string

required

Sent as Authorization: Bearer <token>.

Show type: "basic"

username

string

required

Basic-auth username.

password

string

required

Basic-auth password.

import type { OpenApiAuth } from "smithers-orchestrator";

const apiKey: OpenApiAuth = { type: "apiKey", name: "X-API-Key", in: "header", value: KEY };
const bearer: OpenApiAuth = { type: "bearer", token: TOKEN };
const basic: OpenApiAuth = { type: "basic", username: USER, password: PASS };

OpenApiSpec

The parsed OpenAPI 3.x document shape accepted as an object input. Most callers pass a file path or URL string instead and let the loader parse it, but you can import the type to construct or narrow a spec yourself.

import type { OpenApiSpec } from "smithers-orchestrator";

type OpenApiSpec = {
  openapi: string;
  info: { title: string; version: string; description?: string };
  servers?: Array<{ url: string; description?: string }>;
  paths: Record<string, OpenApiPathItem>;
  components?: { schemas?: Record<string, OpenApiSchemaObject>; /* ... */ };
};

See the Types reference for the full OpenApiSpec, OpenApiPathItem, and OpenApiSchemaObject shapes. Source OpenApiAuth.ts · OpenApiSpec.ts · Tests spec-parser.test.js · See also Types, OpenAPI tools

For request/response handling, filtering semantics, observability metrics, and current limitations (cookie params, non-JSON bodies, Swagger 2.0), see the OpenAPI tools concept. For wiring tools into agents, see Tools.

​createOpenApiTools

​createOpenApiToolsSync

​createOpenApiTool / createOpenApiToolSync

​listOperations

​Types

​OpenApiAuth

​OpenApiSpec

createOpenApiTools

createOpenApiToolsSync

createOpenApiTool / createOpenApiToolSync

listOperations

Types

OpenApiAuth

OpenApiSpec