> ## 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
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.
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
## 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 Agent | When It Creates a Session |
| ------------------- | ------------------------------------------------ |
| **a2ui-terminal** | User opens the CLI |
| **transcript-link** | External system requests browser navigation |
| **cliq** | Build request triggers code generation |
| **Custom service** | Any 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**:
| Reason | Meaning | Example |
| --------- | ------------------------------------------ | ------------------------------- |
| `auto` | Built-in agent, created with the session | orchestrator, executor, planner |
| `self` | The agent that initiated the session | your entry-point agent |
| `routed` | Automatically added by Svantic when needed | on-demand agents |
| `invited` | Explicitly added via API | pre-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
```bash theme={null}
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
```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" }'
```
Svantic verifies your JWT, creates the session, and automatically sets up the internal agents. To 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"
}'
```
### Invite an Agent
```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" }'
```
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
```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"
}
}
}'
```
### Close a Session
```bash theme={null}
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`:
```json theme={null}
{ "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.