Agents V2 Py

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:

1. Container Image - Build and push to Azure Container Registry (ACR) 2. ACR Pull Permissions - Grant your project's managed identity AcrPull role on the ACR 3. Capability Host - Account-level capability host with enablePublicHostingEnvironment=true 4. 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

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:

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:

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 your container:

environment_variables={
    "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    "MODEL_NAME": "gpt-4o-mini",
    "LOG_LEVEL": "INFO",
    "CUSTOM_CONFIG": "value"
}

Best Practice: Never hardcode secrets. Use environment variables or Azure Key Vault.

Complete Example

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    ImageBasedHostedAgentDefinition,
    ProtocolVersionRecord,
    AgentProtocol,
)

def create_hosted_agent():
    """Create a hosted agent with custom container image."""
    
    client = AIProjectClient(
        endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
        credential=DefaultAzureCredential()
    )
    
    agent = client.agents.create_version(
        agent_name="data-processor-agent",
        definition=ImageBasedHostedAgentDefinition(
            container_protocol_versions=[
                ProtocolVersionRecord(
                    protocol=AgentProtocol.RESPONSES,
                    version="v1"
                )
            ],
            image="myregistry.azurecr.io/data-processor:v1.0",
            cpu="2",
            memory="4Gi",
            tools=[
                {"type": "code_interpreter"},
                {"type": "file_search"}
            ],
            environment_variables={
                "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
                "MODEL_NAME": "gpt-4o-mini",
                "MAX_RETRIES": "3"
            }
        )
    )
    
    print(f"Created hosted agent: {agent.name}")
    print(f"Version: {agent.version}")
    print(f"State: {agent.state}")
    
    return agent

if __name__ == "__main__":
    create_hosted_agent()

Async Pattern

import os
from azure.identity.aio import DefaultAzureCredential
from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import (
    ImageBasedHostedAgentDefinition,
    ProtocolVersionRecord,
    AgentProtocol,
)

async def create_hosted_agent_async():
    """Create a hosted agent asynchronously."""
    
    async with DefaultAzureCredential() as credential:
        async with AIProjectClient(
            endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
            credential=credential
        ) as client:
            agent = await client.agents.create_version(
                agent_name="async-agent",
                definition=ImageBasedHostedAgentDefinition(
                    container_protocol_versions=[
                        ProtocolVersionRecord(
                            protocol=AgentProtocol.RESPONSES,
                            version="v1"
                        )
                    ],
                    image="myregistry.azurecr.io/async-agent:latest",
                    cpu="1",
                    memory="2Gi"
                )
            )
            return agent

Common Errors

Best Practices

1. Version Your Images - Use specific tags, not latest in production 2. Minimal Resources - Start with minimum CPU/memory, scale up as needed 3. Environment Variables - Use for all configuration, never hardcode 4. Error Handling - Wrap agent creation in try/except blocks 5. Cleanup - Delete unused agent versions to free resources

Reference Links

• Azure AI Projects SDK
• Hosted Agents Documentation
• Azure Container Registry

Acceptance Criteria: hosted-agents-v2-py

SDK: azure-ai-projects Minimum Version: >=2.0.0b3 Repository: https://github.com/Azure/azure-sdk-for-python

---

1. Correct Import Patterns

1.1 Client and Model Imports

✅ CORRECT: All imports from azure.ai.projects

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    ImageBasedHostedAgentDefinition,
    ProtocolVersionRecord,
    AgentProtocol,
)

✅ CORRECT: Async imports

from azure.identity.aio import DefaultAzureCredential
from azure.ai.projects.aio import AIProjectClient
from azure.ai.projects.models import (
    ImageBasedHostedAgentDefinition,
    ProtocolVersionRecord,
    AgentProtocol,
)

1.2 Anti-Patterns (ERRORS)

❌ INCORRECT: Importing from azure.ai.agents

# WRONG - ImageBasedHostedAgentDefinition is NOT in azure.ai.agents
from azure.ai.agents.models import ImageBasedHostedAgentDefinition

❌ INCORRECT: Importing from azure.ai.agents directly

# WRONG - These models are in azure.ai.projects.models
from azure.ai.agents import (
    ImageBasedHostedAgentDefinition,
    ProtocolVersionRecord,
)

❌ INCORRECT: Wrong module path for AgentProtocol

# WRONG - AgentProtocol is in azure.ai.projects.models
from azure.ai.projects import AgentProtocol

❌ INCORRECT: Using AgentsClient instead of AIProjectClient

# WRONG - Hosted agents use AIProjectClient, not AgentsClient
from azure.ai.agents import AgentsClient

---

2. Client Creation Patterns

2.1 Correct Client Creation

✅ CORRECT: AIProjectClient with DefaultAzureCredential

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

client = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential()
)

✅ CORRECT: Async client with context manager

import os
from azure.identity.aio import DefaultAzureCredential
from azure.ai.projects.aio import AIProjectClient

async with DefaultAzureCredential() as credential:
    async with AIProjectClient(
        endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
        credential=credential
    ) as client:
        # Use client here
        pass

2.2 Anti-Patterns (ERRORS)

❌ INCORRECT: Using AgentsClient for hosted agents

# WRONG - Hosted agents require AIProjectClient
from azure.ai.agents import AgentsClient

client = AgentsClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential()
)

❌ INCORRECT: Hardcoded credentials

# WRONG - Never hardcode credentials
client = AIProjectClient(
    endpoint="https://myresource.services.ai.azure.com/api/projects/myproject",
    credential=DefaultAzureCredential()
)

❌ INCORRECT: Missing credential

# WRONG - credential is required
client = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"]
)

---

3. Hosted Agent Creation Patterns

3.1 Correct Agent Creation

✅ CORRECT: Basic hosted agent with ImageBasedHostedAgentDefinition

from azure.ai.projects.models import (
    ImageBasedHostedAgentDefinition,
    ProtocolVersionRecord,
    AgentProtocol,
)

agent = client.agents.create_version(
    agent_name="my-hosted-agent",
    definition=ImageBasedHostedAgentDefinition(
        container_protocol_versions=[
            ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
        ],
        image="myregistry.azurecr.io/my-agent:latest"
    )
)

✅ CORRECT: Agent with resource allocation

agent = client.agents.create_version(
    agent_name="my-hosted-agent",
    definition=ImageBasedHostedAgentDefinition(
        container_protocol_versions=[
            ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
        ],
        image="myregistry.azurecr.io/my-agent:latest",
        cpu="2",
        memory="4Gi"
    )
)

✅ CORRECT: Agent with tools and environment variables

agent = client.agents.create_version(
    agent_name="my-hosted-agent",
    definition=ImageBasedHostedAgentDefinition(
        container_protocol_versions=[
            ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
        ],
        image="myregistry.azurecr.io/my-agent:latest",
        cpu="1",
        memory="2Gi",
        tools=[{"type": "code_interpreter"}],
        environment_variables={
            "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
            "MODEL_NAME": "gpt-4o-mini"
        }
    )
)

3.2 Anti-Patterns (ERRORS)

❌ INCORRECT: Using create_agent instead of create_version

# WRONG - Hosted agents use create_version, not create_agent
agent = client.agents.create_agent(
    name="wrong-agent-example",
    definition=ImageBasedHostedAgentDefinition(...)
)

❌ INCORRECT: Missing container_protocol_versions

# WRONG - container_protocol_versions is required
agent = client.agents.create_version(
    agent_name="missing-protocol-agent",
    definition=ImageBasedHostedAgentDefinition(
        image="wrong.azurecr.io/incomplete-agent:latest"
    )
)

❌ INCORRECT: Missing image parameter

# WRONG - image is required for ImageBasedHostedAgentDefinition
agent = client.agents.create_version(
    agent_name="missing-image-agent",
    definition=ImageBasedHostedAgentDefinition(
        container_protocol_versions=[
            ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
        ]
    )
)

❌ INCORRECT: Using wrong protocol enum

# WRONG - Must use AgentProtocol enum, not string
agent = client.agents.create_version(
    agent_name="wrong-protocol-agent",
    definition=ImageBasedHostedAgentDefinition(
        container_protocol_versions=[
            ProtocolVersionRecord(protocol="responses", version="v1")
        ],
        image="wrong.azurecr.io/string-protocol-agent:latest"
    )
)

❌ INCORRECT: Passing model parameter (not applicable to hosted agents)

# WRONG - Hosted agents don't take model parameter in definition
agent = client.agents.create_version(
    agent_name="wrong-model-agent",
    definition=ImageBasedHostedAgentDefinition(
        container_protocol_versions=[...],
        image="wrong.azurecr.io/model-param-agent:latest",
        model="gpt-4o-mini"  # WRONG - use environment_variables instead
    )
)

---

4. Protocol Version Patterns

4.1 Correct Protocol Configuration

✅ CORRECT: RESPONSES protocol with v1

container_protocol_versions=[
    ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")
]

4.2 Anti-Patterns (ERRORS)

❌ INCORRECT: Using string instead of enum

# WRONG - protocol must be AgentProtocol enum
container_protocol_versions=[
    ProtocolVersionRecord(protocol="RESPONSES", version="v1")
]

❌ INCORRECT: Empty protocol versions list

# WRONG - At least one protocol version required
container_protocol_versions=[]

❌ INCORRECT: Missing version parameter

# WRONG - version is required
container_protocol_versions=[
    ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES)
]

---

5. Resource Allocation Patterns

5.1 Correct Resource Specification

✅ CORRECT: String format for CPU and memory

ImageBasedHostedAgentDefinition(
    container_protocol_versions=[...],
    image="...",
    cpu="1",      # String format
    memory="2Gi"  # String format with unit
)

✅ CORRECT: Higher resource allocation

ImageBasedHostedAgentDefinition(
    container_protocol_versions=[...],
    image="...",
    cpu="4",
    memory="8Gi"
)

5.2 Anti-Patterns (ERRORS)

❌ INCORRECT: Numeric values instead of strings

# WRONG - cpu and memory must be strings
ImageBasedHostedAgentDefinition(
    container_protocol_versions=[...],
    image="...",
    cpu=1,        # WRONG - must be string "1"
    memory=2048   # WRONG - must be string "2Gi"
)

❌ INCORRECT: Missing unit for memory

# WRONG - memory needs unit suffix (Gi, Mi)
ImageBasedHostedAgentDefinition(
    container_protocol_versions=[...],
    image="...",
    memory="2"  # WRONG - should be "2Gi"
)

---

6. Tools Configuration Patterns

6.1 Correct Tools Specification

✅ CORRECT: Code interpreter tool

tools=[{"type": "code_interpreter"}]

✅ CORRECT: Multiple tools

tools=[
    {"type": "code_interpreter"},
    {"type": "file_search"}
]

✅ CORRECT: MCP tool with server configuration

tools=[
    {
        "type": "mcp",
        "server_label": "my-mcp-server",
        "server_url": "https://my-mcp-server.example.com"
    }
]

6.2 Anti-Patterns (ERRORS)

❌ INCORRECT: Using CodeInterpreterTool class

# WRONG - tools should be dict format for hosted agents
from azure.ai.agents.models import CodeInterpreterTool

tools=[CodeInterpreterTool()]  # WRONG for hosted agents

❌ INCORRECT: String instead of dict

# WRONG - tools must be list of dicts
tools=["code_interpreter"]  # WRONG

---

7. Environment Variables Patterns

7.1 Correct Environment Variables

✅ CORRECT: Using os.environ

environment_variables={
    "AZURE_AI_PROJECT_ENDPOINT": os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    "MODEL_NAME": "gpt-4o-mini"
}

7.2 Anti-Patterns (ERRORS)

❌ INCORRECT: Hardcoded secrets

# WRONG - Never hardcode secrets
environment_variables={
    "API_KEY": "sk-1234567890abcdef"  # NEVER DO THIS
}

---

8. Agent Lifecycle Patterns

8.1 Correct Lifecycle Management

✅ CORRECT: 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}")

✅ CORRECT: Delete agent version

client.agents.delete_version(
    agent_name="my-hosted-agent",
    version=agent.version
)

8.2 Anti-Patterns (ERRORS)

❌ INCORRECT: Using delete_agent instead of delete_version

# WRONG - Use delete_version for hosted agent versions
client.agents.delete_agent(agent_id="wrong-delete-agent")

---

Summary Checklist

Before submitting code using hosted agents, verify:

• [ ] Imports use azure.ai.projects (NOT azure.ai.agents) for hosted agent models
• [ ] Client is AIProjectClient (NOT AgentsClient)
• [ ] Uses create_version method (NOT create_agent)
• [ ] ImageBasedHostedAgentDefinition has required container_protocol_versions
• [ ] ImageBasedHostedAgentDefinition has required image parameter
• [ ] ProtocolVersionRecord uses AgentProtocol enum (NOT string)
• [ ] cpu and memory are strings with proper units
• [ ] tools is a list of dicts (NOT model classes)
• [ ] No hardcoded credentials or secrets
• [ ] Uses DefaultAzureCredential for authentication