Introduction
At Microsoft Build `26 it was announced that Microsoft Foundry Hosted will soon be generally available. This blog post will outline the deployment process and requirements for creating hosted agents in Foundry. The audience for this blog is designed to range from beginner to more advanced users. We will focus on deploying a Hosted Agent from a local machine using the REST API backed by the Responses protocol.
The key thing to understand upfront: deploying a Hosted Agent is ultimately a data plane operation against the Foundry Service API, not an infrastructure deployment. However, it depends on carefully orchestrated infrastructure, identity, and access configuration being in place first. This post walks through each layer.
The companion repository for this post is available at github.com/JFolberth/simple-hosted-agent-responses and contains the full Infrastructure as Code (IaC) templates, deployment scripts, and agent source code referenced throughout.
Background
There's a school of thought that to fully understand and control something you must properly name it. Given this context let's level set on terminology on both what an Agent is and specifically when and how an Agent is defined inside Microsoft Foundry.
For our Definition of an Agent we will leverage the definitions provided and backed by Microsoft Agent Framework. At a process level an Agent can be defined as:
For those that want to go another level this can translate into:
Notice anything missing from these documents? There is no mention of where the Agent is hosted in terms of compute. This is open ended by design as Microsoft believes in providing the flexibility to leverage any part of the agentic technology stack for agent hosting.
We can bring our own compute such as Azure Function, Azure Container App (ACA), App Service, Hosted Virtual Machine, AWS Lambda, etc., to make a call to the Foundry. This is an agentic architecture but is not the same as a Foundry Hosted Agent. This is the key architectural element that is important to understand what makes Foundry Hosted Agents different.
As of this writing there are only three types of Foundry Agents: Prompt, Workflow (preview), and Hosted:
We are going to focus on this last type, Hosted Agents. The compute for Hosted Agents is managed entirely by Foundry through per-session Micro VMs, lightweight, isolated compute units that scale to zero when idle and resume automatically on the next request.
When building agentic applications with open-source frameworks you typically manage many cross-cutting concerns: containerization, web server setup, security, memory persistence, scaling, instrumentation, and version rollbacks. Hosted Agents solve these by letting you bring your own code and framework while the platform handles everything else.
Choose a Hosted Agent over a prompt-based agent when you need to use any framework (Agent Framework, LangGraph, Semantic Kernel), control compute resources like CPU and memory, run stateful workloads that persist files across turns, or use custom protocols for webhook receivers and non-conversational processing.
Each deployed agent automatically receives its own dedicated Microsoft Entra ID and endpoint with no manual identity configuration required. For the full comparison see What are hosted agents?
For us to fully understand the deployment process we first need to understand the required infrastructure, access, and tooling to deploy a Hosted Agent.
Requirements
A Hosted Agent can be deployed via either REST API calls or through the azd CLI. We are going to focus on the REST API process.
To deploy a Hosted Agent via REST API calls the following software needs to be available:
- python (not needed but preferred in our walkthrough)
The following infrastructure and sub resources are required to deploy Hosted Agents:
- Microsoft Foundry (Microsoft.CognitiveServices/accounts)
- Microsoft Foundry Project (Microsoft.CognitiveServices/accounts/projects)
- Azure Container Registry (ACR) (Microsoft.ContainerRegistry/registries)
- Microsoft Foundry Model Deployment (Microsoft.CognitiveServices/accounts/deployments)
- Application Insights (optional) (Microsoft.Insights/components)
- Log Analytics (optional) (Microsoft.OperationalInsights/workspaces)
From an access perspective the following roles will need to be assigned/assignable:
- Contributor (provision the infrastructure)
- Foundry Project Manager (Optional-Ability to view agent in Foundry Portal)
- Foundry User (Data plane access is needed to create a new agent)
- AcrPull (Foundry Project needs to pull the container from ACR)
- AcrPush (To deploy the image to ACR)
- Log Analytics Reader (Foundry Project access to read Log Analytics, optional if using)
To elaborate further the Managed Identity of the Foundry Project will need to have: AcrPull, Log Analytics Reader, Foundry User. Ideally this access provisioning would be contained within your Infrastructure as Code (IaC) processes.
The other access would be required for the user or service principal handling the deployment. These roles would be: Contributor, Foundry Project Manager, Foundry User, AcrPush. In production environments, outside the Contributor role, these roles should be provisioned after the infrastructure has been deployed. Justification being they are one time assignments and it is not a best practice to define the service principal access as part of your template. Luckily, we have a script that will handle all of this for you.
High Level Steps
First, the infrastructure will need to be deployed, either directly in the portal or ideally through an IaC template. After successful completion we will need to grab the Managed Identity of the Foundry Project, Azure Container Registry endpoint, Model(s) deployed, and Foundry Project endpoint. We will need this information for deploying our agent and granting the executing user the ability to view the Agent in Foundry.
After the IaC deployment we will grant the user Foundry Project Manager. We chose the Foundry Project Manager role here as not only will it give permission to deploy an agent it will also give the deploying user access to the Foundry Portal to view the agent. If viewing the agent is not a requirement then Foundry User should suffice.
Since the IaC deploys our ACR we will need to build and push our container image. At the time of this writing the image must be built with --platform linux/amd64 as the Foundry Micro VM runtime only supports amd64 architecture. See the hosted agent container requirements for details.
docker build --platform linux/amd64 -t <acr-login-server>/<image-name>:<tag> .
az acr login --name <acr-name>
docker push <acr-login-server>/<image-name>:<tag>
For the Foundry Micro VM runtime to pull your container image at agent startup, a connection must exist between your Foundry Project and the Azure Container Registry. This is configured as a project-scoped connection of category ContainerRegistry that references the ACR login server and uses the project's Managed Identity for authentication (no stored credentials).
The IaC templates in the companion repo handle this automatically, but if provisioning manually you will need to create this connection via the Foundry project connections API or through the Foundry Portal. For more details see Connections in Microsoft Foundry and Configure container registry connections.
The last step is the most important, deploying the agent. At the end of the day a Hosted Agent is actually not an infrastructure change, rather a data plane operation against the Foundry Service API. We pass in the kind as hosted, specify the container image, and provide the CPU and memory allocation for our Micro VMs.
curl -X POST \
"<project-endpoint>/agents/<agent-name>/versions?api-version=2025-11-15-preview" \
-H "Authorization: Bearer $(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)" \
-H "Content-Type: application/json" \
-d '{
"kind": "hosted",
"configuration": {
"container": {
"image": "<acr-login-server>/<image-name>:<tag>"
},
"resources": {
"cpu": "0.25",
"memory": "0.5Gi"
},
"protocolVersion": "1.0.0",
"environmentVariables": {
"AZURE_AI_MODEL_DEPLOYMENT_NAME": "<model-deployment-name>"
}
},
"metadata": {
"enableVnextExperience": "true"
}
}'
Conclusion
As we covered, deploying a Hosted Agent comes down to a single REST API call, but getting to that point requires the right infrastructure, roles, and container image in place.
Infrastructure first: Your Foundry project, ACR, and model deployments must exist before agent creation. Role assignments, particularly Foundry User for the project managed identity and AcrPull for image access, must be in place before proceeding.
The REST call is the agent: Unlike traditional container deployments where you manage compute directly, the POST to the Foundry data plane is what brings your agent to life. You specify the container image, CPU/memory allocation, and protocol version. Foundry handles the rest, provisioning per-session Micro VMs that scale to zero when idle.
You own only the agent logic: The platform manages the runtime, session isolation, identity, and scaling. This is the fundamental shift from self-hosted patterns. Less operational overhead in exchange for letting Foundry control the compute layer.
To see a complete, working implementation including Bicep and Terraform IaC templates, deployment scripts with proper RBAC handling, and a Python agent using the Responses protocol, visit the companion repository at github.com/JFolberth/simple-hosted-agent-responses. The repo includes a dev container with all prerequisites pre-installed, making it possible to go from clone to deployed agent in a single azd up command.