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.

​
Agents

An agent is a service that exposes capabilities to the Svantic mesh. Your ticket system, your billing API, your monitoring service — wrap it with the SDK and it becomes an agent that the mesh can discover, invoke, and orchestrate.

​
How Agents Work

  1. Your agent registers with the mesh, publishing its capabilities
  2. Users or triggers send requests to the mesh
  3. The mesh plans which agents and capabilities to call
  4. Your agent executes the capability and returns the result
  5. The mesh returns the final response
You write the business logic. The mesh handles routing, planning, and orchestration.

​
Capabilities

A capability is a single thing your agent can do. Each has:
  • Name — What the mesh calls it (get_ticket, create_order)
  • Description — The LLM reads this to decide when to use it
  • Parameters — JSON Schema defining the inputs
  • Handler — Your async function that does the work
agent.define_capability({
  name: 'get_ticket',
  description: 'Look up a support ticket by ID. Returns subject, status, priority.',
  parameters: {
    type: 'object',
    properties: {
      ticket_id: { type: 'number', description: 'The ticket ID' },
    },
    required: ['ticket_id'],
  },
  handler: async (args) => {
    const ticket = await db.find(args.ticket_id);
    if (!ticket) throw new Error(`Ticket ${args.ticket_id} not found`);
    return ticket;
  },
});
Write descriptions that are specific about inputs, outputs, and when to use the capability. The mesh reads these to decide which capability to call.
For a comprehensive guide on defining capabilities, MCP servers, builtin integrations, and bidirectional execution, see Tools & Capabilities.

​
Where Agents Run

Agents run on your infrastructure — your cloud, your VPC, your laptop. The mesh coordinates them but never sees your raw data. Your code, credentials, and databases stay with you. This is what makes Svantic usable in regulated industries. The mesh sees capability names and results, not the underlying data or logic.

​
Multiple Agents Together

The mesh can orchestrate multiple agents in a single workflow:
“Check if customer acme-123 has overdue invoices and create a support ticket if they do.”
The mesh might:
  1. Call billing-agent → get_overdue_invoices
  2. Call ticket-agent → create_ticket
  3. Call slack-agent → send_notification
You don’t write this orchestration logic. Each agent exposes its capabilities. The mesh figures out the plan.

​
Connectivity

Every dispatch the mesh sends must reach your agent. Svantic supports two connectivity modes:
  • Connected (default) — your agent dials Svantic over a persistent WebSocket. Works anywhere outbound HTTPS/WSS works — behind firewalls, NATs, corporate networks, laptops, CI runners, or ephemeral containers.
  • Hosted — your agent exposes a public HTTPS surface the mesh calls into. Opt in when your agent already runs as an HTTP service that can accept inbound traffic.
You choose per instance_id. Two instances of the same agent type can use different modes.

​
Connected mode (default)

Connected mode: agent dials Svantic via WebSocket, dispatches pushed bidirectionally You get connected mode by calling new MeshConnector(agent, { svantic_url, client_id, client_secret }) with no public_url. The SDK dials a WebSocket and keeps it open. The mesh pushes dispatch frames down the socket; your agent pushes dispatch_result frames back. When it’s right (almost always):
  • Behind a firewall, NAT, or corporate proxy
  • Developer laptop, CI runner, ephemeral container
  • Zero inbound exposure — outbound-only is a compliance win
  • Easiest onboarding: no ingress, no TLS cert, no reverse proxy

​
Hosted mode

Hosted mode: Svantic sends HTTPS dispatch to agent, agent returns response Opt in by passing a public_url at registration. Every dispatch is an HTTPS POST from the mesh to {public_url}/send. When to pick it:
  • Your agent already runs as a long-lived HTTP service with inbound traffic
  • You have an existing ingress, LB, or API gateway
  • You prefer request/response and control the infra on both sides
Requirements: Publicly reachable HTTPS URL, /.well-known/agent-card.json served at the root, TLS terminated by you.

​
Quick guide

You have…Pick
A public HTTPS servicehosted
Corporate firewall, egress-onlyconnected
Ephemeral containers (Fly, Vercel CI)connected
Kubernetes pod with Ingresshosted
Developer laptopconnected

​
Health & Capacity

Svantic monitors two independent signals for every registered agent instance: routing status and connection status.

​
Routing Status

Determines whether Svantic will send tasks to an agent instance:
StatusRoutable?Meaning
availableYesHealthy and has capacity
unknownYesNewly registered, not yet confirmed
busyNoReached concurrent session limit
unhealthyNoMissed heartbeats or failed recent dispatches
offlineNoExplicitly marked down
Agents send periodic heartbeats. If an agent stops heartbeating, Svantic marks it unhealthy and stops routing. After repeated failures, it’s automatically deregistered.

​
Capacity

Each agent can declare a max_concurrent_sessions limit at registration:
  • 0 (default): unlimited
  • N > 0: Svantic tracks active sessions and stops routing new work once the limit is reached
When capacity frees up (sessions close), the agent becomes available again. Among available agents, Svantic prefers the least-loaded instance.

​
Connection Status

Reflects the transport link health — drives dashboard indicators:
StatusMeaning
unknownNewly registered
onlineLive WebSocket connection open
healthyRecent dispatch succeeded
degradedAt least one recent dispatch failed
offlineAgent is unreachable

​
Health Events

EventWhen
agent.registeredNew instance registered
agent.connectedWebSocket connection established
agent.disconnectedWebSocket connection closed
agent.health_changedRouting status changed
agent.deregisteredInstance removed

​
Registration

Registration tells Svantic what your agent can do. Once registered, the mesh can discover your capabilities and route work to your agent.

​
Quick Start (SDK)

SVANTIC_CLIENT_ID=your-client-id \
SVANTIC_CLIENT_SECRET=your-client-secret \
node my-agent.js

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

const agent = new Agent({
	name: 'my-service',
	description: 'Describe what your agent does — the AI reads this.',
});

agent.define_capability({
	name: 'analyze_data',
	description: 'Run statistical analysis on a dataset',
	parameters: {
		type: 'object',
		properties: {
			dataset_id: { type: 'string', description: 'Dataset identifier' },
			analysis_type: { type: 'string', description: 'mean, median, regression, or correlation' },
		},
		required: ['dataset_id', 'analysis_type'],
	},
	handler: async (args) => {
		return { result: 'analysis complete' };
	},
});

const mesh = new MeshConnector(agent, {
	svantic_url: process.env.SVANTIC_URL ?? 'https://api.svantic.com',
	client_id: process.env.SVANTIC_CLIENT_ID!,
	client_secret: process.env.SVANTIC_CLIENT_SECRET!,
});
await mesh.connect();
The SDK handles authentication, registration, and connectivity automatically.

​
Registration Policies

Configurable in the dashboard under Settings → Agent Policy:
ModeBehavior
Open (default)Any agent type can register
Allow-listOnly pre-approved agent types can register
AuditAll types register, but unknown types are flagged for review

​
Agent Card

Every agent publishes an Agent Card at /.well-known/agent-card.json. The SDK generates this from your define_capability calls. 
{
  "name": "my-service",
  "description": "Run statistical analysis on datasets",
  "url": "https://my-agent.example.com/send",
  "version": "1.0.0",
  "capabilities": { "streaming": false },
  "skills": [
    {
      "id": "analyze_data",
      "name": "analyze_data",
      "description": "Run statistical analysis on a dataset",
      "parameters": {
        "type": "object",
        "properties": {
          "dataset_id": { "type": "string" },
          "analysis_type": { "type": "string" }
        },
        "required": ["dataset_id", "analysis_type"]
      }
    }
  ]
}
Best practices: kebab-case names, AI-readable descriptions, one skill per function, JSON Schema with descriptions on every property, semver versioning.

​
Manual Registration (non-SDK)

If you’re not using the SDK (e.g. Python, Go): 1. Authenticate: 
curl -X POST https://api.svantic.com/auth/get_token \
  -H "Content-Type: application/json" \
  -d '{ "client_id": "your-client-id", "client_secret": "your-client-secret" }'
2. Register: 
curl -X POST https://api.svantic.com/agents/register \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "agent_type": "my_agent", "instance_id": "pod-1" }'
Add "public_url" and "deployment_mode": "hosted" only if your agent is publicly reachable.

​
Managing Agents

# List registered agents
curl -X POST https://api.svantic.com/agents/list \
  -H "Authorization: Bearer $TOKEN"

# Deregister
curl -X POST https://api.svantic.com/agents/deregister \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "instance_id": "pod-1" }'
Deregistration removes the instance from routing and cleans up any active session bindings.

​
Environment Variables

VariablePurposeRequired
SVANTIC_CLIENT_IDAPI client IDYes
SVANTIC_CLIENT_SECRETAPI client secretYes
SVANTIC_INSTANCE_IDStable instance ID (for containers/k8s)No (defaults to hostname-port)