Managing Sessions

This guide covers the full session lifecycle: creating sessions, inviting agents, sending messages, and closing sessions. All examples use curl and assume Svantic is running at https://api.svantic.com.

Prerequisites

A Svantic account with API credentials
At least one registered agent

Authenticate

Every session operation requires a JWT. Exchange your tenant credentials for a token:

TOKEN=$(curl -s -X POST https://api.svantic.com/auth/get_token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "svantic",
    "client_secret": "your-secret",
    "agent_type": "a2ui-terminal"
  }' | jq -r '.token')

The token authenticates all subsequent requests.

Create a Session

curl -X POST https://api.svantic.com/sessions/init \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "session_id": "my-session-001"
  }'

Response:

{
  "status": "ok",
  "session_id": "my-session-001",
  "agents": [
    { "agent_type": "savant:orchestrator", "instance_id": "orchestrator-my-session-001", "join_reason": "auto" },
    { "agent_type": "savant:executor", "instance_id": "executor-my-session-001", "join_reason": "auto" },
    { "agent_type": "savant:planner", "instance_id": "planner-my-session-001", "join_reason": "auto" },
    { "agent_type": "savant:chat", "instance_id": "chat-my-session-001", "join_reason": "auto" },
    { "agent_type": "savant:critic", "instance_id": "critic-my-session-001", "join_reason": "auto" },
    { "agent_type": "savant:learner", "instance_id": "learner-my-session-001", "join_reason": "auto" }
  ]
}

Svantic verifies your JWT, creates the session, and automatically sets up the internal agents needed for orchestration.

If you’re building a remote agent (not the terminal CLI), register with Svantic:

curl -X POST https://api.svantic.com/agents/register \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "agent_type": "transcript-link",
    "instance_id": "tl-pod-1",
    "url": "http://localhost:4100",
    "tools": [],
    "mcp_servers": {}
  }'

This registers your agent as available. It does not join any session yet.

Invite an Agent into a Session

Add an agent to a session:

curl -X POST https://api.svantic.com/sessions/my-session-001/invite \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "agent_type": "transcript-link",
    "instance_id": "tl-pod-1"
  }'

If you omit instance_id, Svantic picks an available instance of that agent_type automatically:

curl -X POST https://api.svantic.com/sessions/my-session-001/invite \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "agent_type": "transcript-link"
  }'

Response:

{
  "status": "ok",
  "session_id": "my-session-001",
  "agent_type": "transcript-link",
  "instance_id": "tl-pod-1",
  "join_reason": "invited"
}

Send Messages

Send a message to the session via the A2A /send endpoint (JSON-RPC 2.0). The session’s orchestrator handles routing:

curl -X POST https://api.svantic.com/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "message": {
        "kind": "message",
        "messageId": "msg-001",
        "role": "user",
        "parts": [
          { "kind": "text", "text": "Navigate to geico.com and extract the login page" }
        ]
      },
      "configuration": {
        "sessionId": "my-session-001"
      }
    }
  }'

The A2A protocol handles streaming via message/stream. All metadata (files, action_data, target_agent, yolo_mode, context) is sent as DataParts in the A2A Message.

List Agents in a Session

See which agents are in a session and how they joined:

curl https://api.svantic.com/admin/sessions/my-session-001/agents

Response:

{
  "session_id": "my-session-001",
  "agents": [
    { "agent_type": "savant:orchestrator", "instance_id": "orchestrator-my-session-001", "join_reason": "auto", "joined_at": 1708700000 },
    { "agent_type": "savant:executor", "instance_id": "executor-my-session-001", "join_reason": "auto", "joined_at": 1708700000 },
    { "agent_type": "a2ui-terminal", "instance_id": "term-001", "join_reason": "self", "joined_at": 1708700001 },
    { "agent_type": "transcript-link", "instance_id": "tl-pod-1", "join_reason": "routed", "joined_at": 1708700050 }
  ]
}

Close a Session

Explicitly close a session to clean up resources:

curl -X POST https://api.svantic.com/sessions/my-session-001/close \
  -H "Authorization: Bearer $TOKEN"

What happens:

Per-session agents are shut down
Remote agents are released for other sessions
Cleanup events are published

Self-Join Shortcut

For entry-point agents that create sessions, you can combine session creation and self-join in one call:

curl -X POST https://api.svantic.com/sessions/init \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "session_id": "my-session-001",
    "self_agent_type": "a2ui-terminal",
    "self_instance_id": "term-001"
  }'

This creates the session, auto-attaches internal agents, AND binds the caller — all in one round-trip.

Automatic Routing

You don’t need to invite agents manually for most workflows. When a session needs an agent type that isn’t already participating, Svantic automatically:

Checks if the agent type is already in the session — if so, routes to the same instance (session affinity)
Finds an available registered instance
Adds it to the session and dispatches the task

This means registration alone is enough — Svantic pulls agents into sessions as needed.

Session TTL

Sessions without activity are automatically closed after the TTL threshold (default: 30 minutes). The threshold is configurable via settings.json:

{
  "session_ttl_ms": 1800000
}

Set to 0 to disable automatic cleanup (not recommended for production).

Get Started

Build Agents

Deep Dive

Knowledge & Self-Learning

Security

Policies & Guardrails

Notifications & Alerts

Deploying Your Agents

Forge

Plugins

Managing sessions

Managing Sessions

Prerequisites

Self-Join Shortcut

Automatic Routing

Session TTL

Further Reading

​Managing Sessions

​Prerequisites

​Self-Join Shortcut

​Automatic Routing

​Session TTL

​Further Reading

Managing Sessions

Prerequisites

Self-Join Shortcut

Automatic Routing

Session TTL

Further Reading