> ## 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.

# Registering agents

# 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:

```bash theme={null}
SVANTIC_CLIENT_ID=your-client-id \
SVANTIC_CLIENT_SECRET=your-client-secret \
node my-agent.js
```

```typescript theme={null}
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

```mermaid theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#eef2ff', 'primaryTextColor': '#1e1b4b', 'primaryBorderColor': '#818cf8', 'lineColor': '#94a3b8', 'secondaryColor': '#ecfdf5', 'secondaryBorderColor': '#34d399', 'secondaryTextColor': '#064e3b', 'tertiaryColor': '#faf5ff', 'tertiaryBorderColor': '#c084fc', 'tertiaryTextColor': '#581c87', 'noteBkgColor': '#eef2ff', 'noteTextColor': '#374151', 'noteBorderColor': '#c7d2fe'}}}%%
sequenceDiagram
	participant App as Your Agent
	participant Svantic

	App->>Svantic: Authenticate (client_id + client_secret)
	Svantic-->>App: Token

	App->>Svantic: Register (agent name, capabilities)
	Svantic-->>App: OK — connected

	Svantic->>App: Dispatch capability calls
	App-->>Svantic: Results
```

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](../concepts/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.

```json theme={null}
{
  "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:

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

Registration makes your agent **available**. Actual work happens inside [sessions](./managing-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

```bash theme={null}
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.

```bash theme={null}
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

```bash theme={null}
curl -X POST https://api.svantic.com/agents/list \
  -H "Authorization: Bearer $TOKEN"
```

### Deregister

```bash theme={null}
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) |