Generate Tools from an OpenAPI Spec

You have an API spec and you want agent tools. Forge reads OpenAPI v3 (or Swagger 2.0) definitions, extracts the operations you pick, and generates type-safe TypeScript capabilities with auth handling baked in. This walkthrough uses a Zendesk Support API spec as the running example.

Prerequisites

A valid OpenAPI v3 or Swagger 2.0 spec file (JSON or YAML)
The Svantic CLI installed (npm install -g @svantic/cli)

Step 1: List Available Operations

Before generating anything, inspect what the spec offers:

svantic forge tool --list zendesk-openapi.yaml

Output:

zendesk-openapi.yaml (OpenAPI 3.0.2 — Zendesk Support API)

  create_ticket        POST   /api/v2/tickets
  list_tickets         GET    /api/v2/tickets
  get_ticket           GET    /api/v2/tickets/{ticket_id}
  update_ticket        PUT    /api/v2/tickets/{ticket_id}
  delete_ticket        DELETE /api/v2/tickets/{ticket_id}
  add_comment          POST   /api/v2/tickets/{ticket_id}/comments
  list_users           GET    /api/v2/users
  search_users         GET    /api/v2/users/search
  ... (24 operations total)

Each line shows the generated tool name, HTTP method, and path. Tool names are derived from operationId when available, otherwise from the method and path.

Step 2: Generate Specific Tools

Pick the operations you need with --pick:

svantic forge tool --spec zendesk-openapi.yaml \
  --pick create_ticket,list_tickets,get_ticket,add_comment \
  --out ./tools/

This generates two files in ./tools/:

File	Contents
`zendesk.capabilities.ts`	One function per picked operation, with typed parameters and HTTP calls
`zendesk.triggers.ts`	Webhook/schedule trigger stubs (only if the spec defines callbacks or x-webhooks)

It also writes a zendesk.tool-spec.yaml — the intermediate Tool Spec that you can inspect, edit, and regenerate from.

Step 3: Review the Generated Code

The capabilities file exports one function per tool:

import { define_tool } from '@svantic/sdk/forge';

export const create_ticket = define_tool({
  name: 'create_ticket',
  description: 'Create a new support ticket.',
  parameters: {
    type: 'object',
    properties: {
      subject: { type: 'string', description: 'The subject line of the ticket' },
      body: { type: 'string', description: 'The initial comment/description' },
      priority: {
        type: 'string',
        description: 'Ticket priority: low, normal, high, or urgent',
        enum: ['low', 'normal', 'high', 'urgent'],
      },
      requester_email: { type: 'string', description: 'Email of the person filing the ticket' },
    },
    required: ['subject', 'body'],
  },
  auth: { type: 'bearer', env: 'ZENDESK_API_TOKEN' },
  execute: async (params, ctx) => {
    const response = await ctx.http.post('/api/v2/tickets', {
      ticket: {
        subject: params.subject,
        comment: { body: params.body },
        priority: params.priority ?? 'normal',
        requester: params.requester_email
          ? { email: params.requester_email }
          : undefined,
      },
    });
    return response.data;
  },
});

Step 4: Use the Tools in Your Agent

import express from 'express';
import { Agent } from '@svantic/sdk';
import { create_ticket, list_tickets, get_ticket, add_comment } from './tools/zendesk.capabilities';

const app = express();
app.use(express.json());

const agent = new Agent({
  name: 'zendesk-agent',
  description: 'Manages Zendesk support tickets.',
  public_url: 'https://zendesk.example.com',
});

agent.attach_tools([create_ticket, list_tickets, get_ticket, add_comment]);
agent.expose(app);

app.listen(4010, () => console.log('Zendesk agent ready'));

Programmatic Usage

Use the SDK directly instead of the CLI:

import { generate_from_file } from '@svantic/sdk/forge';

const result = await generate_from_file({
  spec_path: './zendesk-openapi.yaml',
  pick: ['create_ticket', 'list_tickets', 'get_ticket', 'add_comment'],
  output_dir: './tools/',
});

console.log(result.capabilities); // Array of generated tool definitions
console.log(result.tool_spec);    // The intermediate YAML as a parsed object

Listing operations programmatically

import { list_operations } from '@svantic/sdk/forge';

const ops = await list_operations('./zendesk-openapi.yaml');
for (const op of ops) {
  console.log(`${op.name}  ${op.method}  ${op.path}`);
}

Auth Detection

Forge reads the securitySchemes section of your OpenAPI spec and maps it to auth configuration automatically:

OpenAPI Security Scheme	Generated Auth Config
`type: http, scheme: bearer`	`{ type: 'bearer', env: '<DOMAIN>_API_TOKEN' }`
`type: apiKey, in: header`	`{ type: 'api_key', env: '<DOMAIN>_API_KEY', header: '<name>' }`
`type: http, scheme: basic`	`{ type: 'basic', env: '<DOMAIN>_USERNAME' }` + `<DOMAIN>_PASSWORD`
`type: oauth2`	`{ type: 'oauth2', env: '<DOMAIN>_CLIENT_ID' }` + related env vars

The env values are suggestions. Override them in the Tool Spec YAML or in the generated code.

Overriding auth at generation time

svantic forge tool --spec zendesk-openapi.yaml \
  --pick create_ticket \
  --auth-type bearer \
  --auth-env MY_ZENDESK_TOKEN \
  --out ./tools/

Swagger 2.0 Support

Forge accepts Swagger 2.0 specs. They are automatically converted to OpenAPI 3.0 internally before generation. The conversion handles:

definitions to components/schemas
basePath + host to servers[0].url
securityDefinitions to securitySchemes

If the automatic conversion produces unexpected results, convert your spec manually with a tool like swagger2openapi and pass the v3 file to Forge.

svantic forge tool --spec legacy-api-swagger.json --pick list_orders --out ./tools/

Filtering Operations

Beyond --pick, you can filter by tag or path prefix:

svantic forge tool --spec zendesk-openapi.yaml --tag tickets --out ./tools/

svantic forge tool --spec zendesk-openapi.yaml --path-prefix /api/v2/tickets --out ./tools/

Regenerating After Spec Changes

If the upstream API spec changes, regenerate from the updated file. Forge overwrites the capabilities and Tool Spec YAML but preserves any file named *.custom.ts in the output directory, so you can keep manual overrides safe.

svantic forge tool --spec zendesk-openapi-v2.yaml \
  --pick create_ticket,list_tickets,get_ticket,add_comment \
  --out ./tools/

Get Started

Build Agents

Deep Dive

Knowledge & Self-Learning

Security

Policies & Guardrails

Notifications & Alerts

Deploying Your Agents

Forge

Plugins

From openapi

Generate Tools from an OpenAPI Spec

Prerequisites

Step 1: List Available Operations

Step 2: Generate Specific Tools

Step 3: Review the Generated Code

Step 4: Use the Tools in Your Agent

Programmatic Usage

Listing operations programmatically

Auth Detection

Overriding auth at generation time

Swagger 2.0 Support

Filtering Operations

Regenerating After Spec Changes

​Generate Tools from an OpenAPI Spec

​Prerequisites

​Step 1: List Available Operations

​Step 2: Generate Specific Tools

​Step 3: Review the Generated Code

​Step 4: Use the Tools in Your Agent

​Programmatic Usage

​Listing operations programmatically

​Auth Detection

​Overriding auth at generation time

​Swagger 2.0 Support

​Filtering Operations

​Regenerating After Spec Changes

Generate Tools from an OpenAPI Spec

Prerequisites

Step 1: List Available Operations

Step 2: Generate Specific Tools

Step 3: Review the Generated Code

Step 4: Use the Tools in Your Agent

Programmatic Usage

Listing operations programmatically

Auth Detection

Overriding auth at generation time

Swagger 2.0 Support

Filtering Operations

Regenerating After Spec Changes