Skip to main content

​
Prerequisites

You need a Smithers project and an OpenAPI 3.0+ spec. The spec can be a JSON file, a YAML file, a URL, or a plain JavaScript object.

​
Install

No extra dependencies. OpenAPI tools are built into smithers-orchestrator.

​
Load a Spec and Create Tools

import { createOpenApiTools } from "smithers-orchestrator";

const tools = await createOpenApiTools("./petstore.json", {
  baseUrl: "https://api.petstore.example.com",
  auth: { type: "bearer", token: process.env.PETSTORE_TOKEN! },
});

console.log(Object.keys(tools));
// ["listPets", "createPet", "getPet"]
Each key is the operationId from the spec. Each value is an AI SDK tool().

​
Use Tools in a Workflow

import { Workflow, Task, AnthropicAgent } from "smithers-orchestrator";
import { createOpenApiTools } from "smithers-orchestrator";

const petTools = await createOpenApiTools("./petstore.json", {
  baseUrl: "https://api.petstore.example.com",
  auth: { type: "bearer", token: process.env.PETSTORE_TOKEN! },
});

const agent = new AnthropicAgent({
  model: "claude-sonnet-4-20250514",
  tools: petTools,
});

export default (
  <Workflow>
    <Task id="list-pets" agent={agent}>
      List all available pets and summarize them.
    </Task>
  </Workflow>
);

​
Filter Operations

// Only expose read operations
const readTools = await createOpenApiTools("./petstore.json", {
  include: ["listPets", "getPet"],
});

// Expose everything except destructive operations
const safeTools = await createOpenApiTools("./petstore.json", {
  exclude: ["deletePet"],
});

​
Single Tool

import { createOpenApiTool } from "smithers-orchestrator";

const listPets = await createOpenApiTool("./petstore.json", "listPets", {
  baseUrl: "https://api.petstore.example.com",
});

​
Preview Tools from CLI

smithers openapi list ./petstore.json
Output: 
  listPets — List all pets
  createPet — Create a pet
  getPet — Get a pet by ID

  3 tool(s) from spec

​
Authentication Options

// Bearer token
await createOpenApiTools(spec, {
  auth: { type: "bearer", token: "sk-..." },
});

// Basic auth
await createOpenApiTools(spec, {
  auth: { type: "basic", username: "admin", password: "secret" },
});

// API key in header
await createOpenApiTools(spec, {
  auth: { type: "apiKey", name: "X-API-Key", value: "key123", in: "header" },
});

// API key in query string
await createOpenApiTools(spec, {
  auth: { type: "apiKey", name: "api_key", value: "key123", in: "query" },
});

// Custom headers
await createOpenApiTools(spec, {
  headers: { "X-Request-Id": "abc123" },
});

​
Name Prefixes

When combining tools from multiple specs, use namePrefix to avoid collisions: 
const petTools = await createOpenApiTools(petSpec, { namePrefix: "pet_" });
const orderTools = await createOpenApiTools(orderSpec, { namePrefix: "order_" });

const allTools = { ...petTools, ...orderTools };