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.

​
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

1

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
2

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

Add credentials

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

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

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:
> What's 42 times 17?
42 times 17 is 714.
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.