Agents

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.

Path Parameters

agent_namestringrequired

The name of the agent to create a session for.

Query Parameters

api-versionstringrequired

The API version to use for this operation.

Header Parameters

Foundry-Featuresstringoptional

A feature flag opt-in required when using preview operations or modifying persisted preview resources.

AgentEndpoints=V1Preview

x-ms-user-isolation-keystringoptional

Opaque per-user isolation key used to scope endpoint-scoped data (responses, conversations, sessions) to a specific end user.

Request BodyContent-Type: application/json

agent_session_idstring

Optional caller-provided session ID. If specified, it must be unique within the agent endpoint. Auto-generated if omitted.

version_indicatorversion_refrequired

Determines which agent version backs the session.

One of the following:

version_refVersionRefIndicator

Version indicator that references a specific agent version by name.

Responses

agent_session_idstringrequired

The session identifier.

version_indicatorversion_refrequired

The version indicator determining which agent version backs this session.

One of the following:

version_refVersionRefIndicator

Version indicator that references a specific agent version by name.

statusenumrequired

The current status of the session.

creatingactiveidleupdatingfaileddeletingdeletedexpired

created_atintegerrequired

The Unix timestamp (in seconds) when the session was created.

last_accessed_atintegerrequired

The Unix timestamp (in seconds) when the session was last accessed.

expires_atintegerrequired

The Unix timestamp (in seconds) when the session expires (rolling, 30 days from last activity).