MeshConnector

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

What it is

MeshConnector owns the Svantic platform connection on behalf of an Agent. It is responsible for:

Authentication — exchanging your client_id / client_secret for a JWT (or accepting a pre-issued token).
Registration — telling Svantic the agent exists, what capabilities it has, and how to reach it.
Transport — in connected mode, dialing an outbound WebSocket; in hosted mode, leaving dispatches to hit the agent’s public URL.
Liveness — sending heartbeats so the gateway keeps the agent marked healthy.
Session lifecycle — creating and closing Svantic sessions from the agent side.

new Agent({ mesh: { … } }) + await agent.start() constructs a MeshConnector under the hood, so in most cases you don’t import this class at all.

When to use it

Import MeshConnector directly when you want the agent endpoints on an Express app you already own:

You’re using agent.expose(app) instead of agent.start().
You’re running multiple agents in one process and want fine-grained lifecycle control.
You’re managing the token yourself (e.g. a BFF forwarding a user JWT).

For the one-call Express embedding pattern, use attach — it wires MeshConnector for you.

Functional usage

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

const app = express();
app.use(express.json());

// 1. Build the agent and register its capabilities.
const agent = new Agent({
  name: 'orders-agent',
  description: 'Order management agent.',
  public_url: 'https://api.acme.com',
});
agent.define_capability({ /* … */ });

// 2. Mount A2A endpoints (/send + /.well-known/agent-card.json) on your app.
agent.expose(app);

// 3. Build the connector with credentials.
const mesh = new MeshConnector(agent, {
  client_id: process.env.SVANTIC_CLIENT_ID!,
  client_secret: process.env.SVANTIC_CLIENT_SECRET!,
});

// 4. connect() does: auth → register → open transport → start heartbeat.
await mesh.connect();

app.listen(4000);

// 5. On shutdown, disconnect() stops the heartbeat, closes the
//    WebSocket, and tells Svantic to deregister.
process.on('SIGTERM', () => mesh.disconnect());

Two advanced patterns the connector enables:

Token rotation — when you’re forwarding a user JWT (e.g. a dashboard session token) that the caller rotates periodically, call mesh.refresh_token(new_jwt) whenever the token changes. No reconnect needed.
Runtime capability changes — after agent.define_capability(...) at runtime, call mesh.re_register() so the gateway sees the updated tool list without a full reconnect.

Constants

`DEFAULT_SVANTIC_URL`

export const DEFAULT_SVANTIC_URL = 'https://api.svantic.com';

Used whenever svantic_url is omitted from a MeshConnectorConfig.

Constructor

new MeshConnector(agent: Agent, config: MeshConnectorConfig)

See MeshConnectorConfig for every option. The most common shapes:

// Credential mode — SDK exchanges client_id/secret for a JWT.
new MeshConnector(agent, {
  client_id: process.env.SVANTIC_CLIENT_ID!,
  client_secret: process.env.SVANTIC_CLIENT_SECRET!,
});

// Token mode — caller supplies a pre-issued JWT (e.g. forwarded from a dashboard session).
new MeshConnector(agent, { token: bearer_token });

At least one of (client_id + client_secret) or token must be set.

Lifecycle

`connect()`

await mesh.connect();

If no token was supplied, exchange credentials for a JWT.
Register the agent with Svantic (capabilities, deployment_mode, optional dispatch_auth, learning config).
In connected mode, open the outbound WebSocket; in hosted mode this step is a no-op.
Start the heartbeat.

Throws if authentication, registration, or the WebSocket handshake fails. Throws are wrapped with clear error context so the caller’s try/catch sees a descriptive message.

`disconnect()`

await mesh.disconnect();

Best-effort teardown: stops the heartbeat, closes the WebSocket, sends POST /agents/deregister, and clears the cached token. Safe to call when not connected.

`re_register()`

await mesh.re_register();

Re-register with Svantic without disconnecting. Use this after adding capabilities at runtime so the gateway sees the refreshed tool list. Throws if the connector is not currently connected.

`refresh_token(jwt)`

mesh.refresh_token(new_jwt);

Replace the JWT used for all subsequent gateway calls. Useful in token-mode deployments (e.g. a BFF forwarding a rotated dashboard session token).

Sessions

`create_session(options?)`

const session_id = await mesh.create_session();
const scoped = await mesh.create_session({ user_id: 'user_42' });

Create a platform session bound to this agent instance. Returns the server-generated session_id. Throws when not connected.

`close_session(session_id)`

await mesh.close_session(session_id);

Mark a session as completed. Throws when not connected.

Properties

Property	Type	Description
`connected`	`boolean`	`true` while a registration is active.
`svantic_url`	`string`	The resolved Svantic URL (respects `DEFAULT_SVANTIC_URL`).
`token`	`string \| null`	Current JWT, or `null` before `connect()` / after `disconnect()`.
`deployment_mode`	`'connected' \| 'hosted' \| null`	Resolved mode from the registration response. `null` before `connect()`.
`agent`	`Agent`	The wrapped agent.
`ws_transport`	`WsTransport \| null`	The underlying WebSocket transport in connected mode; otherwise `null`.

Overview

Guides

Reference

Mesh connector

MeshConnector

What it is

When to use it

Functional usage

Constants

`DEFAULT_SVANTIC_URL`

Constructor

Lifecycle

`connect()`

`disconnect()`

`re_register()`

`refresh_token(jwt)`

Sessions

`create_session(options?)`

`close_session(session_id)`

Properties

See also

​MeshConnector

​What it is

​When to use it

​Functional usage

​Constants

​DEFAULT_SVANTIC_URL

​Constructor

​Lifecycle

​connect()

​disconnect()

​re_register()

​refresh_token(jwt)

​Sessions

​create_session(options?)

​close_session(session_id)

​Properties

​See also

MeshConnector

What it is

When to use it

Functional usage

Constants

`DEFAULT_SVANTIC_URL`

Constructor

Lifecycle

`connect()`

`disconnect()`

`re_register()`

`refresh_token(jwt)`

Sessions

`create_session(options?)`

`close_session(session_id)`

Properties

See also