Interactive Sessions

Interactive sessions are long-lived, stateful collaboration environments where you and AI agents work together in real time — exploring codebases, writing code, reviewing changes, creating documents, and more.

What is an Interactive Session?

Unlike a single-shot workflow job, an interactive session is a persistent workspace where:

• You and an AI agent have a live conversation
• The agent has access to your codebase, tools, knowledge base, and more
• You can pause and resume without losing progress
• All actions are logged in an immutable event ledger
• The session can create branches, commit code, open pull requests
• The agent can spin up live development servers you can preview
• A session can host multiple conversation threads over one shared workspace

A session can be:

• Standalone — a direct conversation with an agent for exploration or tasks
• Pipeline-bound — launched as part of a workflow run (e.g., the engineering phase)

Session Lifecycle

1Creating → Provisioning → Active → Paused → Recovering → Active
2            ↓                               ↓
3          Failed                         Completed
4                               ↓
5                             Archived

What Happens During Provisioning

When you create a session, the platform:

1. Allocates a worker from the agent pool
2. Boots the worker and waits for readiness
3. Resolves approved connection and credential bindings without making long-lived provider secrets part of the Agent configuration
4. Prepares the workspace (mounts repos, knowledge base, deliverable specs)
5. Writes agent configuration (model, tools, skills)
6. Reloads the agent config
7. Verifies the language model is available
8. Verifies tools and MCP servers are accessible
9. Marks session as active

Each phase is tracked as a provisioningPhase in the session, so you can diagnose any failure point.

Key Capabilities

💬 Real-Time Conversation

Send messages to the agent and receive streaming responses. The agent can:

• Answer questions about your codebase
• Explain code, architectures, designs
• Generate new code, tests, documentation
• Review and suggest improvements
• Execute multi-step tasks autonomously

🔧 Tool Execution

Agents use tools to perform real actions:

• File operations — Read, create, edit, delete files
• Git operations — Create branches, commit, push, open PRs
• Web search — Look up external documentation
• Code execution — Run scripts, tests, build commands
• MCP tools — Any tool attached via Model Context Protocol

📁 File & Git Operations

Sessions track every file change and git operation:

• file_created, file_edited, file_deleted
• git_branch_created, git_committed, git_pushed
• pr_created — auto-creates a PR when work is ready

⏸️ Pause & Resume

Sessions can be paused and resumed without losing state:

• Pausing saves a snapshot of the workspace (agent memory, files, history)
• Resuming restores the same logical session on a fresh worker
• The worker allocation may change, but the session identity and restored conversation/workspace state do not
• No work lost — the agent continues from where it left off

🖥️ Preview Apps

Sessions can detect and expose live development servers:

• Automatically detected (Next.js dev, modern bundler dev servers, Python uvicorn, etc.)
• Accessible via a proxied public URL
• Status tracked: running, crashed, stopped

🔌 Attachments & Extensions

Extend session capabilities at any time:

• MCP Servers — Attach external tools (databases, APIs, code tools)
• Skills — Attach domain knowledge (testing best practices, security guidelines)
• Files — Attach knowledge base pages, uploaded documents, repo references
• Sub-agents (Delegates) — Bind extra agents the primary can hand off focused work to via its task tool. See Sub-agents for the model.
• Biome contributions — Biomes extend the session UI itself: slash commands, drawer tabs, activity renderers, tool-call renderers, mutation bars, header chips, attachment classes, and per-profile capability flags. See Biomes · Authoring § Session contributions for the full taxonomy.

🔗 Knowledge & Context

Agents can access:

• Attached knowledge base spaces
• Specific KB pages
• Uploaded files and documents
• Repository references
• Org-level documents

Conversation Threads

A session is the workspace — one worker, one set of files, one git checkout. The conversations that run on it are threads. Every session starts with one default thread (Main); open more to explore separate lines of work against the same workspace.

• Each thread keeps its own message history and its own turn lock.
• Threads share the session's worker, files, tools, and git state.
• Threads run independently — one thread can be mid-turn while you type in another.
• A session always retains at least one active thread.

Messages, the streaming response, and message/event history are addressed by (sessionId, threadId). See the API Reference.

Lifecycle policy and attendance

Two settings shape how a session behaves over time:

• Lifecycle policy. ephemeral is the default: the session pauses when it is idle. persistent never pauses for idleness. In both, a turn that gets stuck is reaped.
• Attendance. Whether a person is present is fixed at launch, from the verified caller. A user token from the web app or the shell makes the session attended. Anything else makes it unattended. It does not change later. See Questions, permission asks and attendance.

Turn Model

Each thread processes one message at a time via a per-thread turn lock:

1User sends message to a thread
2  → Thread turn lock acquired
3  → Agent processes message (streaming response)
4  → Events logged: tool calls, file changes, git ops, etc.
5  → Thread turn lock released (idle)
6  → Thread ready for the next message

A turn is started either by the platform or by the runtime; the session records which one initiated it.

turnState belongs to the thread, not the session — two threads on the same session can be in different turn states at once.

Session & Pipeline Integration

Sessions can be bound to a pipeline run (pipelineRunId). When this happens:

• The session is part of a larger workflow execution
• The session receives context from the pipeline (phase, deliverable specs, mounts)
• When the session completes, results flow back to the pipeline
• The pipeline can gate on the session result (approval, artifact quality)

See Pipeline Integration Examples for workflow examples that spawn sessions.

Event Ledger

Every action in a session is recorded as an immutable event:

The event ledger is the canonical audit record of everything that happened.

Attaching and Detaching Skills

You can attach a skill to a running session with POST /sessions/:id/skills, and detach it with DELETE /sessions/:id/skills/.... Both operations are asynchronous. They return 202 Accepted with the attachment, whose status is pending (or detach_pending for a detach). The skill is not live yet when the call returns.

An attachment moves from pending to bound or failed, and a detach moves from detach_pending to detached.

The change applies between turns. If a turn is running, the change takes effect after that turn ends.

A failed attachment carries a failure with a typed code and a human-readable message. For skill_content_mismatch, the skill changed after it was resolved: attach it again, which resolves it afresh.

Do not poll. Follow progress through the skill_attachment_changed event in the Event Ledger and on the session event stream. Its payload is {attachmentId, skillSlug, status, failureCode?}, where status is one of pending, bound, failed, detach_pending or detached, and failureCode is present only when status is failed.

Quick Start

Start a Session

1curl -X POST https://agent-session-api.xema.dev/sessions \
2  -H "Authorization: Bearer $TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "agentRef": "engineering-assistant@3",
6    "title": "Fix authentication module"
7  }'

Start a Domain-Projected Session (Domain-Selected Agent)

1curl -X POST https://agent-session-api.xema.dev/sessions \
2  -H "Authorization: Bearer $TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "title": "Design review for auth hardening",
6    "sessionDomainKey": "design-review",
7    "sessionDomainRef": "dr_01j2abcxyz"
8  }'

Send a Message

1curl -X POST https://agent-session-api.xema.dev/sessions/{sessionId}/threads/{threadId}/messages \
2  -H "Authorization: Bearer $TOKEN" \
3  -H "Content-Type: application/json" \
4  -H "Accept: text/event-stream" \
5  -H "Idempotency-Key: <unique-turn-id>" \
6  -d '{
7    "content": "Can you review the authentication code and suggest improvements?"
8  }'

Check Status

1curl https://agent-session-api.xema.dev/sessions/{sessionId} \
2  -H "Authorization: Bearer $TOKEN"

Pages in This Section

• Features — Full feature reference
• Pipeline Integration — Using sessions in workflows
• API Reference — REST API endpoints
• Sub-agents — Bind delegates the primary can call into
• Domain Projections — Build custom modes (for example design review) on top of the shared runtime
• Examples — Step-by-step implementation guides for custom interactive modes

See Also

• Workflows Overview
• DSL Examples with Sessions
• Pipeline Integration Examples