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

# Forge

# No Code with Forge

The fastest way to create agents and tools. Forge generates production-ready code from API specs or plain English — in seconds.

<img src="https://mintcdn.com/svantic/DQEVJ_RnVW5_l6gu/images/forge-flow.svg?fit=max&auto=format&n=DQEVJ_RnVW5_l6gu&q=85&s=a2656f29128fef9b8c9e87b49278625c" alt="Forge Flow" width="900" height="580" data-path="images/forge-flow.svg" />

All paths go through the same intermediate format — the **Tool Spec** — which you can edit, validate, and combine before generating code.

## Generate a Tool Spec

Pick any source. Forge produces a `.tool-spec.yaml` you can inspect, edit, and version control.

#### OpenAPI / Swagger

List available operations, then generate:

```bash theme={null}
# See what's available
svantic forge tool --list zendesk-openapi.yaml

# Generate spec for selected operations
svantic forge tool --spec zendesk-openapi.yaml --pick create_ticket,list_tickets --out ./tools/
```

Forge reads `securitySchemes` and maps auth automatically:

| Scheme             | Generated env                       |
| ------------------ | ----------------------------------- |
| HTTP bearer        | Bearer token env                    |
| `apiKey` in header | `api_key` + header name             |
| HTTP basic         | Username/password env pair          |
| OAuth2             | Client ID, secret, and related envs |

Override with `--auth-type` or `--auth-env`. Swagger 2.0 is supported and converted internally.

Filter operations with `--pick`, `--tag <name>`, or `--path-prefix /api/v2/tickets`.

#### Natural Language

Describe what you need. Optionally point to API docs for accuracy:

```bash theme={null}
# Basic prompt
svantic forge tool --prompt "Monitor Datadog alerts and query metrics" --out ./tools/

# With documentation for better accuracy
svantic forge tool --prompt "Monitor Datadog alerts" --docs https://docs.datadog.com/api --out ./tools/
```

Uses Gemini by default (`GOOGLE_API_KEY`). Override with `--model gemini-2.5-pro`.

The CLI shows proposed tools for review: **Y** (accept) / **n** (reject) / **edit**.

## Create an Agent

Combine one or more Tool Specs into a deployable agent.

#### Standalone project

Generates a complete project with `server.ts`, `package.json`, `Dockerfile`, and `.env.template`:

```bash theme={null}
svantic forge agent --name ops-bot --tools zendesk.yaml,billing.yaml,slack.yaml --standalone
```

#### Embedded in existing app

Same command without `--standalone` writes capability modules into your existing codebase:

```bash theme={null}
svantic forge agent --name ops-bot --tools zendesk.yaml --out ./src/agents/
```

#### Handling name collisions

If multiple specs define the same tool name, Forge fails fast. Resolve with:

* `--prefix domain` → `zendesk_create_ticket`, `jira_create_ticket`
* `--rename zendesk:create_ticket=create_zendesk_ticket`
* Edit the `.tool-spec.yaml` directly

## Conversational Generation

The Svantic terminal runs the same workflow interactively:

```
> Read my source code in src/monitoring/ and propose tools
> Remove health_check, rename get_metrics to fetch_metrics
> Now generate the tools
> Compose these with my zendesk tools into monitoring-bot
```

## Tool Spec Reference

The Tool Spec is a YAML file that describes your tools. Forge generates it, but you can edit it manually to customize before generating code.

#### Tool Spec Schema

<ParamField body="domain" type="string" required>
  Namespace for your tools. Used as a prefix when combining multiple specs (e.g., zendesk\_create\_ticket).
</ParamField>

<ParamField body="version" type="string">
  Spec version for tracking changes. Default: `1.0`
</ParamField>

<ParamField body="base_url" type="string">
  API base URL. All tool paths are relative to this. Example: `https://your-subdomain.zendesk.com/api/v2`
</ParamField>

<ParamField body="auth" type="object">
  Authentication configuration.

  <Expandable title="properties">
    <ParamField body="type" type="string">
      Authentication method. Allowed values: `bearer`, `api_key`, `basic`, `oauth2`, `none`
    </ParamField>

    <ParamField body="env" type="string">
      Environment variable name for the token/key. Example: `ZENDESK_API_TOKEN`
    </ParamField>

    <ParamField body="header" type="string">
      Header name (for api\_key type). Example: `X-API-Key`
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tools" type="array" required>
  The capabilities your agent will have.

  <Expandable title="items">
    <ParamField body="name" type="string" required>
      Tool name in snake\_case. The mesh calls this capability by name. Example: `create_ticket`
    </ParamField>

    <ParamField body="description" type="string" required>
      What this tool does. The LLM reads this to decide when to use it. Example: `Create a new support ticket in Zendesk`
    </ParamField>

    <ParamField body="method" type="string" required>
      HTTP method. Allowed values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
    </ParamField>

    <ParamField body="path" type="string" required>
      API path, relative to base\_url. Use \{param} for path parameters. Example: `/tickets/{ticket_id}`
    </ParamField>

    <ParamField body="params" type="object">
      Path and query parameters. Keys are parameter names. Each value is an object with:

      <Expandable title="properties">
        <ParamField body="type" type="string">
          Allowed values: `string`, `integer`, `number`, `boolean`
        </ParamField>

        <ParamField body="required" type="boolean">
          Whether the parameter is required.
        </ParamField>

        <ParamField body="description" type="string">
          Parameter description.
        </ParamField>

        <ParamField body="default" type="string">
          Default value.
        </ParamField>

        <ParamField body="enum" type="array">
          Allowed values for this parameter.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="body" type="object">
      JSON body fields. Keys are field names. Each value is an object with:

      <Expandable title="properties">
        <ParamField body="type" type="string">
          Allowed values: `string`, `integer`, `number`, `boolean`, `object`, `array`
        </ParamField>

        <ParamField body="required" type="boolean">
          Whether the field is required.
        </ParamField>

        <ParamField body="description" type="string">
          Field description.
        </ParamField>

        <ParamField body="default" type="string">
          Default value.
        </ParamField>

        <ParamField body="enum" type="array">
          Allowed values for this field.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="triggers" type="array">
  Events that fire prompts into the mesh.

  <Expandable title="items">
    <ParamField body="type" type="string" required>
      Trigger type. Allowed values: `webhook` (HTTP callback), `schedule` (cron), `emit` (in-process event), `queue` (message queue), `file` (file watcher)
    </ParamField>

    <ParamField body="event" type="string">
      Event name for identification. Example: `ticket_created`
    </ParamField>

    <ParamField body="path" type="string">
      Webhook endpoint path (for webhook type). Example: `/webhooks/zendesk`
    </ParamField>

    <ParamField body="cron" type="string">
      Cron expression (for schedule type). Example: `0 9 * * MON-FRI`
    </ParamField>

    <ParamField body="prompt" type="string" required>
      The prompt sent to the mesh when this trigger fires. Use double-brace placeholders for dynamic values.
    </ParamField>
  </Expandable>
</ParamField>

#### Example

```yaml theme={null}
domain: zendesk
version: "1.0"
base_url: https://your-subdomain.zendesk.com/api/v2

auth:
  type: bearer
  env: ZENDESK_API_TOKEN

tools:
  - name: create_ticket
    description: Create a new support ticket
    method: POST
    path: /tickets
    body:
      subject:
        type: string
        required: true
      priority:
        type: string
        enum: [low, normal, high, urgent]
        default: normal

triggers:
  - type: webhook
    event: ticket_created
    path: /webhooks/zendesk
    prompt: "New ticket: {{subject}}. Triage it."
```

#### Validate and regenerate

```bash theme={null}
# Check for errors without generating
svantic forge tool --validate my-spec.yaml

# Regenerate code after editing the spec
svantic forge tool --spec my-spec.yaml --out ./tools/
```