agent-tool-generator

A CLI tool that generates type-safe AI SDK tools from OpenAPI 3.x and Swagger 2.0 specifications. Point it at a spec and get one tool per operation, complete with Zod schemas and auth handling — ready to plug into any AI SDK agent.

Installation

pnpm add agent-tool-generator

Quick Start

pnpm dlx agent-tool-generator \
  -i ./swagger.json \
  -o ./src/tools/my-api \
  -n MyApi

This reads swagger.json, detects whether it's Swagger 2.0 or OpenAPI 3.x, and writes generated tools to src/tools/my-api/.

If the package is installed in your project, you can also run:

pnpm exec agent-tool-generator \
  -i ./swagger.json \
  -o ./src/tools/my-api \
  -n MyApi

CLI Options

| Flag | Short | Description | Default | | --- | --- | --- | --- | | --input <source> | -i | OpenAPI/Swagger spec source: local path or http(s) URL (JSON/YAML) | required | | --output <dir> | -o | Output directory for generated files | required | | --name <name> | -n | API name used for type names (e.g. SentinelOne) | required | | --endpoint <name> | -e | Only generate tools for endpoint paths containing this value (e.g. users) | | | --strip-prefix <prefix> | | Path prefix to strip when deriving tool names | | | --emit-jsdoc | | Emit JSDoc comments in generated tool files with required input/output details | false | | --auth-type <type> | | Auth type: apiKey, bearer, basic | apiKey | | --auth-header <name> | | Auth header name | Authorization | | --auth-prefix <prefix> | | Auth value prefix | Bearer | | --auth-in <location> | | Auth location: header, query | header | | --help | -h | Show help | |

Filter by endpoint path:

pnpm dlx agent-tool-generator \
  -i ./swagger.json \
  -o ./src/tools/my-api \
  -n MyApi \
  -e users

Generated Output

Given a spec, the generator produces:

src/tools/my-api/
├── _types.ts              # Shared options type (baseUrl, auth)
├── accounts/
│   ├── get-accounts.ts    # One file per operation
│   └── post-accounts.ts
├── agents/
│   └── get-agents.ts
└── ...

• One file per operation — each exports a tool factory function
• Grouped by tag — operations are organized into subdirectories by their first OpenAPI tag
• Direct file imports — barrel index.ts files are not generated

Usage in Code

import { getAccounts } from "./tools/my-api/accounts/get-accounts.js";
import { postAccounts } from "./tools/my-api/accounts/post-accounts.js";

const tools = {
  getAccounts: getAccounts({ baseUrl: "https://api.example.com", apiToken: API_TOKEN }),
  postAccounts: postAccounts({ baseUrl: "https://api.example.com", apiToken: API_TOKEN }),
};

Each generated tool is compatible with the AI SDK tool() interface and includes:

• A Zod input schema derived from the spec's path, query, and body parameters
• A description pulled from the operation's summary/description
• An execute function that makes the HTTP request with proper auth
• Optional JSDoc blocks (--emit-jsdoc) that document required input and output contracts

Supported Specs

• Swagger 2.0 — auto-detected via "swagger": "2.x" or the presence of definitions
• OpenAPI 3.x — auto-detected via "openapi": "3.x"

Specs can be JSON or YAML, from a local file or a remote http:// / https:// URL.

Peer Dependencies

• ai ^5.0.0
• zod ^4.0.0

Scripts

| Script | Description | | --- | --- | | pnpm generate | Run the local TypeScript CLI (repo development) | | pnpm build | Build the package with tsup | | pnpm test | Run the package's configured test command |

License

ISC