Deploy Containerized Agents on Azure

This skill covers building container-based hosted agents in Azure AI Foundry using ImageBasedHostedAgentDefinition from the Azure AI Projects SDK (requiring version 2.0.0b3 or later). Before creating a hosted agent, four prerequisites must be in place: a container image built and pushed to Azure Container Registry, an AcrPull role grant on that ACR for the project's managed identity, an account-level capability host configured with enablePublicHostingEnvironment=true, and the correct SDK version. Authentication always uses DefaultAzureCredential against an AIProjectClient pointed at the project's endpoint.

The core workflow creates an agent via client.agents.create_version, passing an ImageBasedHostedAgentDefinition with required container_protocol_versions (a list of ProtocolVersionRecord objects - currently AgentProtocol.RESPONSES version v1 is the available protocol) and image (the full registry/image:tag path), plus optional cpu, memory, tools, and environment_variables. Resource allocation has documented limits: CPU ranges from a minimum of 0.5 to a maximum of 4 cores (default 1), and memory ranges from 1Gi to 8Gi (default 2Gi). Tools can include code_interpreter, file_search, and custom MCP servers specified with a server_label and server_url, combinable in a single agent definition. Environment variables pass configuration into the container, with an explicit best practice against hardcoding secrets - use environment variables or Azure Key Vault instead. Agent versions can be listed with client.agents.list_versions and removed with client.agents.delete_version.

An async variant is also documented, using azure.identity.aio.DefaultAzureCredential and azure.ai.projects.aio.AIProjectClient inside async with blocks for non-blocking agent creation. Documented common errors map directly to fixes: ImagePullBackOff traces back to a missing AcrPull role grant, InvalidContainerImage to a wrong or missing image path/tag, CapabilityHostNotFound to a missing account-level capability host, and ProtocolVersionNotSupported to using anything other than AgentProtocol.RESPONSES version v1.

Use this when creating hosted agents in Azure AI Foundry that run from a custom container image rather than a purely SDK-configured agent. Best practices called out include versioning container images with specific tags rather than latest in production, starting with minimal CPU/memory and scaling up only as needed, wrapping agent creation in try/except error handling, and deleting unused agent versions to free resources.

Install with:

pip install azure-ai-projects>=2.0.0b3 azure-identity

Required configuration is AZURE_AI_PROJECT_ENDPOINT. Inputs are a container image reference, protocol version, resource allocation, tool list, and environment variables; output is a created agent object exposing name, version, and state, confirmable via list_versions.

Built on the Azure AI Projects SDK's AIProjectClient, Azure Identity's DefaultAzureCredential, Azure Container Registry for image hosting, and optional MCP server tools alongside built-in code_interpreter/file_search tools.

Python developers deploying custom containerized agents into Azure AI Foundry who need concrete patterns for agent creation, resource sizing, tool configuration, and troubleshooting common deployment errors.