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 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-previewand theFoundry-Features: SessionCompute=V1Previewheader 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.portsset totrue. 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/readfor discovery andsessions/computes/ports/writefor exposure changes. These are separate data actions underMicrosoft.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.
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.
Inspect the port number, name, and protocol in the
session.compute.portresult.A new exposure returns HTTP
201. Repeating PUT with the same effective configuration returns200and 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. |