Skip to main content

​
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/:
FileContents
zendesk.capabilities.tsOne function per picked operation, with typed parameters and HTTP calls
zendesk.triggers.tsWebhook/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

Register the generated capabilities with an 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 SchemeGenerated 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/