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.

​
Connecting to Svantic

Every agent built with the SDK runs in one of two modes:
  • Connected — the agent opens an outbound WebSocket to Svantic and receives dispatches over that socket. This is the default.
  • Hosted — the agent serves A2A over its own public HTTPS URL, and Svantic POSTs dispatches to it.
This guide covers when to pick which, how to configure credentials, and what URL to point at.

​
Which mode do I want?

Use connected mode (the default) when:
  • The agent runs on a laptop, CI worker, or anywhere behind NAT / corporate egress / a cloud provider’s default firewall.
  • You don’t want to manage an ingress, TLS certificate, or WAF.
  • The agent is ephemeral — scales to zero, spins up per-task, runs as a background worker.
Use hosted mode when:
  • The agent is already a public HTTP service you’d run regardless (e.g. a customer-facing API that also wants to be reachable from Svantic).
  • You want Svantic traffic to flow through your own ingress for auditing, WAF rules, or compliance reasons.
  • You want the agent to be callable from systems that are not on Svantic (bare A2A clients, other platforms).
When in doubt, use connected. It’s the better default for almost every team.

​
Credentials

Every SDK connection exchanges a client_id / client_secret pair for a short-lived JWT. Create the pair once in the Svantic dashboard under Settings → API Credentials and set them as environment variables: 
export SVANTIC_CLIENT_ID=cred_abc123
export SVANTIC_CLIENT_SECRET=sv_secret_...
Don’t bake them into your source or into container images. The SDK never writes them to disk.

​
The URL

Every SDK call to Svantic uses a single hostname: api.svantic.com. The edge routes paths (/auth/get_token, /agents/register, /sessions/init, WebSocket upgrade, …) to the right internal service, so your config stays simple. Override it only when pointing at a self-hosted or dev instance: 
new Agent({
  /* … */
  mesh: {
    svantic_url: 'https://svantic.internal.acme.com',
    client_id: process.env.SVANTIC_CLIENT_ID!,
    client_secret: process.env.SVANTIC_CLIENT_SECRET!,
  },
});
Default: DEFAULT_SVANTIC_URL = https://api.svantic.com.

​
Connected mode

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

const agent = new Agent({
  name: 'report-agent',
  description: 'Generates daily reports.',
  mesh: {
    client_id: process.env.SVANTIC_CLIENT_ID!,
    client_secret: process.env.SVANTIC_CLIENT_SECRET!,
  },
});

agent.define_capability({ /* … */ });

await agent.start();
  • No port, no public_url. The SDK opens a single outbound WebSocket.
  • The WebSocket is authenticated with your JWT and keeps a persistent ping/pong heartbeat.
  • If the connection drops, the SDK reconnects with exponential backoff automatically.
  • await agent.stop() deregisters cleanly.

​
Hosted mode

Set public_url (and optionally port) on the config: 
const agent = new Agent({
  name: 'report-agent',
  description: 'Generates daily reports.',
  public_url: 'https://report-agent.acme.com',
  port: 4000,
  mesh: {
    client_id: process.env.SVANTIC_CLIENT_ID!,
    client_secret: process.env.SVANTIC_CLIENT_SECRET!,
  },
});

agent.define_capability({ /* … */ });
await agent.start();
  • The SDK starts an Express server on port and registers public_url with Svantic.
  • Svantic POSTs dispatches to ${public_url}/send.
  • You’re responsible for the ingress, TLS termination, and keeping the URL reachable.
  • Turn on dispatch auth in hosted mode.

​
Using expose(app) + MeshConnector

When embedding into an existing Express service, split the two responsibilities: 
import express from 'express';
import { Agent } from '@svantic/sdk';
import { MeshConnector } from '@svantic/sdk/mesh';

const app = express();
app.use(express.json());

const agent = new Agent({
  name: 'report-agent',
  description: 'Generates daily reports.',
  public_url: 'https://api.acme.com',
});
agent.define_capability({ /* … */ });
agent.expose(app);

const mesh = new MeshConnector(agent, {
  client_id: process.env.SVANTIC_CLIENT_ID!,
  client_secret: process.env.SVANTIC_CLIENT_SECRET!,
});
await mesh.connect();

app.listen(4000);
See Attach to Express for a one-call alternative using attach().

​
What does the dashboard show?

An agent’s connection state appears under Agents → [your agent] in real time — connected mode shows “WebSocket healthy” with the last pong timestamp; hosted mode shows “HTTP callback” with the last successful dispatch. When liveness stalls for more than 90 seconds the agent is marked unhealthy; after ~2.5 minutes it’s deregistered.

​
See also