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 | | --format <format> | -f | Output format: ai-sdk, eve | ai-sdk | | --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

Generate tools for eve agents:

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

Generated Output

AI SDK Format (Default)

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 (kebab-case)
│   └── 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
• Kebab-case filenames — get-accounts.ts, post-accounts.ts

Eve Format

When using --format eve, the generator produces tools compatible with eve:

agent/tools/my-api/
├── accounts/
│   ├── get_accounts.ts    # One file per operation (snake_case)
│   └── post_accounts.ts
├── agents/
│   └── get_agents.ts
└── ...

• Snake_case filenames — get_accounts.ts, post_accounts.ts (eve requirement)
• Default export with defineTool — uses defineTool from eve/tools
• Standalone tools — each tool includes its own configuration with process.env access
• No shared types file — tools are self-contained for eve's discovery system

Usage in Code

AI SDK Format

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

Eve Format

For eve agents, generated tools are placed in your agent/tools/ directory and automatically discovered:

my-eve-agent/
├── agent/
│   ├── agent.ts
│   ├── instructions.md
│   └── tools/
│       └── my-api/
│           ├── accounts/
│           │   ├── get_accounts.ts
│           │   └── post_accounts.ts
│           └── agents/
│               └── get_agents.ts
└── package.json

Each tool uses defineTool from eve/tools and includes:

• Configuration via process.env for base URL and auth tokens
• A Zod input schema for type-safe parameters
• An async execute(input, ctx) function with access to eve's context
• Optional outputSchema for structured responses
• Full compatibility with eve's tool discovery and execution system

No imports needed — eve discovers and exposes tools automatically based on filename!

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