Expose hosted agent session ports

Use the preview port management APIs in Microsoft Foundry to expose an application port in a hosted agent session, inspect its configuration, and remove the exposure when you're finished.

This guide covers port exposure management, not application requests through an exposed port. Exposing a port doesn't start an application or verify its health.

Prerequisites

  • API version 2025-11-15-preview and the Foundry-Features: SessionCompute=V1Preview header on port management requests.
  • An existing, accessible session with running managed compute and capabilities.ports: true. See Manage session compute.
  • An agent version with definition.compute_primitives.ports set to true. See Enable optional primitives.
  • An application listening on the chosen user port inside that session. The example uses port 3000.
  • Azure CLI, authenticated with az login, and Bash.
  • Authorization under the agent endpoint's policy and access under the session's isolation policy.
  • For Azure RBAC authorization, sessions/computes/ports/read for discovery and sessions/computes/ports/write for exposure changes. These are separate data actions under Microsoft.CognitiveServices/accounts/AIServices/agents/endpoints/. See Session compute permissions.

The Foundry User built-in role includes these port data actions and Compute Read 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 Bash examples for port management use AzureRbac (or Entra) with RESOURCE="https://ai.azure.com". They don't acquire tokens for AgentBlueprint.

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.

Compute Read is also required if you use the optional compute discovery request in the management guide. General endpoint invocation permission isn't a substitute for port permissions.

Expose an application port

Replace the endpoint, agent, and session 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"
PORT_NUMBER=3000

COMPUTE_URL="${PROJECT_ENDPOINT}/agents/${AGENT_NAME}"
COMPUTE_URL+="/endpoint/sessions/${SESSION_ID}/computes/default"
PORTS_URL="${COMPUTE_URL}/ports"
PORT_RESOURCE_URL="${PORTS_URL}/${PORT_NUMBER}"

Reference: Manage session compute.

For delegated identity or header-based isolation, include the same permitted identity or isolation headers used to access the session. Knowing the port resource URL doesn't bypass session isolation.

  1. Expose the application's port:

    az rest --method PUT \
      --url "${PORT_RESOURCE_URL}?api-version=${COMPUTE_API_VERSION}" \
      --resource "${RESOURCE}" \
      --headers "Foundry-Features=SessionCompute=V1Preview" \
      --body '{"name":"web","protocol":"http"}'
    

    Reference: Choose a valid port configuration.

  2. Inspect the port number, name, and protocol in the session.compute.port result.

    A new exposure returns HTTP 201. Repeating PUT with the same effective configuration returns 200 and the existing exposure.

Inspect exposed ports

List the session's exposed user ports:

az rest --method GET \
  --url "${PORTS_URL}?api-version=${COMPUTE_API_VERSION}" \
  --resource "${RESOURCE}" \
  --headers "Foundry-Features=SessionCompute=V1Preview"

Reference: Choose a valid port configuration.

The list envelope contains object: list, data, and has_more. Nonempty pages also contain first_id and last_id. Port cursor IDs are port numbers represented as strings.

Lists accept limit from 1 through 100, order of asc or desc, and either after or before. Defaults are limit=20 and order=asc.

Read one exposure:

az rest --method GET \
  --url "${PORT_RESOURCE_URL}?api-version=${COMPUTE_API_VERSION}" \
  --resource "${RESOURCE}" \
  --headers "Foundry-Features=SessionCompute=V1Preview"

Reference: Choose a valid port configuration.

An unexposed port returns 404 compute_port_not_found. The platform control port isn't returned by list or get.

Choose a valid port configuration

The port number is in the route, not the request body.

Setting Constraint
Port number 1024 through 65535, excluding reserved platform port 8088.
Exposure count At most eight user ports per compute.
name Optional, unique per compute, and at most 32 characters. Use lowercase letters and digits, with hyphens only between them. Defaults to port-<number>.
protocol http or http2; defaults to http.
provider_options Optional provider-specific settings. Omit unless your environment documents a supported option.

A repeated PUT with a different effective name or protocol returns 409 compute_port_conflict. Remove the existing exposure before changing its configuration. Reusing another port's name also returns that conflict.

Authentication isn't configurable on a port. Unknown fields, including auth_mode and allowed_*, are rejected. This preview isn't arbitrary TCP forwarding or anonymous public ingress.

Re-expose ports after runtime changes

Exposed ports apply to the current sandbox, not permanently to the session. Don't assume they survive stop/resume or sandbox replacement. Read the exposed ports again and re-expose the required ports after the runtime is ready.

Port management operations require running compute; they don't provide exec's automatic idle wake-up. Use Start stopped compute when an explicit start is appropriate.

Remove the exposure

Remove only the port exposure you intend to close:

az rest --method DELETE \
  --url "${PORT_RESOURCE_URL}?api-version=${COMPUTE_API_VERSION}" \
  --resource "${RESOURCE}" \
  --headers "Foundry-Features=SessionCompute=V1Preview"

Reference: Session compute permissions.

Success returns HTTP 204 with no response body. Removing a nonexistent exposure returns 404 compute_port_not_found; it isn't an idempotent success.

Removing an exposure doesn't stop the application, stop compute, or delete the session. Close test applications through their own lifecycle and delete a test-owned session only if you intend to remove its state. See Manage hosted agent sessions.

Troubleshoot port management

Symptom Check
Plain HTTP 404 without a compute error code Check the project endpoint and port route. Include Foundry-Features: SessionCompute=V1Preview and use API version 2025-11-15-preview for port management requests.
404 compute_port_not_found The requested port isn't exposed. List the current exposures and expose the application's port if appropriate.
compute_operation_not_supported Check provider capabilities and the version's ports opt-in.
compute_not_ready Ensure the instance is running. Port calls don't resume it automatically.
compute_port_reserved Choose a user port other than 8088.
compute_port_limit_exceeded Remove an unneeded exposure before adding another.
compute_port_conflict Use a unique name; remove an existing exposure before changing its configuration.
Exposures disappear after resume Read and recreate the instance's exposures as needed.