dynamic-sessions

name: dynamic-sessions description: Work with Azure Container Apps dynamic sessions through their REST API. Use when agents need to authenticate with Entra ID, create or reuse code interpreter sessions via identifiers, execute Python code inside a session, inspect session metadata, and upload, list, or download files independent of the client programming language.

Dynamic Sessions

Azure Container Apps dynamic sessions provide short-lived, isolated sandboxes behind a session pool. This skill is intentionally language-agnostic on the client side: any language that can make HTTPS requests and attach a bearer token can use it. The only runtime assumption is that the code sent to the built-in code interpreter session is Python.

When To Use

• Writing client code in any language that calls the dynamic sessions management API directly.
• Building backend services in any language that execute untrusted or AI-generated Python code in a session.
• Managing session identifiers, session metadata, and session lifecycle behavior.
• Uploading input files to a session and retrieving generated outputs.

Core Concepts

Session pool

A session pool is the Azure resource that fronts all sessions. Your app talks to the pool management endpoint, not to individual containers.

Session identifier

The identifier query parameter selects the session. If the identifier already exists, the existing session is reused. If it does not exist, the first request that targets the session creates it implicitly.

Authentication

All pool management API requests require a Microsoft Entra token and the caller must have the Azure ContainerApps Session Executor role on the session pool. The token must target https://dynamicsessions.io. Client-library details depend on the language, but the HTTP contract is the same.

Scope

This skill focuses on the built-in code interpreter session pool for running Python code. Custom container sessions are out of scope unless a task explicitly asks for them.

Preferred Workflow

1. Get the pool management endpoint:

az containerapp sessionpool show \
  --name <SESSION_POOL_NAME> \
  --resource-group <RESOURCE_GROUP> \
  --query "properties.poolManagementEndpoint" \
  --output tsv

2. Store it in POOL_MANAGEMENT_ENDPOINT.
3. Acquire a Microsoft Entra token for https://dynamicsessions.io.
4. Call the REST endpoints documented below.
5. Reuse the same identifier to keep working inside the same session.

Quick Start

Use code-interpreter-rest-flow.md for a language-agnostic flow that:

• acquires an Entra token
• reuses a session via a caller-supplied identifier
• executes Python code inside the session
• deletes the session explicitly when finished
• uploads a file
• lists files
• downloads a file

Common Patterns

Authenticate

Client code varies by language, but the HTTP requirement is always:

Authorization: Bearer <TOKEN_FOR_https://dynamicsessions.io>

Execute Python code

POST <POOL_MANAGEMENT_ENDPOINT>/executions?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Content-Type: application/json
Authorization: Bearer <TOKEN>

{
  "properties": {
    "codeInputType": "inline",
    "executionType": "synchronous",
    "code": "print('Hello from Azure dynamic sessions')"
  }
}

Create or reuse a session

There is no separate documented "create session" call for code interpreter pools. Creation is implicit. Send the first request with a new identifier; later requests with the same identifier reuse the same session.

Inspect sessions

POST <POOL_MANAGEMENT_ENDPOINT>/.management/getSession?identifier=<SESSION_ID>&api-version=2024-02-02-preview
Authorization: Bearer <TOKEN>

Stop a session

For built-in code interpreter sessions, the current data-plane REST docs expose an explicit delete endpoint:

DELETE <POOL_MANAGEMENT_ENDPOINT>/session?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>

This deletes the code-interpreter session identified by identifier. A later execution with the same identifier can recreate a fresh session implicitly.

Do not confuse this with the custom-container management endpoint:

POST <POOL_MANAGEMENT_ENDPOINT>/.management/stopSession?api-version=2025-10-02-preview&identifier=<SESSION_ID>

That stopSession operation is documented for custom container session pools, not for the built-in code interpreter pool.

Work with files

POST <POOL_MANAGEMENT_ENDPOINT>/files?api-version=2025-10-02-preview&identifier=<SESSION_ID>
Authorization: Bearer <TOKEN>
Content-Type: multipart/form-data

API Quick Reference

Important Version Note

Microsoft Learn currently shows two API shapes in different articles:

• newer code-interpreter docs: /executions and /files with 2025-10-02-preview
• older session-pool docs: code/execute and files/upload with 2024-02-02-preview

For new code, prefer the newer code-interpreter REST shape and keep API versions configurable in your client code. Details are in api-notes.md.

Best Practices

• Keep Entra tokens server-side only. Never expose them to end users.
• Treat session identifiers as sensitive values. Generate them securely and never let users choose arbitrary identifiers for other tenants.
• Prefer EgressDisabled unless the workload genuinely needs outbound network access.
• Assume anything inside a session is visible to code running in that session, including files and environment variables.
• Handle session expiration by recreating state when SessionWithIdentifierNotFound or equivalent not-found behavior occurs.
• Generate Python for the code interpreter unless a task explicitly asks for another runtime.
• Keep API versions configurable because the Learn articles and data-plane references are still evolving.

Learn More

CLI Alternative For Learn MCP Tools

Run directly with npx @microsoft/learn-cli <command> or install globally with npm install -g @microsoft/learn-cli.