
About
Build container-based Foundry Agents with Azure AI Projects SDK (ImageBasedHostedAgentDefinition). Use when creating hosted agents with custom container images in Azure AI Foundry.
name: agents-v2-py description: "Build container-based Foundry Agents with Azure AI Projects SDK (ImageBasedHostedAgentDefinition). Use when creating hosted agents with custom container images in Azure AI Foundry." risk: unknown source: community date_added: "2026-02-27"
Azure AI Hosted Agents (Python)
Build container-based hosted agents using ImageBasedHostedAgentDefinition from the Azure AI Projects SDK.
Installation
pip install azure-ai-projects>=2.0.0b3 azure-identity
Minimum SDK Version: 2.0.0b3 or later required for hosted agent support.
Environment Variables
AZURE_AI_PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
Prerequisites
Before creating hosted agents:
- Container Image - Build and push to Azure Container Registry (ACR)
- ACR Pull Permissions - Grant your project's managed identity
AcrPullrole on the ACR - Capability Host - Account-level capability host with
enablePublicHostingEnvironment=true - SDK Version - Ensure
azure-ai-projects>=2.0.0b3
Authentication
Always use DefaultAzureCredential:
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
credential = DefaultAzureCredential()
client = AIProjectClient(
endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
credential=credential
)
Core Workflow
1. Imports
import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
ImageBasedHostedAgentDefinition,
ProtocolVersionRecord,
AgentProtocol,
)
2. Create Hosted Agent
client = AIProjectClient(
endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential()
)
agent = client.agents.create_version(
agent_name="my-hosted-agent",
definition=ImageBasedHostedAgentDefinition(
container_protocol_versions=[
ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
],
cpu="1",
memory="2Gi",
image="myregistry.azurecr.io/my-agent:latest",
tools=[{"type": "code_interpreter"}],
environment_variables={
"AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
"MODEL_NAME": "gpt-4o-mini"
}
)
)
print(f"Created agent: {agent.name} (version: {agent.version})")
3. List Agent Versions
versions = client.agents.list_versions(agent_name="my-hosted-agent")
for version in versions:
print(f"Version: {version.version}, State: {version.state}")
4. Delete Agent Version
client.agents.delete_version(
agent_name="my-hosted-agent",
version=agent.version
)
ImageBasedHostedAgentDefinition Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| container_protocol_versions | list[ProtocolVersionRecord] | Yes | Protocol versions the agent supports |
| image | str | Yes | Full container image path (registry/image:tag) |
| cpu | str | No | CPU allocation (e.g., "1", "2") |
| memory | str | No | Memory allocation (e.g., "2Gi", "4Gi") |
| tools | list[dict] | No | Tools available to the agent |
| environment_variables | dict[str, str] | No | Environment variables for the container |
Protocol Versions
The container_protocol_versions parameter specifies which protocols your agent supports:
from azure.ai.projects.models import ProtocolVersionRecord, AgentProtocol
# RESPONSES protocol - standard agent responses
container_protocol_versions=[
ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
]
Available Protocols:
| Protocol | Description |
|----------|-------------|
| AgentProtocol.RESPONSES | Standard response protocol for agent interactions |
Resource Allocation
Specify CPU and memory for your container:
definition=ImageBasedHostedAgentDefinition(
container_protocol_versions=[...],
image="myregistry.azurecr.io/my-agent:latest",
cpu="2", # 2 CPU cores
memory="4Gi" # 4 GiB memory
)
Resource Limits: | Resource | Min | Max | Default | |----------|-----|-----|---------| | CPU | 0.5 | 4 | 1 | | Memory | 1Gi | 8Gi | 2Gi |
Tools Configuration
Add tools to your hosted agent:
Code Interpreter
tools=[{"type": "code_interpreter"}]
MCP Tools
tools=[
{"type": "code_interpreter"},
{
"type": "mcp",
"server_label": "my-mcp-server",
"server_url": "https://my-mcp-server.example.com"
}
]
Multiple Tools
tools=[
{"type": "code_interpreter"},
{"type": "file_search"},
{
"type": "mcp",
"server_label": "custom-tool",
"server_url": "https://custom-tool.example.com"
}
]
Environment Variables
Pass configuration to y