Skip to main content

​
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:
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 — 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

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