Deploy a hosted agent

Deploy your containerized agent code to Foundry Agent Service using the Azure Developer CLI or Python SDK.

Deploy a hosted agent

This article shows you how to deploy a containerized agent to Foundry Agent Service. Use hosted agents when you need to run custom agent code built with frameworks like LangGraph, Microsoft Agent Framework, or your own implementation.

Prerequisites

• A Microsoft Foundry project
• Python 3.10 or later for SDK-based development
• Azure CLI version 2.80 or later
• Docker Desktop installed for local container development
• Familiarity with Azure Container Registry
• Agent code using a supported framework

Required permissions

You need one of the following role combinations depending on your deployment scenario:

Scenario	Required roles
Create new Foundry project	Azure AI Owner on Foundry resource
Deploy to existing project with new resources	Azure AI Owner on Foundry + Contributor on subscription
Deploy to fully configured project	Reader on account + Azure AI User on project

For more information, see Authentication and authorization.

Package and test your agent locally

Before deploying to Foundry, validate your agent works locally using the hosting adapter.

Run your agent locally

The hosting adapter starts a local web server that exposes your agent as a REST API:

@baseUrl = http://localhost:8088

POST {{baseUrl}}/responses
Content-Type: application/json.
{
    "input": {
        "messages": [
            {
                "role": "user",
                "content": "Where is Seattle?"
            }
        ]
    }
}

A successful response:

{
    "id": "resp_abc123",
    "object": "response",
    "output": [
        {
            "type": "message",
            "role": "assistant",
            "content": "Seattle is a major city in the Pacific Northwest region of the United States..."
        }
    ],
    "status": "completed"
}

Local testing helps you:

• Validate agent behavior before containerization
• Debug issues in your development environment
• Verify API compatibility with the Foundry Responses API

Deploy using the Azure Developer CLI

The Azure Developer CLI ai agent extension provides the fastest path to deploy hosted agents.

This extension is currently in preview. Don’t use it for production workloads.

Install and configure the Azure Developer CLI

1. Verify you have Azure Developer CLI version 1.23.0 or later:

   azd version
   

   To upgrade, see Install or update the Azure Developer CLI.

2. Initialize a new project with the Foundry starter template:

   azd init -t https://github.com/Azure-Samples/azd-ai-starter-basic
   

   Or, if you have an existing Foundry project:

   azd ai agent init --project-id /subscriptions/[SUBSCRIPTIONID]/resourceGroups/[RESOURCEGROUPNAME]/providers/Microsoft.CognitiveServices/accounts/[ACCOUNTNAME]/projects/[PROJECTNAME]
   

Configure your agent

Initialize the template with your agent definition:

azd ai agent init -m <repo-path-to-agent.yaml>

The agent repository should contain:

• Application code
• Dockerfile for containerization
• agent.yaml file with your agent’s definition

Get started with samples on GitHub.

Deploy your agent

Package, provision, and deploy in one command:

azd up

This command:

• Generates infrastructure configuration
• Provisions required Azure resources
• Builds and pushes your container image
• Creates a hosted agent version and deployment

Verify deployment

az cognitiveservices agent show \
    --account-name <your-account-name> \
    --project-name <your-project-name> \
    --name <your-agent-name>

A successful deployment shows status: Started. If the status shows Failed, check the deployment logs.

Deploy using the Python SDK

Use the SDK for programmatic deployments or CI/CD integration.

Additional prerequisites

• A container image in Azure Container Registry

• User Access Administrator or Owner permissions on the container registry

• Azure AI Projects SDK version 2.0.0b3 or later

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

Build and push your container image

1. Build your Docker image:

   docker build -t myagent:v1 .
   

   See sample Dockerfiles for Python and C#.

2. Push to Azure Container Registry:

   az acr login --name myregistry
   docker tag myagent:v1 myregistry.azurecr.io/myagent:v1
   docker push myregistry.azurecr.io/myagent:v1
   

Configure container registry permissions

Grant your project’s managed identity access to pull images:

1. In the Azure portal, go to your Foundry project resource.

2. Select Identity and copy the Object (principal) ID under System assigned.

3. Assign the Container Registry Repository Reader role to this identity on your container registry. See Azure Container Registry roles and permissions.

Create an account-level capability host

Hosted agents require a capability host with public hosting enabled:

Bash

    az rest --method put \
        --url "https://management.azure.com/subscriptions/[SUBSCRIPTIONID]/resourceGroups/[RESOURCEGROUPNAME]/providers/Microsoft.CognitiveServices/accounts/[ACCOUNTNAME]/capabilityHosts/accountcaphost?api-version=2025-10-01-preview" \
        --headers "content-type=application/json" \
        --body '{
            "properties": {
                "capabilityHostKind": "Agents",
                "enablePublicHostingEnvironment": true
            }
        }'

Updating capability hosts isn’t supported. If you have an existing capability host, delete and recreate it with enablePublicHostingEnvironment set to true.

Create the hosted agent

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

endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]

client = AIProjectClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential()
)

agent = client.agents.create_version(
    agent_name="my-agent",
    definition=ImageBasedHostedAgentDefinition(
        container_protocol_versions=[ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")],
        cpu="1",
        memory="2Gi",
        image="your-registry.azurecr.io/your-image:tag",
        environment_variables={
            "AZURE_AI_PROJECT_ENDPOINT": endpoint,
            "MODEL_NAME": "gpt-4.1"
        }
    )
)

print(f"Agent created: {agent.name}, version: {agent.version}")

Key parameters:

Parameter	Description
agent_name	Unique name (alphanumeric with hyphens, max 63 characters)
image	Full Azure Container Registry image URL with tag
cpu	CPU allocation (for example, "1")
memory	Memory allocation (for example, "2Gi")

Add tools to your agent

Include tools when creating the agent:

agent = client.agents.create_version(
    agent_name="my-agent",
    definition=ImageBasedHostedAgentDefinition(
        container_protocol_versions=[ProtocolVersionRecord(protocol=AgentProtocol.RESPONSES, version="v1")],
        cpu="1",
        memory="2Gi",
        image="your-registry.azurecr.io/your-image:tag",
        tools=[
            {"type": "code_interpreter"},
            {"type": "mcp", "project_connection_id": os.environ["GITHUB_CONNECTION_ID"]}
        ],
        environment_variables={
            "AZURE_AI_PROJECT_ENDPOINT": endpoint,
            "MODEL_NAME": "gpt-4.1"
        }
    )
)

Supported tools:

• Code Interpreter
• Image Generation
• Web Search
• MCP connections (see Connect to Model Context Protocol servers)

Clean up resources

To prevent charges, clean up resources when finished.

Azure Developer CLI cleanup

azd down

SDK cleanup

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

Troubleshooting

Error	HTTP code	Solution
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.

Next steps

Manage hosted agent lifecycle

Related content

• What are hosted agents?
• Agent identity concepts
• Publish and share agents
• Azure Container Registry documentation