1# Session Management
2 
3Manage hosted agent sessions — isolated compute environments that provide persistent state across invocations.
4 
5This document covers session creation and lifecycle for both HTTP-protocol agents (`responses`, `invocations`) and WebSocket agents (`invocations_ws`).
6 
7## Overview
8 
9Sessions bind a hosted agent to a dedicated compute instance. Files written to `$HOME` during a session persist across requests for the lifetime of that session. When a session is deleted, its compute resources and stored files are released.
10 
11## Session Creation
12 
13| Protocol | How a session is created | Session id |
14|----------|--------------------------|------------|
15| `responses`, `invocations` (HTTP) | Call the `session_create` MCP tool before invoking the agent | **Server-issued** `sessionId` (or a client-supplied one passed to `session_create`) |
16| `invocations_ws` (WebSocket) | Implicitly, on the first WebSocket upgrade (no `session_create` call) | **Client-supplied** `agent_session_id` query parameter on the upgrade URL — **optional**; if omitted, the platform (or the container) generates a random id |
17 
18Both ids follow the same format rule: `^[A-Za-z0-9_-]{8,128}$`.
19 
20## Session Lifecycle
21 
22**HTTP (`responses`, `invocations`):**
23 
24```text
25session_create → Running → (invoke, file ops) → session_delete
26                    ↓
27               Expired (platform auto-cleanup)
28```
29 
30**WebSocket (`invocations_ws`):**
31 
32```text
33client opens WS upgrade (optionally with ?agent_session_id=<id>)
34  └─► first upgrade for that id ──► sandbox created, handler bound
35        └─► frames flow ──► either side closes ──► WS connection ends
36              └─► sandbox + $HOME persist ──► next WS upgrade with same id re-hydrates
37                    └─► after the idle timeout, compute is deprovisioned; state is persisted
38```
39 
40Key points for `invocations_ws`:
41 
42- There is **no `session_create` / `session_delete`** call. The first upgrade creates the session; the session outlives any individual WebSocket connection.
43- The `agent_session_id` query parameter is **optional**. If you omit it, the platform (or the container) generates a random id; supply it explicitly only when you need a specific id to resume an existing session.
44- The `agent_session_id` is the **affinity key** — the platform routes upgrades with the same id back to the same sandbox.
45- Closing the WebSocket does **not** delete the session. To resume, open a new upgrade with the same `agent_session_id` and the container sees its previous `$HOME` state.
46- After the idle timeout, the platform deprovisions compute but persists session state, so the next reconnect re-hydrates the sandbox.
47 
48## Session ID Format
49 
50Session IDs must match the pattern `^[A-Za-z0-9_-]{8,128}$`.
51 
52- If you provide a `sessionId` to `session_create`, it must conform to this pattern
53- If you omit `sessionId`, the platform auto-generates one
54- Store the returned `sessionId` — it is required for all subsequent operations
55 
56## MCP Tool Details
57 
58### Create Session
59 
60Use `session_create` to provision a new session:
61 
62| Parameter | Required | Description |
63|-----------|----------|-------------|
64| `projectEndpoint` | ✅ | AI Foundry project endpoint |
65| `agentName` | ✅ | Name of the hosted agent |
66| `sessionId` | ❌ | Optional custom session ID (8-128 chars, alphanumeric + hyphens/underscores) |
67 
68Returns: Session resource with `sessionId`, status, and expiration.
69 
70### Get Session
71 
72Use `session_get` to check session status:
73 
74| Parameter | Required | Description |
75|-----------|----------|-------------|
76| `projectEndpoint` | ✅ | AI Foundry project endpoint |
77| `agentName` | ✅ | Name of the hosted agent |
78| `sessionId` | ✅ | The session ID to inspect |
79 
80Returns: Session details including status, version, creation time, and expiration.
81 
82### Delete Session
83 
84Use `session_delete` to release compute resources:
85 
86| Parameter | Required | Description |
87|-----------|----------|-------------|
88| `projectEndpoint` | ✅ | AI Foundry project endpoint |
89| `agentName` | ✅ | Name of the hosted agent |
90| `sessionId` | ✅ | The session ID to delete |
91 
92> ⚠️ **Warning:** Deleting a session permanently removes all files stored in `$HOME` for that session.
93 
94### List Sessions
95 
96Use `session_list` to enumerate sessions:
97 
98| Parameter | Required | Description |
99|-----------|----------|-------------|
100| `projectEndpoint` | ✅ | AI Foundry project endpoint |
101| `agentName` | ✅ | Name of the hosted agent |
102| `limit` | ❌ | Max results to return (1-100, default 20) |
103| `order` | ❌ | Sort order: `asc` or `desc` (default `asc`) |
104| `after` | ❌ | Cursor for forward pagination |
105| `before` | ❌ | Cursor for backward pagination |
106 
107> ⚠️ **Warning:** `after` and `before` are mutually exclusive — do not pass both.
108 
109## Session vs Conversation
110 
111| Concept | Purpose | Scope |
112|---------|---------|-------|
113| `sessionId` | Binds requests to a compute instance with persistent filesystem state | Hosted agents only |
114| `conversationId` | Tracks conversation history across turns | Responses protocol only |
115 
116- A single session can host multiple conversations
117- A conversation does not require a session (prompt agents use `conversationId` without sessions)
118- For hosted agents using `responses` protocol, use **both**: `sessionId` for compute affinity and `conversationId` for history
119 
120## Best Practices
121 
1221. **Create sessions explicitly** — Always use `session_create` before invoking a hosted agent with `responses` or `invocations` protocol. Do not rely on implicit session creation.
1232. **Reuse sessions** — Keep the same session for related multi-turn interactions to preserve agent state.
1243. **Clean up when done** — Delete sessions after use to release compute resources and avoid quota consumption.
1254. **Handle expiry** — Sessions expire based on platform policies. If `session_get` returns a non-running state, create a new session.
1265. **Version awareness** — The platform auto-resolves the agent version at session creation time. If you need a specific version, ensure it is active before creating the session.
1276. **Debug with logstream** — Use `session_logstream` to stream stdout/stderr from a running session for troubleshooting.
128