Registering Agents

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

Quick Start (SDK)

The fastest way to register is with @svantic/sdk. Three environment variables, five lines of code:

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. Your agent is now discoverable on the mesh.

What Happens During Registration

The SDK performs all of this automatically when you call mesh.connect().

Connectivity Modes

By default, your agent connects outbound via WebSocket — no public URL or ingress needed. This works behind firewalls, NATs, and corporate networks. If your agent already runs as a public HTTP service, opt into hosted mode by passing a public_url. See Agent Connectivity for the full trade-off.

Registration Policies

Svantic supports three 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 — a JSON manifest at /.well-known/agent-card.json that describes its capabilities. The SDK generates this automatically 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:

Name: Use kebab-case, unique on the mesh (my-service, not MyService)
Description: Write it for the AI — explain what the service does and when to use it
Skills: One skill per atomic function. Don’t bundle multiple operations
Parameters: Use JSON Schema with descriptions on every property
Version: Use semver

Session Context

When a capability is invoked, your handler receives session context alongside the arguments:

handler: async (args, context) => {
	console.log(context.session_id);   // "abc-123"
}

Registration makes your agent available. Actual work happens inside sessions — Svantic pulls your agent in automatically when a session needs it.

Manual Registration (non-SDK)

If you’re not using the SDK (e.g. Python, Go), make two HTTP calls:

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

Use the token from step 1. The body only needs your agent’s name and capabilities — the body field and most other fields are optional.

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)

Get Started

Build Agents

Deep Dive

Knowledge & Self-Learning

Security

Policies & Guardrails

Notifications & Alerts

Deploying Your Agents

Forge

Plugins

Registering agents

Registering Agents

Quick Start (SDK)

What Happens During Registration

Connectivity Modes

Registration Policies

Agent Card

Session Context

Manual Registration (non-SDK)

1. Authenticate

2. Register

Managing Agents

List Registered Agents

Deregister

Environment Variables

​Registering Agents

​Quick Start (SDK)

​What Happens During Registration

​Connectivity Modes

​Registration Policies

​Agent Card

​Session Context

​Manual Registration (non-SDK)

​1. Authenticate

​2. Register

​Managing Agents

​List Registered Agents

​Deregister

​Environment Variables

Registering Agents

Quick Start (SDK)

What Happens During Registration

Connectivity Modes

Registration Policies

Agent Card

Session Context

Manual Registration (non-SDK)

1. Authenticate

2. Register

Managing Agents

List Registered Agents

Deregister

Environment Variables