Svantic SDK

@svantic/sdk is the TypeScript toolkit for building AI agents on Svantic. You describe what your agent can do in plain code, and Svantic handles the rest — discovery, orchestration, streaming, authentication, and observability. A handler you write today runs the same way whether it’s called by a user in the chat UI, by another agent as a tool, or by a scheduled trigger at 3 a.m.

Install

npm install @svantic/sdk

Requires Node.js 20 or later.

Hello, agent

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

const agent = new Agent({
  name: 'hello-agent',
  description: 'Greets people by name.',
  mesh: {
    client_id: process.env.SVANTIC_CLIENT_ID!,
    client_secret: process.env.SVANTIC_CLIENT_SECRET!,
  },
});

agent.define_capability({
  name: 'greet',
  description: 'Return a friendly greeting for the given name.',
  parameters: {
    type: 'object',
    properties: {
      name: { type: 'string', description: 'Name to greet' },
    },
    required: ['name'],
  },
  handler: async ({ name }) => ({ message: `Hello, ${name}!` }),
});

await agent.start();

Run it with your credentials from the Svantic dashboard:

SVANTIC_CLIENT_ID=... SVANTIC_CLIENT_SECRET=... npx tsx hello.ts

Your agent is now live, discoverable, and callable by other agents on Svantic. No ingress, no public URL, no port forwarding — it dials out to api.svantic.com and keeps a persistent connection open.

What the SDK gives you

You want to…	Start here
Expose functions an AI can invoke	Defining capabilities
Let an LLM plan which capabilities to call	Smart agents
Call another agent’s capabilities	Calling other agents
Embed agent endpoints in an existing Express app	Attach to Express
Run on webhooks, cron, or emitted events	Triggers
Bridge an MCP server as capabilities	MCP integration
Trace what your agent did, and why	Telemetry & tracing
Reject forged dispatches to a hosted agent	Securing dispatches
Keep secrets out of the agent and LLM	Sensitive forms

Two ways to run

Every agent built with the SDK is either:

Connected — the default. Your agent dials Svantic over an outbound WebSocket. No public URL, no inbound firewall rules. Ideal for laptops, CI, ephemeral workers, and anything behind NAT.
Hosted — your agent exposes a public HTTPS URL, and Svantic POSTs to it. Use this when you want Svantic traffic to flow through your own ingress for auditing or WAF reasons.

See Connecting to Svantic for when to choose which.

How to read these docs

Guides are task-oriented. Start here if you’re building something. Each guide is a complete walkthrough.
Reference is the exhaustive API listing — every class, method, option, and type.

If you’re new, go to the Quickstart.

Getting credentials

Every SDK call to Svantic uses a client_id / client_secret pair issued to your tenant. Create them in the Svantic dashboard under Settings → API Credentials, then set them as environment variables:

export SVANTIC_CLIENT_ID=...
export SVANTIC_CLIENT_SECRET=...

The SDK exchanges these for a short-lived token automatically — you never mint or refresh JWTs by hand.

Support

Source and issues: github.com/svantic/svantic
Questions: support@svantic.com
Status: status.svantic.com

Overview

Guides

Reference

Sdk

Svantic SDK

Install

Hello, agent

What the SDK gives you

Two ways to run

How to read these docs

Getting credentials

Support

​Svantic SDK

​Install

​Hello, agent

​What the SDK gives you

​Two ways to run

​How to read these docs

​Getting credentials

​Support

Svantic SDK

Install

Hello, agent

What the SDK gives you

Two ways to run

How to read these docs

Getting credentials

Support