Deploy a hosted agent

Deploy your containerized agent code to Foundry Agent Service using the Python SDK or REST API.

This article shows you how to deploy a containerized agent to Foundry Agent Service by using the Azure Developer CLI (azd), the Python SDK, or the REST API. Choose a deployment method by using the selector at the top of the article. Use the SDK or REST approaches when you want to manage agent deployments directly from your own applications or services.

If you’re deploying for the first time or want a guided walkthrough, see the Quickstart: Create and deploy a Hosted agent. The Azure Developer CLI (azd) and VS Code extension handle building, pushing, versioning, and RBAC configuration automatically.

Prefer a Docker-less inner loop? You can also deploy a hosted agent directly from source code - upload a .zip of your Python or .NET code and the platform builds and hosts it for you.

Deployment lifecycle

Every Hosted agent deployment follows this sequence:

1. Build and push - Package your agent code into a container image and push it to Azure Container Registry.
2. Create an agent version - Register the image with Foundry Agent Service. The platform provisions infrastructure and creates a dedicated Entra agent identity.
3. Poll for status - Wait for the version status to reach active.
4. Invoke - Send requests to the agent’s dedicated endpoint.

Prerequisites

• A Microsoft Foundry project.
• Agent code using a supported framework.
• Docker Desktop installed for local container development.
• Azure CLI version 2.80 or later.

Required permissions

You need the Foundry Project Manager role at the project scope to deploy a hosted agent. This role grants the data-plane permissions to create and update agents, plus the ability to create role assignments for the platform-created agent identity if needed. For a detailed breakdown of the permissions involved, see Hosted agent permissions reference.

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 platform creates a dedicated Microsoft Entra agent identity for each hosted agent at deploy time. This identity is a service principal that your running container uses to call models and tools. You don’t need to configure managed identities manually. The agent identity can access model inferencing through the project endpoint and session storage by default. For external resources (for example, your own Azure Storage), assign RBAC roles manually to the agent’s Microsoft Entra ID. For more information, see Agent access beyond defaults.

If you use azd or the VS Code extension, the tooling handles most RBAC assignments automatically, including Container Registry Repository Reader for the project managed identity (image pulls).

For more information, see Authentication and authorization.

Support for placing your Hosted agent’s Azure Container Registry behind a private network (private endpoint with public network access disabled) depends on when the Foundry project was created. Projects created after June 25, 2026 support a private registry. Projects created before that date require the registry to be reachable over its public endpoint so the platform can pull the image. Existing projects aren’t affected. For the full list of network constraints, see Limitations.

Container requirements

Your container image must meet the following requirements to run on the Hosted agent platform.

The hosting platform requires x86_64 (linux/amd64) container images. If you build on Apple Silicon or other ARM-based machines, use docker build --platform linux/amd64 . to avoid producing an incompatible ARM image.

Protocol libraries

Hosted agents communicate with the Foundry gateway through protocol libraries. Choose the protocol that matches your agent’s interaction pattern:

Protocol	Python library	.NET library	Endpoint	Best for
Responses	azure-ai-agentserver-responses	Azure.AI.AgentServer.Responses	/responses	Conversational chatbots, streaming, multi-turn with platform-managed history
Invocations	azure-ai-agentserver-invocations	Azure.AI.AgentServer.Invocations	/invocations	Webhook receivers, non-conversational processing, custom async workflows
Invocations (WebSocket)	azure-ai-agentserver-invocations	Azure.AI.AgentServer.Invocations	/invocations_ws	Bidirectional streaming: real-time voice agents, interactive media

The WebSocket protocol uses the identifier invocations_ws and ships in the same azure-ai-agentserver-invocations package as the HTTP /invocations route, so one container can serve both. Use it when you need persistent, full-duplex streaming - for example, sending microphone PCM to the agent and receiving synthesized audio back. For voice scenarios, see Build a voice agent with hosted agents.

A single container can expose multiple protocols simultaneously by declaring them when you create the agent - in the protocols field of the azure.ai.agent service in azure.yaml, an SDK call, or a REST API request - and importing the required libraries. Use the protocol libraries within your existing framework, whether that’s Microsoft Agent Framework, LangChain, or custom code.

Responses protocol library

The Python and .NET libraries for the Responses protocol implement the Azure AI Responses API. Import the package and implement the IResponseHandler interface. The library handles routing, streaming with server-sent events (SSE), background execution, cancellation, caching, and response lifecycle management.

IResponseHandler

IResponseHandler is the core abstraction you implement. The library calls CreateAsync for each incoming request and delivers the returned IAsyncEnumerable<ResponseStreamEvent> to clients through SSE:

public class EchoHandler : ResponseHandler
{
    public override IAsyncEnumerable<ResponseStreamEvent> CreateAsync(
        CreateResponse request,
        ResponseContext context,
        CancellationToken cancellationToken)
    {
        return new TextResponse(context, request,
            createText: async ct =>
            {
                var input = await context.GetInputTextAsync(cancellationToken: ct);
                return $"Echo: {input}";
            });
    }
}

ResponseEventStream

ResponseEventStream manages sequenceNumber, outputIndex, contentIndex, itemId, and the full Response lifecycle automatically. Each yield return maps one-to-one to an SSE event, so you don’t need to track this state yourself.

Streaming and background modes

• Streaming mode (default): SSE events are delivered in real time to the connected client.
• Background mode: The handler runs to completion without a connected SSE client. Events are buffered and available for replay through GET /responses/{id}.

Response lifecycle

The library orchestrates the complete response lifecycle: created -> in_progress -> completed (or failed or cancelled). The library also manages cancellation, error handling, and terminal event guarantees automatically.

Thread safety

All service instances registered through AddResponsesServer() are thread-safe. Handler instances are scoped per-request.

For detailed handler implementation guidance, see the handler implementation guide. For runnable examples, see the Responses protocol samples.

Health endpoints

The protocol libraries automatically expose a /readiness endpoint for platform health checks. You don’t need to implement this yourself.

Port

Containers serve traffic on port 8088 locally. In production, the Foundry gateway handles routing - your container doesn’t need to expose a public port.

Platform-injected environment variables

The Hosted agent platform automatically injects environment variables into your container at runtime. Your code can read these variables without declaring them in the env map of the azure.ai.agent service in azure.yaml or in SDK and REST environment variable settings. The FOUNDRY_* prefix is reserved for platform use.

Variable	Purpose
FOUNDRY_PROJECT_ENDPOINT	Foundry project endpoint URL
FOUNDRY_PROJECT_ARM_ID	Foundry project ARM resource ID
FOUNDRY_AGENT_NAME	Name of the running agent
FOUNDRY_AGENT_VERSION	Version of the running agent
FOUNDRY_AGENT_SESSION_ID	Session ID for the current request (hosted containers only)
APPLICATIONINSIGHTS_CONNECTION_STRING	Application Insights connection string for telemetry

Don’t redeclare platform-injected variables in azure.yaml - they’re set automatically.

Variables that you declare yourself, such as MODEL_DEPLOYMENT_NAME or toolbox MCP endpoints, go in the env map of the azure.ai.agent service in azure.yaml or the SDK create_version call.

When you deploy your hosted agent to Foundry Agent Service, the platform automatically injects an Application Insights connection string into your agent container as an environment variable, enabling OpenTelemetry tracing by default. To view distributed traces, requests, and dependencies, open the Application Insights resource provisioned during setup in the Azure portal and navigate to Investigate > Transaction search or Performance. Use azd ai agent monitor for live console logs. When AppInsights is enabled, this project logs traces to help monitor and evaluate user level interactions with agents. Project members provided with Log Analytics Reader role in AppInsights can view trace data, which might contain personal data and/or Customer Content. If the underlying Log Analytics tables are protected, members instead need the Privileged Monitoring Data Reader role to view that trace data. Review what trace data is collected and who can view and use this data. Additional Azure Monitor App Insights pricing might apply. Learn more.

Reference project connections in environment variables

Instead of hard-coding secrets (API keys, tokens, endpoints) into azure.yaml or your image, pull them from a Foundry project connection at sandbox start. Any value that you declare as an environment variable can be a placeholder expression that the platform resolves before your container starts.

Placeholder syntax

A placeholder has the form ${{connections.<name>.<path>}}, where <name> is the connection’s resource name (visible in the portal under Project details > Connected resources) and <path> is one of:

Path	Resolves to
credentials.<field>	A secret field on the connection
target	The connection’s target property (for example, an endpoint URL)
metadata.<field>	A field under the connection’s metadata

The field name to use depends on the connection category:

Connection category	Field name in placeholder
ApiKey, AppInsights	Always key—for example, credentials.key
CustomKeys	The key name you supplied when creating the connection—for example, credentials.github_token

Example

First, create a CustomKeys connection on the project that holds the secret. See Add a new connection in Microsoft Foundry. Then reference it from the env map in the azure.ai.agent service in azure.yaml:

services:
  my-agent:
    host: azure.ai.agent
    env:
      MODEL_DEPLOYMENT_NAME: gpt-5-mini
      GITHUB_TOKEN: ${{connections.agent-secrets.credentials.github_token}}

At sandbox start, Foundry resolves the placeholder and injects the resolved value as a plain environment variable. Your code reads it like any other env var:

import os
token = os.environ["GITHUB_TOKEN"]

A GET on the agent version returns the literal ${{...}} text—the resolved secret is never echoed back through the management API.

Considerations

• Create the connection before you deploy the version. If the connection or the referenced field is missing at sandbox start, the placeholder doesn’t resolve and the variable is empty.
• Secrets are write-only. GET on a connection returns credentials: null. Verify resolution by reading the env var from inside your running container, not by inspecting the connection.
• Record CustomKeys field names yourself. The management API never echoes them back after creation. Keep them next to your agent source (for example, in IaC templates or alongside azure.yaml) so you can construct placeholders later without guessing.
• Foundry manages the backing secret name. When you create the connection, Foundry stores the value in Key Vault under a name it chooses — you can’t reference a preexisting Key Vault secret by name. To attach your own Key Vault as the backing store, see Set up a Key Vault connection.

Package and test your agent locally

Before deploying to Foundry, validate your agent works locally using the protocol library. The container serves the same endpoints locally as it does in production.

Test the Responses protocol

POST http://localhost:8088/responses
Content-Type: application/json

{
    "input": "Where is Seattle?",
    "stream": false
}

Test the Invocations protocol

POST http://localhost:8088/invocations
Content-Type: application/json

{
    "message": "Hello!"
}

Clean up resources

To prevent charges, clean up resources when finished. Agent compute is deprovisioned after 15 minutes of inactivity, so there’s no cost when an agent isn’t serving requests.

Troubleshooting

Provisioning errors surface on the version object’s error.code and error.message fields. Check the version status after creation to identify issues.

Error code	HTTP code	Solution
image_pull_failed	400	Verify the image URI. Confirm that the project managed identity has Container Registry Repository Reader on the ACR and that the registry’s azureADAuthenticationAsArmPolicy policy status is enabled
SubscriptionIsNotRegistered	400	Register the subscription provider
InvalidAcrPullCredentials	401	Fix managed identity or registry RBAC
UnauthorizedAcrPull	403	Provide correct credentials or identity
AcrImageNotFound	404	Correct image name/tag or publish image
RegistryNotFound	400/404	Fix registry DNS or network reachability

For 5xx errors, contact Microsoft support.

For detailed RBAC requirements and permission troubleshooting, see Hosted agent permissions reference.

Next steps

Manage Hosted agent lifecycle

Related content

• What are Hosted agents?
• Add a content safety guardrail to a hosted agent
• Agent identity concepts
• Agent applications

• Azure Container Registry documentation