Register Agent

Create or update an agent instance. Registration is policy-gated based on the your organizations’s policy_mode:

open (default) — Any agent type is auto-admitted. The type is added to the tenant’s allow-list automatically.
allow-list — Only pre-approved agent types can register. Returns 403 if the type is not in the tenant’s allow-list. Use /agents/allow_type to add it.
audit — All types can register, but a registration_flagged event is emitted for admin review.

Auto-creates the agent-type on first registration. Tool declarations and optional MCP server configs are persisted. Requires a valid JWT Bearer token.

Deployment mode — deployment_mode selects the transport the mesh uses for every dispatch sent to this instance:

connected (default) — the agent dials connect_url (returned in the response) over WebSocket and keeps the connection open; the mesh pushes dispatches down that socket. The agent-card probe is skipped. url must be omitted.
hosted — the agent exposes a public A2A HTTP surface at url. The gateway probes GET {url}/.well-known/agent-card.json on admission; if the probe fails the registration is rejected with 502.

If deployment_mode is omitted, the server infers hosted when url is present and connected otherwise.

Re-registering an existing instance_id with a different deployment_mode is rejected with 409 DEPLOYMENT_MODE_MISMATCH — deregister first and re-register, or create a new instance.

POST

agents

curl --request POST \
  --url https://api.svantic.com/agents/register \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_type": "navigator",
  "instance_id": "navigator-prod-01",
  "deployment_mode": "connected",
  "dispatch_auth": {
    "type": "svantic_jwt"
  },
  "agent_card": {
    "example_key": "example_value"
  },
  "tools": [
    {
      "example_key": "example_value"
    }
  ],
  "mcp_servers": {
    "sample_key": {
      "command": "string",
      "args": [
        "string"
      ]
    }
  }
}
'

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent_type: 'navigator',
    instance_id: 'navigator-prod-01',
    deployment_mode: 'connected',
    dispatch_auth: {type: 'svantic_jwt'},
    agent_card: {example_key: 'example_value'},
    tools: [{example_key: 'example_value'}],
    mcp_servers: {sample_key: {command: 'string', args: ['string']}}
  })
};

fetch('https://api.svantic.com/agents/register', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.svantic.com/agents/register"

payload = {
    "agent_type": "navigator",
    "instance_id": "navigator-prod-01",
    "deployment_mode": "connected",
    "dispatch_auth": { "type": "svantic_jwt" },
    "agent_card": { "example_key": "example_value" },
    "tools": [{ "example_key": "example_value" }],
    "mcp_servers": { "sample_key": {
            "command": "string",
            "args": ["string"]
        } }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.svantic.com/agents/register"

	payload := strings.NewReader("{\n  \"agent_type\": \"navigator\",\n  \"instance_id\": \"navigator-prod-01\",\n  \"deployment_mode\": \"connected\",\n  \"dispatch_auth\": {\n    \"type\": \"svantic_jwt\"\n  },\n  \"agent_card\": {\n    \"example_key\": \"example_value\"\n  },\n  \"tools\": [\n    {\n      \"example_key\": \"example_value\"\n    }\n  ],\n  \"mcp_servers\": {\n    \"sample_key\": {\n      \"command\": \"string\",\n      \"args\": [\n        \"string\"\n      ]\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "ok": true,
  "tenant_id": "tenant_abc123",
  "instance_id": "navigator-prod-01",
  "deployment_mode": "connected",
  "connect_url": "wss://api.svantic.com/agents/connect",
  "svantic_jwks_url": "https://api.svantic.com/.well-known/jwks.json",
  "dispatch_auth": {
    "type": "svantic_jwt"
  }
}

{
  "error": "Invalid request body",
  "code": "BAD_REQUEST"
}

{
  "error": "Invalid or expired token",
  "code": "unauthorized"
}

{
  "error": "JWT does not include the required scope for this operation",
  "code": "forbidden"
}

{
  "error": "Not found",
  "code": "NOT_FOUND",
  "request_id": "req_01EXAMPLE",
  "timestamp": "2026-03-31T12:00:00.000Z"
}

{
  "error": "Request timeout",
  "code": "REQUEST_TIMEOUT"
}

{
  "error": "<string>",
  "code": "<string>",
  "request_id": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR",
  "request_id": "req_01EXAMPLE",
  "timestamp": "2026-03-31T12:00:00.000Z"
}

{
  "error": "Bad gateway",
  "code": "BAD_GATEWAY"
}

{
  "error": "Service temporarily unavailable",
  "code": "SERVICE_UNAVAILABLE"
}

Body

application/json

agent_type

string

required

Logical agent type (e.g. "navigator", "transcript-link").

instance_id

string

required

Unique instance id (caller-supplied; upserted per instance).

url

string<uri> | null

Base URL where the agent serves its A2A surface. Required for hosted mode; must be omitted or null for connected mode. Switching the deployment_mode for an existing instance is rejected with 409 DEPLOYMENT_MODE_MISMATCH.

deployment_mode

enum<string>

default:connected

How the mesh reaches this agent for dispatches.

connected (default) — mesh pushes frames down an agent-initiated WebSocket. Works anywhere outbound HTTPS/WSS reaches, including behind firewalls, NATs, laptops, and CI.
hosted — mesh POSTs to url over HTTPS. Opt in when your agent already runs as a public HTTP service.

If the field is omitted, the server infers hosted when url is present and connected otherwise.

Available options:

hosted,

connected

dispatch_auth

object

How the mesh authenticates each dispatch it sends to the agent. Per-dispatch authentication applies to both hosted (HTTPS callback) and connected (WebSocket) agents. The envelope is attached to every outbound dispatch payload and verified by the SDK on the agent side via verify_dispatch_auth. Enforcement is gated by the mesh's SVANTIC_DISPATCH_AUTH_ENABLED flag. When the flag is on, the mesh refuses to send unauthenticated dispatches; when off, the mesh skips minting envelopes and the SDK skips verification. Both sides must agree on the flag. Defaults to svantic_jwt when omitted. See the internal spec platform/docs/specs/dispatch_auth.md for the wire format, error taxonomy, and test ownership.

Show child attributes

dispatch_auth_shared_secret

string

write-only

Raw secret bytes for dispatch_auth.type=shared_secret. Required on register when and only when dispatch_auth.type is shared_secret; rejected with 400 in any other case. The gateway encrypts this value under the tenant key and stores the ciphertext in agent_instances.dispatch_auth_secret_ciphertext; the raw value is never echoed in any response. Rotate by re-registering with a new credentials_ref and a fresh secret.

Required string length: 1 - 4096

agent_card

object

Optional agent card JSON persisted with the instance.

tools

object[]

Dynamic tool declarations registered with this instance. These are instance-specific capabilities that may vary across instances of the same agent type.

Show child attributes

mcp_servers

object

Optional MCP server configs applied to the agent type for this tenant.

Show child attributes

Response

Agent registered successfully.

Registration confirmation. The tenant_id is derived from the JWT. Connected-mode agents must dial the returned connect_url over WebSocket immediately and keep the connection open; that socket is the only path dispatches reach the agent on. Hosted-mode agents can ignore connect_url (it is null).

boolean

required

tenant_id

string

required

Tenant derived from the JWT Bearer token.

instance_id

string

required

Echo of the submitted instance_id, confirming the upsert target.

deployment_mode

enum<string>

required

The effective deployment mode for this instance after admission. Usually matches the request, but the server may reject a switch attempt with 409 DEPLOYMENT_MODE_MISMATCH (see the register path spec), so callers should always trust this value.

Available options:

hosted,

connected

connect_url

string<uri> | null

Populated only for connected mode: the WebSocket endpoint the SDK must dial to complete registration. Always includes the instance_id as a query parameter; authenticate with the same JWT used for the register call. null for hosted mode.

svantic_jwks_url

string<uri> | null

Public JWKS endpoint for dispatch_auth.type = svantic_jwt validation. null when the agent declared a non-JWT auth scheme. Hosted agents that rely on the default scheme should cache this JWKS with a short TTL (max 10 minutes) to catch signing-key rotations.

dispatch_auth

object

Show child attributes

curl --request POST \
  --url https://api.svantic.com/agents/register \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_type": "navigator",
  "instance_id": "navigator-prod-01",
  "deployment_mode": "connected",
  "dispatch_auth": {
    "type": "svantic_jwt"
  },
  "agent_card": {
    "example_key": "example_value"
  },
  "tools": [
    {
      "example_key": "example_value"
    }
  ],
  "mcp_servers": {
    "sample_key": {
      "command": "string",
      "args": [
        "string"
      ]
    }
  }
}
'

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent_type: 'navigator',
    instance_id: 'navigator-prod-01',
    deployment_mode: 'connected',
    dispatch_auth: {type: 'svantic_jwt'},
    agent_card: {example_key: 'example_value'},
    tools: [{example_key: 'example_value'}],
    mcp_servers: {sample_key: {command: 'string', args: ['string']}}
  })
};

fetch('https://api.svantic.com/agents/register', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.svantic.com/agents/register"

payload = {
    "agent_type": "navigator",
    "instance_id": "navigator-prod-01",
    "deployment_mode": "connected",
    "dispatch_auth": { "type": "svantic_jwt" },
    "agent_card": { "example_key": "example_value" },
    "tools": [{ "example_key": "example_value" }],
    "mcp_servers": { "sample_key": {
            "command": "string",
            "args": ["string"]
        } }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.svantic.com/agents/register"

	payload := strings.NewReader("{\n  \"agent_type\": \"navigator\",\n  \"instance_id\": \"navigator-prod-01\",\n  \"deployment_mode\": \"connected\",\n  \"dispatch_auth\": {\n    \"type\": \"svantic_jwt\"\n  },\n  \"agent_card\": {\n    \"example_key\": \"example_value\"\n  },\n  \"tools\": [\n    {\n      \"example_key\": \"example_value\"\n    }\n  ],\n  \"mcp_servers\": {\n    \"sample_key\": {\n      \"command\": \"string\",\n      \"args\": [\n        \"string\"\n      ]\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "ok": true,
  "tenant_id": "tenant_abc123",
  "instance_id": "navigator-prod-01",
  "deployment_mode": "connected",
  "connect_url": "wss://api.svantic.com/agents/connect",
  "svantic_jwks_url": "https://api.svantic.com/.well-known/jwks.json",
  "dispatch_auth": {
    "type": "svantic_jwt"
  }
}

{
  "error": "Invalid request body",
  "code": "BAD_REQUEST"
}

{
  "error": "Invalid or expired token",
  "code": "unauthorized"
}

{
  "error": "JWT does not include the required scope for this operation",
  "code": "forbidden"
}

{
  "error": "Not found",
  "code": "NOT_FOUND",
  "request_id": "req_01EXAMPLE",
  "timestamp": "2026-03-31T12:00:00.000Z"
}

{
  "error": "Request timeout",
  "code": "REQUEST_TIMEOUT"
}

{
  "error": "<string>",
  "code": "<string>",
  "request_id": "<string>",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR",
  "request_id": "req_01EXAMPLE",
  "timestamp": "2026-03-31T12:00:00.000Z"
}

{
  "error": "Bad gateway",
  "code": "BAD_GATEWAY"
}

{
  "error": "Service temporarily unavailable",
  "code": "SERVICE_UNAVAILABLE"
}