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

Your agent registers with the mesh, publishing its capabilities
Users or triggers send requests to the mesh
The mesh plans which agents and capabilities to call
Your agent executes the capability and returns the result
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:

Call billing-agent → get_overdue_invoices
Call ticket-agent → create_ticket
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

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 service	`hosted`
Corporate firewall, egress-only	`connected`
Ephemeral containers (Fly, Vercel CI)	`connected`
Kubernetes pod with Ingress	`hosted`
Developer laptop	`connected`

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:

Status	Routable?	Meaning
`available`	Yes	Healthy and has capacity
`unknown`	Yes	Newly registered, not yet confirmed
`busy`	No	Reached concurrent session limit
`unhealthy`	No	Missed heartbeats or failed recent dispatches
`offline`	No	Explicitly 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:

Status	Meaning
`unknown`	Newly registered
`online`	Live WebSocket connection open
`healthy`	Recent dispatch succeeded
`degraded`	At least one recent dispatch failed
`offline`	Agent is unreachable

Health Events

Event	When
`agent.registered`	New instance registered
`agent.connected`	WebSocket connection established
`agent.disconnected`	WebSocket connection closed
`agent.health_changed`	Routing status changed
`agent.deregistered`	Instance 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:

Mode	Behavior
Open (default)	Any agent type can register
Allow-list	Only pre-approved agent types can register
Audit	All 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

Variable	Purpose	Required
`SVANTIC_CLIENT_ID`	API client ID	Yes
`SVANTIC_CLIENT_SECRET`	API client secret	Yes
`SVANTIC_INSTANCE_ID`	Stable instance ID (for containers/k8s)	No (defaults to hostname-port)

​Agents

​How Agents Work

​Capabilities

​Where Agents Run

​Multiple Agents Together

​Connectivity

​Connected mode (default)

​Hosted mode

​Quick guide

​Health & Capacity

​Routing Status

​Capacity

​Connection Status

​Health Events

​Registration

​Quick Start (SDK)

​Registration Policies

​Agent Card

​Manual Registration (non-SDK)

​Managing Agents

​Environment Variables

Agents

How Agents Work

Capabilities

Where Agents Run

Multiple Agents Together

Connectivity

Connected mode (default)

Hosted mode

Quick guide

Health & Capacity

Routing Status

Capacity

Connection Status

Health Events

Registration

Quick Start (SDK)

Registration Policies

Agent Card

Manual Registration (non-SDK)

Managing Agents

Environment Variables