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.

​
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 invokeDefining capabilities
Let an LLM plan which capabilities to callSmart agents
Call another agent’s capabilitiesCalling other agents
Embed agent endpoints in an existing Express appAttach to Express
Run on webhooks, cron, or emitted eventsTriggers
Bridge an MCP server as capabilitiesMCP integration
Trace what your agent did, and whyTelemetry & tracing
Reject forged dispatches to a hosted agentSecuring dispatches
Keep secrets out of the agent and LLMSensitive 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