Getting Started

By the end of this guide, you’ll have:

A running agent on your machine
Connected to the Svantic mesh
Responding to natural language prompts
Fully traced in the dashboard

Prerequisites

Node.js 20+

Required runtime for Svantic agents. Download the latest LTS version.

Svantic Account

Free to create. You’ll need API keys from the dashboard.

Quick Start

Clone the starter agent

The starter agent has simple capabilities (calculator, clock, unit converter) — things you wouldn’t normally need AI for. That’s intentional.

AI should only do what requires AI. A calculator doesn’t need an LLM — it needs arithmetic. The LLM’s job is to understand “what’s 42 times 17?” and route it to the right tool. The tool does the actual work, deterministically and cheaply.This is how Svantic works: the mesh uses AI for understanding and routing, your agents use code for execution. You get natural language interfaces without burning tokens on tasks that don’t need them.

git clone https://github.com/svantic/starter-agent.git
cd starter-agent
npm install

Get your API keys

Sign up at app.svantic.com/signup, go to Settings → API Keys → Create Key, and copy your Client ID and Client Secret.

Add credentials

cp .env.example .env
# Edit .env and add your keys:
# SAVANT_CLIENT_ID=your-client-id
# SAVANT_CLIENT_SECRET=your-client-secret

Start the agent

npm run dev

You should see:

[agent] Listening on http://localhost:4000
[agent] Connected to Svantic mesh (authenticated + registered)
Starter agent is running. Try asking: "What is 42 times 17?"

Your agent is live — registered on the mesh, publishing capabilities, exporting telemetry.

Talk to your agent

Open a second terminal:

npm install -g @svantic/terminal
svantic --client-id your-client-id --client-secret your-client-secret

The starter agent has three capabilities. Test each one:

Calculator
Timezone Clock
Unit Converter

> What's 42 times 17?
42 times 17 is 714.

> What time is it in Tokyo?
It's currently 3:45 PM in Tokyo (JST).

> Convert 100 kg to pounds
100 kilograms is 220.46 pounds.

If you see responses like these, your agent is working.

See it in the dashboard

Go to app.svantic.com and click into your session:

Agent registry — Your agent listed with URL, version, heartbeat status
Session timeline — The conversation you just had
Tool calls — calculate called with { operator: "multiply", a: 42, b: 17 }
Telemetry spans — End-to-end timing for every step

Every action traced, no extra code required.

Understand the Code

Everything is in src/agent.ts — 5 lines to create an agent, ~10 lines per capability.

The Agent

import { Agent } from '@svantic/sdk';

const agent = new Agent({
  name: 'starter-agent',
  description: 'A utility agent that does math, tells time, and converts units.',
  port: 4000,
  mesh: {
    client_id: process.env.SAVANT_CLIENT_ID,
    client_secret: process.env.SAVANT_CLIENT_SECRET,
  },
});

name — Identity in the mesh. Other agents discover you by this. description — The mesh LLM reads this to decide when to route tasks to your agent. port — The mesh calls your agent at this port to invoke capabilities. mesh — Credentials for mesh connection. Without this, the agent runs standalone.

Capabilities

Each capability is a function the mesh can call:

agent.define_capability({
  name: 'calculate',
  description: 'Perform basic arithmetic.',
  parameters: {
    type: 'object',
    properties: {
      operator: { type: 'string', enum: ['add', 'subtract', 'multiply', 'divide'] },
      a: { type: 'number' },
      b: { type: 'number' },
    },
    required: ['operator', 'a', 'b'],
  },
  handler: async (args) => {
    const { operator, a, b } = args;
    if (operator === 'add') return { result: a + b };
    if (operator === 'multiply') return { result: a * b };
    // ...
  },
});

name — The mesh invokes your capability by this name. parameters — JSON Schema. The LLM constructs arguments from natural language. handler — Your business logic. Receives parsed arguments, returns a result.

Start

await agent.start();

One line to start the agent and join the mesh, ready to serve.

What’s Next

Build with Forge

Generate agents from OpenAPI specs or prompts.

Build by Hand

Deeper guide with multiple capabilities.

Add to Existing Service

Use attach() with Express apps.

Connecting Agents

Discover and call other agents.

Get Started

Build Agents

Deep Dive

Knowledge & Self-Learning

Security

Policies & Guardrails

Notifications & Alerts

Deploying Your Agents

Forge

Plugins

Getting Started

Getting Started

Prerequisites

Node.js 20+

Svantic Account

Quick Start

See it in the dashboard

Understand the Code

The Agent

Capabilities

Start

What’s Next

Build with Forge

Build by Hand

Add to Existing Service

Connecting Agents

​Getting Started

​Prerequisites

Node.js 20+

Svantic Account

​Quick Start

​See it in the dashboard

​Understand the Code

​The Agent

​Capabilities

​Start

​What’s Next

Build with Forge

Build by Hand

Add to Existing Service

Connecting Agents

Getting Started

Prerequisites

Quick Start

See it in the dashboard

Understand the Code

The Agent

Capabilities

Start

What’s Next