Skip to main content

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.

​
Sessions

Sessions are where work happens in Svantic. Every agent action — sending a message, calling a capability, approving a tool — takes place inside a session, and the session is what the mesh uses to coordinate who’s involved, what’s been said, and what’s been decided.

​
The Session-First Principle

A session is the unit of work in Svantic. It’s where a conversation happens, where agents collaborate, where state is kept, and where every action is attributed. Registering an agent with the mesh only declares availability — nothing is actually invoked, tracked, or recorded until a session wraps around it. Sessions don’t leak into each other. Two sessions running side by side keep their own conversation, their own context, and their own tool approvals, even when they share the same underlying agent instance.

​
Session Lifecycle

A session moves through four phases. It opens when an agent asks Svantic for one, becomes active once the agents it needs have joined, occasionally pauses while it waits for a human approval or form, and eventually closes — either explicitly or by sitting idle past its time-to-live. Session lifecycle: Opening → Active → Paused → Closed Each transition is driven by real events: an agent calling “open a session”, a message arriving, a tool needing approval, a human replying, a close call or an idle-timeout reaper ticking over.

​
Who talks to whom

Session sequence: your agent, Svantic, and other agents communicating

​
Who Creates Sessions?

Sessions are always initiated by an entry-point agent — the agent closest to the user or external trigger. Entry-point agents authenticate and call POST /sessions/init.
Entry-Point AgentWhen It Creates a Session
a2ui-terminalUser opens the CLI
transcript-linkExternal system requests browser navigation
cliqBuild request triggers code generation
Custom serviceAny authenticated agent that needs orchestration
Internal agents (orchestrator, executor, planner) never initiate sessions.

​
How Agents Join Sessions

There are four ways an agent ends up in a session:

​
1. Auto-Attach (Internal Agents)

When a session is created, Svantic instantiates a fresh set of internal agents for it — orchestrator, executor, planner, chat, critic, learner, mesh builder, document processor, and UI agent. No invitation needed.

​
2. Self-Join (Session Creator)

The entry-point agent that initiated the session joins automatically.

​
3. Automatic Routing (On-Demand)

When a session needs an agent type that isn’t already participating, Svantic automatically finds a registered instance and adds it. Once added, all future requests for that type in the same session go to the same instance (session affinity).

​
4. Explicitly Invited

An admin or entry-point agent calls POST /sessions/invite to add an agent before execution needs it.

​
Per-Session Agent Instances

Each session gets its own fresh set of internal agents. They belong to the session, live as long as it runs, and are torn down when it closes. This delivers:
  • Separate context — sessions never see each other’s conversations
  • Separate tool state — approvals and guardrail budgets apply per session
  • Failure stays local — a stuck agent is contained to its session
  • Per-session customization — different models, instructions, or toolsets
What is shared: Knowledge Store, app settings, and account credentials.

​
Session Participation

Svantic tracks which agents are in each session with a join reason:
ReasonMeaningExample
autoBuilt-in agent, created with the sessionorchestrator, executor, planner
selfThe agent that initiated the sessionyour entry-point agent
routedAutomatically added by Svantic when neededon-demand agents
invitedExplicitly added via APIpre-warmed agents

​
Input-Required: When Agents Need Humans

During execution, a message can enter the input-required state — the agent is blocked and needs human input. This happens when:
  • A policy guard blocks a tool invocation and requires approval
  • An agent explicitly calls request_user_input to collect structured data
  • An ADK tool confirmation fires
  • A plan requires approval before execution
A human resolves the request from any surface — dashboard, Slack, webhook, or in-session chat. Resolution transitions the message from input-required → working and execution continues. Messages in input-required can have a TTL; if unresolved, they transition to failed.

​
Managing Sessions

All examples use curl and assume Svantic is running at https://api.svantic.com.

​
Authenticate

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

​
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" }'
Svantic verifies your JWT, creates the session, and automatically sets up the internal agents. To 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"
  }'

​
Invite an Agent

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" }'
If you omit instance_id, Svantic picks an available instance automatically. Most of the time you don’t need to invite manually — automatic routing handles it.

​
Send Messages

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

​
Close a Session

curl -X POST https://api.svantic.com/sessions/my-session-001/close \
  -H "Authorization: Bearer $TOKEN"
Closing shuts down per-session agents, releases remote agents, and publishes cleanup events.

​
Session TTL

Sessions without activity are automatically closed after 30 minutes (default). Configurable via settings.json: 
{ "session_ttl_ms": 1800000 }

​
Constraints

  1. Every session has an account. The account identity comes from the JWT used in /sessions/init.
  2. Every working agent is in a session. Registration declares availability; work happens in sessions.
  3. Internal agents are per-session. Conversations, approvals, and state never bleed across sessions.
  4. Remote agents are shared. A single pod can serve multiple sessions. Session bindings track which sessions it’s in.
  5. Agents cannot cross accounts. An agent registered under account A cannot join a session owned by account B.