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 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-previewand theFoundry-Features: SessionCompute=V1Previewheader 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.execset totrue, and a default compute whoseproviderisaca_sandboxesandcapabilities.execistrue. - A Microsoft Entra credential accepted by the endpoint's configured authorization scheme. With
AzureRbac(orEntra), request scopehttps://ai.azure.com/.default. WithAgentBlueprint, 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
execcommands. See Session compute permissions. - For WebSocket, a client that supports custom handshake headers,
exec.v1subprotocol negotiation, UTF-8 JSON text messages, and base64 decoding. - The example executables (
/bin/echo,/bin/cat, and/bin/shwithprintf) 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.
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.
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.
Treat a nonzero
exit_codeas 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.
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.v1Reference: 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.v1before sending a command.Send exactly one
startmessage as the first WebSocket text message:{ "type": "start", "start": { "command": "/bin/echo", "args": ["Hello"], "tty": false, "stdin": false } }Reference: Client and server messages.
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
datawith base64 to obtainHelloand a newline. Don't treat message boundaries as text-line or UTF-8 character boundaries.Require both a valid
exit_codeand normal close code1000. Anerrormessage, 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. |