1# Session Management
2 
3Manage hosted agent sessions — isolated compute environments that provide persistent state across invocations.
4 
5## Overview
6 
7Sessions 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.
8 
9## Session Lifecycle
10 
11```text
12session_create → Running → (invoke, file ops) → session_delete
13                    ↓
14               Expired (platform auto-cleanup)
15```
16 
17## Session ID Format
18 
19Session IDs must match the pattern `^[A-Za-z0-9_-]{8,128}$`.
20 
21- If you provide a `sessionId` to `session_create`, it must conform to this pattern
22- If you omit `sessionId`, the platform auto-generates one
23- Store the returned `sessionId` — it is required for all subsequent operations
24 
25## MCP Tool Details
26 
27### Create Session
28 
29Use `session_create` to provision a new session:
30 
31| Parameter | Required | Description |
32|-----------|----------|-------------|
33| `projectEndpoint` | ✅ | AI Foundry project endpoint |
34| `agentName` | ✅ | Name of the hosted agent |
35| `sessionId` | ❌ | Optional custom session ID (8-128 chars, alphanumeric + hyphens/underscores) |
36 
37Returns: Session resource with `sessionId`, status, and expiration.
38 
39### Get Session
40 
41Use `session_get` to check session status:
42 
43| Parameter | Required | Description |
44|-----------|----------|-------------|
45| `projectEndpoint` | ✅ | AI Foundry project endpoint |
46| `agentName` | ✅ | Name of the hosted agent |
47| `sessionId` | ✅ | The session ID to inspect |
48 
49Returns: Session details including status, version, creation time, and expiration.
50 
51### Delete Session
52 
53Use `session_delete` to release compute resources:
54 
55| Parameter | Required | Description |
56|-----------|----------|-------------|
57| `projectEndpoint` | ✅ | AI Foundry project endpoint |
58| `agentName` | ✅ | Name of the hosted agent |
59| `sessionId` | ✅ | The session ID to delete |
60 
61> ⚠️ **Warning:** Deleting a session permanently removes all files stored in `$HOME` for that session.
62 
63### List Sessions
64 
65Use `session_list` to enumerate sessions:
66 
67| Parameter | Required | Description |
68|-----------|----------|-------------|
69| `projectEndpoint` | ✅ | AI Foundry project endpoint |
70| `agentName` | ✅ | Name of the hosted agent |
71| `limit` | ❌ | Max results to return (1-100, default 20) |
72| `order` | ❌ | Sort order: `asc` or `desc` (default `asc`) |
73| `after` | ❌ | Cursor for forward pagination |
74| `before` | ❌ | Cursor for backward pagination |
75 
76> ⚠️ **Warning:** `after` and `before` are mutually exclusive — do not pass both.
77 
78## Session vs Conversation
79 
80| Concept | Purpose | Scope |
81|---------|---------|-------|
82| `sessionId` | Binds requests to a compute instance with persistent filesystem state | Hosted agents only |
83| `conversationId` | Tracks conversation history across turns | Responses protocol only |
84 
85- A single session can host multiple conversations
86- A conversation does not require a session (prompt agents use `conversationId` without sessions)
87- For hosted agents using `responses` protocol, use **both**: `sessionId` for compute affinity and `conversationId` for history
88 
89## Best Practices
90 
911. **Create sessions explicitly** — Always use `session_create` before invoking a hosted agent. Do not rely on implicit session creation.
922. **Reuse sessions** — Keep the same session for related multi-turn interactions to preserve agent state.
933. **Clean up when done** — Delete sessions after use to release compute resources and avoid quota consumption.
944. **Handle expiry** — Sessions expire based on platform policies. If `session_get` returns a non-running state, create a new session.
955. **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.
966. **Debug with logstream** — Use `session_logstream` to stream stdout/stderr from a running session for troubleshooting.
97