> ## Documentation Index
> Fetch the complete documentation index at: https://docs.svantic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# From openapi

# 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:

```bash theme={null}
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`:

```bash theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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

```typescript theme={null}
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

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
svantic forge tool --spec zendesk-openapi-v2.yaml \
  --pick create_ticket,list_tickets,get_ticket,add_comment \
  --out ./tools/
```