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

# Managing sessions

# 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

***

<Steps>
  <Step title="Authenticate">
    Every session operation requires a JWT. Exchange your tenant credentials for a token:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Create a Session">
    ```bash theme={null}
    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:**

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="Register Your Agent (If You're a Remote Agent)">
    If you're building a remote agent (not the terminal CLI), register with Svantic:

    ```bash theme={null}
    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.
  </Step>

  <Step title="Invite an Agent into a Session">
    Add an agent to a session:

    ```bash theme={null}
    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:

    ```bash theme={null}
    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:**

    ```json theme={null}
    {
      "status": "ok",
      "session_id": "my-session-001",
      "agent_type": "transcript-link",
      "instance_id": "tl-pod-1",
      "join_reason": "invited"
    }
    ```
  </Step>

  <Step title="Send Messages">
    Send a message to the session via the A2A `/send` endpoint (JSON-RPC 2.0). The session's orchestrator handles routing:

    ```bash theme={null}
    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.
  </Step>

  <Step title="List Agents in a Session">
    See which agents are in a session and how they joined:

    ```bash theme={null}
    curl https://api.svantic.com/admin/sessions/my-session-001/agents
    ```

    **Response:**

    ```json theme={null}
    {
      "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 }
      ]
    }
    ```
  </Step>

  <Step title="Close a Session">
    Explicitly close a session to clean up resources:

    ```bash theme={null}
    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
  </Step>
</Steps>

***

## Self-Join Shortcut

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

```bash theme={null}
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.

```mermaid theme={null}
flowchart TD
    M1["First message needs transcript-link"] --> F["Svantic finds tl/pod-3"]
    F --> A["Adds to session + dispatches"]
    M2["Second message needs transcript-link"] --> S["Already in session"]
    S --> R["Routes to tl/pod-3 directly"]
```

***

## Session TTL

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

```json theme={null}
{
  "session_ttl_ms": 1800000
}
```

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

***

## Further Reading

* [Sessions](../concepts/sessions) — the session-first architecture
* [Registering Agents](./registering-agents) — how agents register with Svantic
* [Using the API](./using-the-api) — full API reference