Run commands in hosted agent session compute

Use exec in Microsoft Foundry to diagnose an existing hosted agent session. Run a short shell command with HTTP :exec, or exchange streaming output and terminal messages with WebSocket exec/stream.

Exec supports managed sandboxes (aca_sandboxes) only. Sessions hosted on your own Azure Kubernetes Service (AKS) cluster, also called BYO-AKS, don't support exec.

Prerequisites

  • API version 2025-11-15-preview and the Foundry-Features: SessionCompute=V1Preview header for HTTP requests and WebSocket handshakes.
  • An existing, accessible hosted agent session with running managed compute or inactivity-stopped compute that can resume in place. Exec doesn't create a session, start customer-stopped compute, or recreate a terminated sandbox. See Handle inactive compute.
  • An agent version that opts in with definition.compute_primitives.exec set to true, and a default compute whose provider is aca_sandboxes and capabilities.exec is true.
  • A Microsoft Entra credential accepted by the endpoint's configured authorization scheme. With AzureRbac (or Entra), request scope https://ai.azure.com/.default. With AgentBlueprint, request a token for the individual agent blueprint instead.
  • For Azure RBAC authorization, the data action Microsoft.CognitiveServices/accounts/AIServices/agents/endpoints/sessions/computes/exec/action. Ask an authorized administrator to assign appropriately scoped permissions. General management access and endpoint invocation permission aren't substitutes.
  • Compute Read permission if you use the optional discovery request in this article. It's separate from permission to run exec commands. See Session compute permissions.
  • For WebSocket, a client that supports custom handshake headers, exec.v1 subprotocol negotiation, UTF-8 JSON text messages, and base64 decoding.
  • The example executables (/bin/echo, /bin/cat, and /bin/sh with printf) installed in your image.

The Foundry User built-in role includes the Exec and Compute Read 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 RBAC permissions above apply to AzureRbac (or Entra). For AgentBlueprint, follow Agent blueprint authorization and Acquire a token for the agent blueprint. In all cases, you need access to the target session under its isolation policy.

Select an execution API

Choose the API before constructing a command. Their command formats aren't interchangeable.

Requirement HTTP :exec WebSocket exec/stream
Command format One shell command string. Executable and separate args; no implicit shell.
Output Collected stdout and stderr in one JSON result. Base64 stdout and stderr messages while the connection is open.
Input and terminal controls No stdin or terminal messages. Protocol messages for stdin, terminal resize, and stdin closure.
Completion Inspect timed_out, exit_code, and truncation flags, not just HTTP status. Require an exit_code message and a normal WebSocket close.
Best fit Short, bounded diagnostics. Streaming output, stdin, or terminal workflows.

Both use API version 2025-11-15-preview, the Foundry-Features: SessionCompute=V1Preview header, and the compute-scoped route. The currently supported compute ID is default.

Keep tokens out of URLs and logs. Connect through the public project endpoint. Use the documented authentication and feature headers; don't add headers intended for service-to-service authentication inside Foundry.

Identify running compute

Use your project endpoint, agent name, and existing session ID. URL-encode each path segment. The compute URL has this form:

https://{account}.services.ai.azure.com/api/projects/{project}/agents/{agent}/endpoint/sessions/{session}/computes/default

Reference: Manage hosted agent sessions.

If you have Compute Read permission, make this optional discovery request. In the following HTTP examples, replace {{computeUrl}} with the compute URL and {{accessToken}} with your credential's bearer token.

GET {{computeUrl}}?api-version=2025-11-15-preview
Authorization: Bearer {{accessToken}}
Foundry-Features: SessionCompute=V1Preview

Reference: Prerequisites.

Check capabilities.exec and the reported state. A GET doesn't resume compute, and the reported state can briefly differ from the sandbox's actual state. Don't use repeated exec calls as a readiness probe.

This GET request isn't a required exec preflight. An Exec-only client can omit it when its caller supplies an accessible, qualified compute.

Handle inactive compute

Both HTTP :exec and WebSocket exec/stream check the sandbox before executing a command. If inactivity stops a resumable sandbox, exec restarts that same sandbox. It then checks the session and sandbox again before running the command or upgrading to WebSocket.

Condition Action
Compute is running Continue with the command after authorization and readiness checks.
Inactivity stopped compute and in-place resume is possible Resume first, then execute the command once. Allow extra time for wake-up.
You stopped the session yourself exec rejects it with resume_rejected_on_user_stopped. Use explicit compute :start first if you intend to restart the runtime.
Backing sandbox is terminated or requires replacement exec doesn't recreate it. Consider explicit :start for a recoverable volume-backed session.
Session is missing, expired, failed, or inaccessible Return an error; don't create a new logical session.

Implicit exec wake-up doesn't require a separate Compute Write grant; the exec operation still requires its dedicated authorization and session access. Explicit :start requires Compute Write and returns a conflict if the instance is already running.

Wake-up preserves the same session, agent version, and sandbox. If the session now points to a different sandbox, exec returns compute_not_ready instead of running the command there.

Wake-up isn't command replay or a reconnect mechanism. The service doesn't rerun a command after it starts. If wake-up fails before WebSocket upgrade, the client receives a normal HTTP error.

For explicit start, lifecycle policy, and the stable compute resource model, see Manage hosted agent session compute.

Run a shell command over HTTP

The HTTP exec method runs one shell command and returns the collected output.

  1. Send this request to the existing compute resource:

    POST {{computeUrl}}:exec?api-version=2025-11-15-preview
    Authorization: Bearer {{accessToken}}
    Foundry-Features: SessionCompute=V1Preview
    Content-Type: application/json
    
    {
      "command": "printf 'Hello\\n'",
      "timeout_seconds": 10
    }
    

    Reference: HTTP request and result fields.

  2. Inspect the result. A completed command can return:

    {
      "object": "session.compute.exec_result",
      "exit_code": 0,
      "timed_out": false,
      "stdout": "Hello\n",
      "stderr": "",
      "duration_ms": 25,
      "stdout_truncated": false,
      "stderr_truncated": false
    }
    

    Reference: HTTP request and result fields.

  3. Treat a nonzero exit_code as a command failure, even when the HTTP response is successful. Check both truncation flags before treating output as complete.

The sandbox shell interprets the HTTP command. Don't build it by concatenating untrusted values. Use WebSocket executable-plus-arguments when you don't need shell interpretation, or apply quoting appropriate to the target shell.

HTTP request and result fields

Request field Meaning
command Required nonempty shell command, up to 32,768 UTF-16 code units.
timeout_seconds Optional server wait deadline, from 1 through 120 seconds. Default: 60 seconds.
provider_options Optional provider-specific settings. Omit unless your environment documents a supported option.
Result field Meaning
object session.compute.exec_result.
exit_code Process exit code when established; null or absent on timeout.
timed_out The server stopped waiting. It doesn't prove the command stopped.
stdout, stderr Collected text, which can be null or absent when unavailable.
duration_ms Time spent waiting for the command, in milliseconds.
stdout_truncated, stderr_truncated Whether the corresponding stream exceeded the service's 262,144 UTF-16-code-unit limit. These limits aren't byte counts.

Handle a timeout without replaying the command

A server deadline produces a result with timed_out: true and no established exit code, rather than a retryable timeout status. The command might still be running.

Set your client's deadline longer than timeout_seconds to allow for authentication, idle wake-up, readiness, connection establishment, and response delivery. A client timeout, connection loss, or lost response leaves execution uncertain.

Disable automatic retries for exec requests. Don't replay a command because of a timeout, truncation, server error, or ambiguous response. First inspect the session and any effects through a separate, authorized workflow.

Run an executable over WebSocket

Use wss and append /exec/stream to the compute URL. This example runs /bin/echo without a shell or stdin.

  1. Open a WebSocket with these handshake headers:

    GET {{computeUrl}}/exec/stream?api-version=2025-11-15-preview
    Authorization: Bearer {{accessToken}}
    Foundry-Features: SessionCompute=V1Preview
    Sec-WebSocket-Protocol: exec.v1
    

    Reference: Client and server messages.

    Let your WebSocket library generate the standard upgrade headers. Verify the HTTP upgrade succeeds and the negotiated subprotocol is exactly exec.v1 before sending a command.

  2. Send exactly one start message as the first WebSocket text message:

    {
      "type": "start",
      "start": {
        "command": "/bin/echo",
        "args": ["Hello"],
        "tty": false,
        "stdin": false
      }
    }
    

    Reference: Client and server messages.

  3. Read continuously. A successful exchange includes an execution correlation identifier, output, and a process exit:

    {"type":"session_id","session_id":"execution-correlation"}
    {"type":"stdout","data":"SGVsbG8K"}
    {"type":"exit_code","exit_code":0}
    

    Reference: Client and server messages.

    Each line represents a separate message. Decode data with base64 to obtain Hello and a newline. Don't treat message boundaries as text-line or UTF-8 character boundaries.

  4. Require both a valid exit_code and normal close code 1000. An error message, premature close, malformed message, or connection loss isn't successful completion. A nonzero process exit remains a command failure, not a transport failure.

The server's session_id is an execution correlation value, not your hosted session ID or a reconnect token. Each connection owns one command. Don't send a second start, reconnect to resume, or replay a command after connection loss.

Client and server messages

Client messages have these shapes:

Message Fields
start Nested start object with command, args, tty, and stdin. Optional environment, working_directory, and terminal_size (height, width).
stdin Base64 data. Use when stdin is enabled in the start message.
resize Flat integer height and width. Use with a terminal.
close_stdin No payload fields. Requests EOF; it isn't cancellation.

Server messages are session_id with session_id, stdout or stderr with base64 data, exit_code with integer exit_code, or error with an error object containing code and message. Treat error as failure, and avoid logging its content.

Send input and close stdin

For pipe-style input without a terminal, set tty to false and stdin to true. For example, start /bin/cat:

{
  "type": "start",
  "start": {
    "command": "/bin/cat",
    "args": [],
    "tty": false,
    "stdin": true
  }
}

Reference: Client and server messages.

Send base64-encoded input, then send close_stdin when you have no more input. Each line in the following example is a separate WebSocket text message:

{"type":"stdin","data":"SGVsbG8K"}
{"type":"close_stdin"}

Reference: Client and server messages.

Read stdout and stderr continuously while sending input. Reading both streams avoids deadlocks when the process produces output before it finishes consuming input. In this example, /bin/cat echoes Hello and a newline, then exits after EOF. Require the exit code and normal close before reporting completion.

close_stdin closes only the command's input. Continue reading until the command exits; don't close the WebSocket to signal EOF.

Use a terminal and resize it

For terminal input, set tty and stdin to true and include an initial terminal_size. For example:

{
  "type": "start",
  "start": {
    "command": "/bin/sh",
    "args": [],
    "tty": true,
    "stdin": true,
    "terminal_size": {"height": 24, "width": 80}
  }
}

Reference: Client and server messages.

Read output while sending input to avoid deadlocks. Terminal output can merge stdout and stderr and include echo or terminal escape sequences. A resize is a separate message:

{"type":"resize","height":30,"width":100}

Reference: Client and server messages.

This protocol doesn't include interrupt, terminate, detach, or reconnect messages. EOF isn't an interrupt. Closing the connection doesn't prove termination of the command or its descendants.

Apply limits and protect diagnostic data

Set limits for complete messages, decoded data, accumulated output, and total connection time in your client.

Protocol limit Maximum
First start message 64 KiB.
Complete data message 1 MiB.
Decoded data in one message 750 KiB.
Client control message, excluding start and stdin data 4 KiB.
Server control message 16 KiB.

Service, gateway, and client deadlines can end a connection. A client deadline doesn't extend a service deadline, and source defaults aren't regional availability or duration guarantees.

Exec can access files, credentials, and network resources available inside the session. Use least privilege, preserve isolation, and don't log bearer tokens, command arguments, environment values, stdin, stdout, or stderr. Display output only in the intended diagnostic interface.

Native browser WebSocket APIs can't set the required custom handshake headers. These examples target server-side or native clients. Don't move bearer tokens into URLs or assume a browser-specific authentication workaround is supported.

Clean up diagnostic work

Use short-lived commands, and avoid background or detached processes. Close sockets and client credentials when finished. Don't delete an existing session, agent, or version merely because a diagnostic client exits.

If you create a dedicated session for a test, clean up only that session through its lifecycle API. Neither session deletion, socket closure, nor client disposal proves full process-tree termination. Confirm unexpected continuing work through an authorized operational workflow.

Commands consume the session's compute resources. Apply your environment's normal compute and lifecycle cost controls; a disconnected client doesn't establish that remote work or compute consumption has ended.

Troubleshoot exec

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 HTTP requests and WebSocket handshakes.
HTTP or upgrade rejection API version, compute-scoped route, required feature header, token scope, endpoint authorization, and session isolation. Don't bypass the public gateway.
Readiness GET denied but exec is authorized Compute Read and Exec are separate permissions. Omit optional discovery or request Compute Read access.
Compute not ready or capability unavailable Confirm the version opt-in and supported compute. Only inactivity-stopped compute can wake in place; use explicit start when appropriate for customer-stopped or recoverable terminated compute.
Exec unavailable on a BYO-AKS session Exec currently supports only managed aca_sandboxes compute. Permissions or agent-version opt-ins don't add exec support to BYO-AKS sessions.
resume_rejected_on_user_stopped The session was stopped explicitly. Start its compute separately with the required Compute Write access before retrying an intended command.
HTTP success with a failed command Inspect timed_out, exit_code, and both truncation flags.
Stream closes without an exit code Treat the result as incomplete or unknown. Don't retry automatically.
Command waits for more input Set stdin: true in start, send valid base64 input, and send close_stdin when input is complete. Keep reading output while the command exits.
Output appears incomplete Check truncation or client limits; drain streaming output concurrently and validate terminal completion.