Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Use the preview session compute APIs in Microsoft Foundry to inspect the environment that runs your hosted agent session. You can start stopped compute, change its idle timeout, read its network settings, and stream container logs.
Each session has one compute named default. It represents the session's running environment, not a separate agent or conversation. If the service replaces the sandbox, the session and compute IDs stay the same.
Prerequisites
- API version
2025-11-15-previewand theFoundry-Features: SessionCompute=V1Previewrequest header for compute operations. - An existing, accessible hosted agent session. To create or find one, see Manage hosted agent sessions.
- Azure CLI, authenticated with
az login. The examples use Bash andaz rest. The log-stream example also usescurl. - Authorization under the agent endpoint's configured policy, and access to the session under its isolation policy.
- For Azure RBAC authorization, Compute Read permission for the discovery, policy-read, and log examples. Compute Write permission is also required for
:startand lifecycle-policy changes. See Session compute permissions. - A compute that supports the operation you need. Check
capabilities.startorcapabilities.lifecycle_policy_writebefore using those operations.
The Foundry User built-in role includes the required Compute Read and Compute Write data actions when assigned at the Foundry project scope. For narrower access, use a custom role with only the required data actions.
Important
The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.
The Azure CLI and curl examples in this article use AzureRbac (or Entra) and request tokens for the Foundry resource (https://ai.azure.com). Don't use these token-acquisition commands unchanged with a Blueprint-only endpoint.
For AgentBlueprint, request a token for the individual agent blueprint and satisfy its token-validation rules. Follow Agent blueprint authorization and Acquire a token for the agent blueprint.
Identify the session's compute
Use your public project endpoint, agent name, and session ID. Replace the placeholders, URL-encode the agent and session path segments, and omit a trailing slash from PROJECT_ENDPOINT.
PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
AGENT_NAME="<url-encoded-agent-name>"
SESSION_ID="<url-encoded-session-id>"
RESOURCE="https://ai.azure.com"
COMPUTE_API_VERSION="2025-11-15-preview"
COMPUTES_URL="${PROJECT_ENDPOINT}/agents/${AGENT_NAME}"
COMPUTES_URL+="/endpoint/sessions/${SESSION_ID}/computes"
COMPUTE_URL="${COMPUTES_URL}/default"
Reference: Manage hosted agent sessions.
Read the compute:
az rest --method GET \
--url "${COMPUTE_URL}?api-version=${COMPUTE_API_VERSION}" \
--resource "${RESOURCE}" \
--headers "Foundry-Features=SessionCompute=V1Preview"
Reference: Interpret compute state and capabilities, az rest.
The result has object: session.compute and id: default. Read requests don't start or resume compute.
Use 2025-11-15-preview and Foundry-Features: SessionCompute=V1Preview for the compute operations in this article. These settings don't change the API version used by your existing agent invocation or session-management calls.
For delegated identity or header-based isolation, include the same permitted identity or isolation headers used to access the session. A session ID alone doesn't grant access. See Isolate sessions per user.
List the session's computes
The collection currently contains only default. There's no separate compute-creation API; creating a session provides its compute.
az rest --method GET \
--url "${COMPUTES_URL}?api-version=${COMPUTE_API_VERSION}" \
--resource "${RESOURCE}" \
--headers "Foundry-Features=SessionCompute=V1Preview"
Reference: Interpret compute state and capabilities.
The list envelope contains object: list, data, and has_more. Nonempty pages also contain first_id and last_id. Collection requests accept limit from 1 through 100, order of asc or desc, and either after or before. Defaults are limit=20 and order=asc.
Interpret compute state and capabilities
Read the resource fields together rather than treating a provider name or capability as proof that an operation is ready.
| Field | Meaning |
|---|---|
id |
The compute ID, currently default. Other IDs return compute_not_found. |
agent_session_id |
The owning session. |
provider |
The infrastructure running the session, such as aca_sandboxes or byo_aks. Use capabilities to decide which operations are supported. |
state |
provisioning, running, stopped, suspended, failed, or deleted. The reported state can briefly differ from the sandbox's actual state. |
capabilities |
Support for start, exec, ports, and lifecycle_policy_write. A capability isn't a caller permission or readiness guarantee. |
volumes |
Read-only resolved storage layout, including mount paths, storage types, and persistence properties. It doesn't report usage or let you create or resize volumes. |
created_at, last_accessed_at, stopped_at |
Unix timestamps in seconds; stopped_at can be absent or null. |
Clients must tolerate new provider, state, and storage-type values. Don't interpret an unknown value as a running or supported compute.
The agent version defines the image, resources, baseline policies, and optional primitive opt-ins. The session provides workload identity and isolation. The compute surface exposes runtime operations on that session, not a new deployment configuration.
Persistence depends on the configured storage and lifecycle mode. Memory snapshots restore a version's startup baseline, not an ongoing session checkpoint. For their different file and memory persistence behavior, see Enable memory snapshots for hosted agents.
Start stopped compute
Use :start when you explicitly want an existing session's compute to run, including after you stop that session yourself. The operation requires Compute Write permission and capabilities.start: true; it doesn't require an exec or ports opt-in.
Send a request without a body:
az rest --method POST \ --url "${COMPUTE_URL}:start?api-version=${COMPUTE_API_VERSION}" \ --resource "${RESOURCE}" \ --headers "Foundry-Features=SessionCompute=V1Preview"Reference: Session compute permissions.
Inspect the result. Success returns HTTP
200and the runningsession.computeresource after readiness checks complete.
| Condition | Behavior |
|---|---|
| Backing sandbox is stopped and resumable | Resume it in place. |
| Customer stop terminated a recoverable, volume-backed sandbox | Create a replacement sandbox using the session's existing agent version and compatible persistent storage when recovery permits. |
| Backing sandbox is already running | Return HTTP 409 with compute_not_ready, not an idempotent success. |
| Terminated sandbox has no recoverable persistent data volume | Reject the start. |
| Session is missing, expired, failed, or otherwise not recoverable | Reject the operation; don't create a new logical session. |
| Compute doesn't support start | Return compute_operation_not_supported. |
The service checks the sandbox's actual state, not only the reported compute state. A running value from an earlier GET doesn't make :start an idempotent operation.
Before reporting success, the service checks that the sandbox it started still belongs to the session and is running. If the sandbox has changed or stopped, start returns 409 compute_not_ready instead.
Wake-up includes container readiness time. To reduce that part of startup, see Reduce startup latency for hosted agents.
Starting compute doesn't submit a new agent-protocol request. It also doesn't promise to preserve process memory, files outside persistent mounts, port exposures, or instance-scoped policy overrides across replacement.
Both exec transports can resume inactivity-stopped compute in place before dispatching a command. They don't start customer-stopped compute or recreate terminated sandboxes. For that distinction, see Handle inactive compute.
Enable optional exec and port primitives
An agent version must opt in before its sessions support exec or port exposure. The following fragment belongs inside the hosted agent's definition, alongside its image, resources, and protocol configuration:
{
"compute_primitives": {
"exec": true,
"ports": true
}
}
Reference: Run commands in session compute, Expose session ports.
This fragment isn't a complete version-creation request. Publish the intended configuration as an agent version using your supported deployment path, then use sessions bound to that version. For version management, see Manage hosted agent lifecycle.
Opt-ins don't grant authorization or change which agent version an existing session uses. Start and lifecycle-policy writes don't require these two opt-ins.
Read and change the instance idle timeout
The agent version's session_configuration.idle_timeout_seconds sets the baseline for its sessions. Use the compute lifecycle-policy API to view that baseline and override the current instance's auto-suspend interval.
Read the policy:
POLICY_URL="${COMPUTE_URL}/lifecycle-policy" az rest --method GET \ --url "${POLICY_URL}?api-version=${COMPUTE_API_VERSION}" \ --resource "${RESOURCE}" \ --headers "Foundry-Features=SessionCompute=V1Preview"Reference: Manage session idleness.
Compare
requestedwitheffective, and checkwritableandlimits.Field Meaning requestedThe baseline idle timeout and its source: agent_definitionorplatform_default.effectiveThe provider's current auto-suspend, idle-timeout, suspend-mode, and auto-delete settings. effective_statusproviderwhen effective settings are available;unavailablewitheffective: nullwhen the provider doesn't report its current policy.limitsPermitted idle-timeout range, currently 120 through 14,400 seconds. session_lifetimeSession expiry and last-access timestamps, separate from the instance idle timeout. writableMirrors capabilities.lifecycle_policy_write; it doesn't grant Compute Write permission.For a running, writable compute, set a one-hour idle timeout:
az rest --method PATCH \ --url "${POLICY_URL}?api-version=${COMPUTE_API_VERSION}" \ --resource "${RESOURCE}" \ --headers "Foundry-Features=SessionCompute=V1Preview" \ --body '{"idle_timeout_seconds":3600}'Reference: Session compute permissions.
The response has the same policy shape as GET. PATCH changes only the provider's idle interval; it preserves auto-delete settings and suspend mode. A nonrunning compute returns 409 compute_not_ready.
The override doesn't change the agent definition and isn't persisted on the session. After stop/resume or replacement, check the current policy and reapply the override as needed. Publish a new agent version to change the durable baseline.
After an override, requested can still report the definition or platform value while effective reports the new interval. Don't treat that difference as a failed update. Increasing the idle timeout doesn't extend the session's separate expiry into an indefinite lifetime.
Inspect the egress policy summary
Read the network posture without enumerating the agent's allow list:
EGRESS_URL="${COMPUTE_URL}/egress-policy"
az rest --method GET \
--url "${EGRESS_URL}?api-version=${COMPUTE_API_VERSION}" \
--resource "${RESOURCE}" \
--headers "Foundry-Features=SessionCompute=V1Preview"
Reference: Interpret compute state and capabilities.
The result includes compute_id, mode, rule_count, and managed_by. It can also include default_action and traffic_inspection.
| Mode | Meaning |
|---|---|
open |
No egress restriction is configured. |
inspected |
Traffic is inspected but not blocked by policy. |
audit |
Rules are evaluated and violations logged without blocking. |
enforced |
Policy violations are blocked. |
unknown |
No recognized posture information is available. Don't treat it as open. |
Rule names, host patterns, and CIDRs aren't returned. There's no egress PATCH operation on compute; change the agent definition and publish a new version.
Stream container logs
Compute :logstream returns container stdout and stderr as server-sent events. It's the same underlying stream as session logstream, not the output of a particular exec command.
For a bounded streaming example, obtain a token without printing it and stream for up to 60 seconds:
ACCESS_TOKEN="$(az account get-access-token \
--resource "${RESOURCE}" --query accessToken --output tsv)"
LOG_URL="${COMPUTE_URL}:logstream?api-version=${COMPUTE_API_VERSION}"
curl --fail --no-buffer --max-time 60 \
--url "${LOG_URL}" \
--header "Authorization: Bearer ${ACCESS_TOKEN}" \
--header "Foundry-Features: SessionCompute=V1Preview"
unset ACCESS_TOKEN
Reference: Monitor hosted agent logs, az account get-access-token.
Read the text/event-stream response incrementally. Reaching the example's client time limit ends the connection with a curl timeout; it isn't an agent failure. Disconnecting from logs doesn't stop compute.
Keep tokens and log contents out of shell traces and diagnostic logs. For the existing azd workflow, use Monitor hosted agent logs.
Stop or delete the owning session
Stopping and deleting remain session operations, not compute routes. Use Stop a session to stop its runtime, and Delete a session only when you intend to remove that session and its persisted state.
The preview doesn't add compute :stop, :restart, or DELETE operations. Explicit :start operates on the existing session-owned compute.
Troubleshoot compute operations
| Symptom | Check |
|---|---|
Plain HTTP 404 without a compute error code |
Check the project endpoint, compute-scoped route, and API version. Include Foundry-Features: SessionCompute=V1Preview on the request. |
| Request rejected before the operation | API version, required feature header, endpoint authorization, and session isolation. Use the public project endpoint. |
compute_not_found |
Use an accessible session and the compute ID default. |
compute_operation_not_supported |
Check capabilities and the required agent-version opt-in. Permissions alone don't add provider support. |
compute_not_ready on start |
The sandbox might already be running, or the session might not be recoverable. Read the error details; don't assume a successful no-op. |
compute_not_ready on policy PATCH |
The instance must be running. Start it explicitly if appropriate, then reconsider the policy change. |
compute_lifecycle_policy_invalid |
Supply an integer idle_timeout_seconds within the reported limits. |
effective_status: unavailable |
Effective policy information is unavailable; don't substitute the requested baseline as proof of provider enforcement. |
| A runtime override or exposed port disappears | Re-read configuration after stop/resume or replacement; instance settings aren't durable session configuration. |