Skip to main content

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.

Write Your Agent

Build an agent from scratch with full control over every capability.
Forge generates agent code from an API spec, TypeScript source, or plain English — in seconds.

Quick Start

A minimal working agent:
import { Agent } from '@svantic/sdk';

const agent = new Agent({
  name: 'ticket-agent',
  description: 'Manages support tickets — lookup, creation, and status updates.',
  port: 4000,
  mesh: {
    client_id: process.env.SAVANT_CLIENT_ID!,
    client_secret: process.env.SAVANT_CLIENT_SECRET!,
  },
});

agent.define_capability({
  name: 'get_ticket',
  description: 'Look up a support ticket by its ID.',
  parameters: {
    type: 'object',
    properties: {
      ticket_id: { type: 'number', description: 'The ticket ID' },
    },
    required: ['ticket_id'],
  },
  handler: async (args) => {
    const ticket = await db.find(args.ticket_id);
    return { id: ticket.id, subject: ticket.subject, status: ticket.status };
  },
});

await agent.start();

Agent Configuration

name
string
required
Agent identity in the mesh. Other agents and the dashboard see this name.
description
string
required
What this agent does. The mesh LLM reads this to decide when to route tasks to your agent. Be specific.
port
number
Port for the HTTP server. The mesh calls your agent at this port to invoke capabilities.
url
string
Full URL if you’re not using port (e.g., behind a reverse proxy).
mesh
object
Credentials for mesh connection. Without this, the agent runs standalone (useful for testing).
version
string
default:"1.0.0"
Agent version shown in the dashboard.
instructions
string
System prompt for Smart Agents. Makes the agent reason about which capabilities to call.
llm
object
LLM configuration for Smart Agents.

Capabilities

A capability is a single thing your agent can do.
name
string
required
Capability name in snake_case. The mesh calls this by name.
description
string
required
What this capability does. The LLM reads this to decide when to use it. Be specific about inputs and outputs.
parameters
object
required
JSON Schema defining the inputs. The LLM constructs arguments from natural language based on this schema.
handler
function
required
Async function (args, context) => result. Executes the capability and returns a result or throws an error.
agent.define_capability({
  name: 'create_ticket',
  description: 'Create a new support ticket. Returns the ticket ID.',
  parameters: {
    type: 'object',
    properties: {
      subject: { type: 'string', description: 'Ticket subject line' },
      body: { type: 'string', description: 'Ticket description' },
      priority: { type: 'string', enum: ['low', 'normal', 'high', 'urgent'] },
    },
    required: ['subject', 'body'],
  },
  handler: async (args) => {
    const ticket = await db.create(args);
    return { id: ticket.id, status: 'created' };
  },
});

Starting and Stopping

await agent.start();

process.on('SIGTERM', () => agent.stop());
start() creates an HTTP server, mounts A2A endpoints, and connects to the mesh.

Tool Agent vs Smart Agent

By default, your agent is a Tool Agent — the mesh decides which capability to call. Add instructions and llm to make it a Smart Agent that reasons on its own:
const agent = new Agent({
  name: 'support-agent',
  description: 'Handles customer support end-to-end.',
  port: 4000,
  instructions: `You are a support specialist. When asked about a ticket:
    1. Look it up first
    2. Check the knowledge base for similar issues
    3. Draft a helpful response`,
  llm: {
    provider: 'gemini',
    model: 'gemini-2.0-flash',
  },
  mesh: { /* ... */ },
});
Tool AgentSmart Agent
LLM locationMesh onlyMesh + Agent
ReceivesStructured capability callsNatural language tasks
DecidesNothing — executes what it’s toldWhich capabilities to call
Best forIntegrations, lookups, CRUDComplex reasoning, multi-step

What’s Next