Avoid azd Black Box for Reliable Deployments

Azure Developer CLI (azd) templates for Foundry hosted agents fail in preview due to opaque internals, making troubleshooting impossible without understanding the underlying cloud-native container model. Instead, deploy manually using basic Azure CLI tools and portal steps: create infrastructure first (ACR, image, Foundry Project, RBAC), then the agent second. This gives full control over orchestration and harness, unlike prompt agents.

Install azd extension only for init (azd ai agent init -m <agent-definition-url>), but skip azd up. Use az acr build for cloud-based Docker builds without local Docker.

Container Workflow: ACR Image to Running Agent

Build agent as Docker image in Azure Container Registry (ACR): name it debugagent, push my-hosted-agent:latest with az acr build --registry debugagent --image my-hosted-agent:latest --platform linux/amd64 --file ./src/debug-agent/Dockerfile ./src/debug-agent.

Agent code uses Microsoft Agent Framework: reads config from env vars like AZURE_AI_PROJECT_ENDPOINT and AZURE_OPENAI_CHAT_DEPLOYMENT_NAME.

import os
from azure.identity.aio import DefaultAzureCredential
from dotenv import load_dotenv
from agent_framework.azure import AzureAIClient
from azure.ai.agentserver.agentframework import from_agent_framework

load_dotenv(override=False)
async def main():
    credential = DefaultAzureCredential()
    async with AzureAIClient(
        project_endpoint=os.getenv("AZURE_AI_PROJECT_ENDPOINT"),
        model_deployment_name=os.getenv("AZURE_OPENAI_CHAT_DEPLOYMENT_NAME"),
        credential=credential,
    ).as_agent(
        name="Assistant",
        instructions="You are a helpful assistant. Answer questions concisely and accurately.",
    ) as agent:
        await from_agent_framework(agent).run_async()

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Dockerfile: FROM python:3.12-slim, copy code, pip install -r requirements.txt if present, expose 8088, CMD ["python", "main.py"].

Create Foundry Project, deploy gpt-4.1 model. Assign AcrPull or Container Registry Repository Reader RBAC from ACR to Foundry Project's managed identity for image pull.

SDK Agent Creation with RBAC Secures Access

Use azure.ai.projects SDK to create agent:

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import HostedAgentDefinition, ProtocolVersionRecord, AgentProtocol

project_client = AIProjectClient(endpoint=FOUNDRY_ENDPOINT, credential=credential, allow_preview=True)
agent = project_client.agents.create_version(
    agent_name="my-hosted-agent",
    definition=HostedAgentDefinition(
        kind="hosted",
        container_protocol_versions=[ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="1.0.0")],
        cpu="0.25",
        memory="0.5Gi",
        image="debugagent.azurecr.io/my-hosted-agent:latest",
        environment_variables={
            "AZURE_AI_PROJECT_ENDPOINT": FOUNDRY_ENDPOINT,
            "AZURE_OPENAI_CHAT_DEPLOYMENT_NAME": MODEL_DEPLOYMENT,
        }
    )
)

Agent gets Entra ID (Agent ID). Assign Azure AI User or Azure AI Project Manager RBAC at Foundry Project scope for model access. Result: production-grade hosted agent runs with full control.