Skip to main content

​
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
1

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

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

Register Your Agent (If You're a Remote Agent)

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

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"
}
5

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

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 }
  ]
}
7

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:
  1. Per-session agents are shut down
  2. Remote agents are released for other sessions
  3. 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:
  1. Checks if the agent type is already in the session — if so, routes to the same instance (session affinity)
  2. Finds an available registered instance
  3. 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).

​
Further Reading