# Create a session

`POST /agents/{agent_name}/endpoint/sessions`

Creates a new session for an agent endpoint.
The endpoint resolves the backing agent version from `version_indicator` and
enforces session ownership using the provided isolation key for session-mutating operations.

## Parameters

### Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `agent_name` | `string` | Yes | The name of the agent to create a session for. |

### Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `api-version` | `string` | Yes | The API version to use for this operation. |

### Header parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `Foundry-Features` | `enum` | No | A feature flag opt-in required when using preview operations or modifying persisted preview resources. _Constant:_ `AgentEndpoints=V1Preview` |
| `x-ms-user-isolation-key` | `string` | No | Opaque per-user isolation key used to scope endpoint-scoped data (responses, conversations, sessions) to a specific end user. |

## Request Body

Content-Type: `application/json` *(required)*

Request to create a new agent session.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `agent_session_id` | `string` | No | Optional caller-provided session ID. If specified, it must be unique within the agent endpoint. Auto-generated if omitted. |
| `version_indicator` | `VersionRefIndicator` | Yes | Determines which agent version backs the session. |

### `version_indicator` — `VersionRefIndicator`

Determines which agent version backs the session.

**One of the following:**

#### `version_ref` — `version_ref (VersionRefIndicator)`

Version indicator that references a specific agent version by name.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Discriminator value for version_ref. _Constant:_ `version_ref` |
| `agent_version` | `string` | Yes | The agent version identifier returned by the agent version APIs. |

## Responses

### 201 — The request has succeeded and a new resource has been created as a result.

Content-Type: `application/json`

An agent session providing a long-lived compute sandbox for hosted agent invocations.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `agent_session_id` | `string` | Yes | The session identifier. |
| `version_indicator` | `VersionRefIndicator` | Yes | The version indicator determining which agent version backs this session. |
| `status` | `enum` | Yes | The current status of the session. _Enum:_ `creating`, `active`, `idle`, `updating`, `failed`, `deleting`, `deleted`, `expired` |
| `created_at` | `integer` | Yes | The Unix timestamp (in seconds) when the session was created. _Format:_ `unixtime` |
| `last_accessed_at` | `integer` | Yes | The Unix timestamp (in seconds) when the session was last accessed. _Format:_ `unixtime` |
| `expires_at` | `integer` | Yes | The Unix timestamp (in seconds) when the session expires (rolling, 30 days from last activity). _Format:_ `unixtime` |

#### `version_indicator` — `VersionRefIndicator`

The version indicator determining which agent version backs this session.

**One of the following:**

##### `version_ref` — `version_ref (VersionRefIndicator)`

Version indicator that references a specific agent version by name.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | `enum` | Yes | Discriminator value for version_ref. _Constant:_ `version_ref` |
| `agent_version` | `string` | Yes | The agent version identifier returned by the agent version APIs. |

### 4XX — Client error

Content-Type: `application/json`

Error response for API failures.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `error` | `OpenAI.Error` | Yes |  |

#### `error` — `OpenAI.Error`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `code` | `string \| null` | Yes |  |
| `message` | `string` | Yes |  |
| `param` | `string \| null` | No |  |
| `type` | `string` | No |  |
| `details` | `OpenAI.Error[]` | No |  |
| `additionalInfo` | `object` | No |  |
| `debugInfo` | `object` | No |  |

### 5XX — Server error

Content-Type: `application/json`

Error response for API failures.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `error` | `OpenAI.Error` | Yes |  |

#### `error` — `OpenAI.Error`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `code` | `string \| null` | Yes |  |
| `message` | `string` | Yes |  |
| `param` | `string \| null` | No |  |
| `type` | `string` | No |  |
| `details` | `OpenAI.Error[]` | No |  |
| `additionalInfo` | `object` | No |  |
| `debugInfo` | `object` | No |  |