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
403if the type is not in the tenant’s allow-list. Use/agents/allow_typeto add it. -
audit — All types can register, but a
registration_flaggedevent 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 dialsconnect_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.urlmust be omitted. -
hosted— the agent exposes a public A2A HTTP surface aturl. The gateway probesGET {url}/.well-known/agent-card.jsonon admission; if the probe fails the registration is rejected with502.
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.
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"
]
}
}
}
'{
"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"
}
}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.
Body
Logical agent type (e.g. "navigator", "transcript-link").
Unique instance id (caller-supplied; upserted per instance).
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.
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 tourlover 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.
hosted, connected 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
Show child attributes
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.
1 - 4096Optional agent card JSON persisted with the instance.
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
Show child attributes
Optional MCP server configs applied to the agent type for this tenant.
Show child attributes
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).
Tenant derived from the JWT Bearer token.
Echo of the submitted instance_id, confirming the upsert target.
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.
hosted, connected 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.
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.
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
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"
]
}
}
}
'{
"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"
}
}