Manage hosted agent session compute

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-preview and the Foundry-Features: SessionCompute=V1Preview request 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 and az rest. The log-stream example also uses curl.
  • 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 :start and lifecycle-policy changes. See Session compute permissions.
  • A compute that supports the operation you need. Check capabilities.start or capabilities.lifecycle_policy_write before 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.

  1. 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.

  2. Inspect the result. Success returns HTTP 200 and the running session.compute resource 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.

  1. 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.

  2. Compare requested with effective, and check writable and limits.

    Field Meaning
    requested The baseline idle timeout and its source: agent_definition or platform_default.
    effective The provider's current auto-suspend, idle-timeout, suspend-mode, and auto-delete settings.
    effective_status provider when effective settings are available; unavailable with effective: null when the provider doesn't report its current policy.
    limits Permitted idle-timeout range, currently 120 through 14,400 seconds.
    session_lifetime Session expiry and last-access timestamps, separate from the instance idle timeout.
    writable Mirrors capabilities.lifecycle_policy_write; it doesn't grant Compute Write permission.
  3. 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.