Background

Your Terraform workflow already manages your Azure infrastructure but deploying hosted agents still requires manual SDK calls or REST API scripts. This post shows you how to bring agent deployments into your existing IaC pipeline using the AzAPI provider, so your entire Foundry stack can be versioned, reviewed, and deployed together. For this post we will focus on leveraging Foundry Hosted Agents.

At a high level hosted agents will abstract the overhead of managing your agents compute. Conceptually, think of taking the compute today, that might be in Azure Container Apps (ACA) or Azure Functions and moving it into Foundry. For more information can check out my previous blog on this topic. In this example Foundry runs the agent code on managed compute from a container image. For this specific example we need to use Azure Container Registry to house our code artifact. If wanting to deploy directly from source refer to my previous blog Deploying Foundry Hosted Agents from Source 

Why an Infrastructure as Code Approach?

Hosted agents today in Foundry support SDK and REST API deployments, why should we look at leveraging an IaC provider to handle our agents today?

Many organizations subscribe to an IaC strategy for managing their Azure Resources. A hosted agent, at its core, is configuring and allocating infrastructure resources behind Foundry. This would be similar to how we configure plan sizes for products like App Services. Additionally, anything defined by IaC makes it easier to version the configuration in source control and incorporate it into repeatable CI/CD pipelines. Production workflows should also account for remote state, approval controls, and image-version promotion. Another added benefit for anything under IaC is the ability to apply custom policies, Azure or otherwise, over the codebase.

Prerequisites

• An Azure subscription with permission to create resources and role assignments.
• Access to a region and model deployment with sufficient quota for Foundry Hosted Agents.
• Azure CLI, Terraform, Git, and Docker installed. Docker must support building linux/amd64 images.
• Permission to push images to Azure Container Registry and create agents in the Foundry project.

The provided sample creates or configures the supporting Azure Container Registry, Foundry account and project, model deployment, managed identity, project connection, and hosted-agent deployment.

Hosted agents require a Linux AMD64 (linux/amd64) container image. When building from an ARM-based workstation, including Apple Silicon, explicitly target linux/amd64 and ensure Docker cross-platform emulation is available. See Microsoft’s hosted-agent container requirements.

docker build --platform linux/amd64 -t <registry-name>.azurecr.io/<image-name>:<tag>

To get started quickly I have a repository w/ all the prerequisites and reviewed code at simple-hosted-agent-deploy-azapi

Deploy the Sample

To deploy the sample:

1. Clone the repository and reopen it in the included development container.
2. Authenticate to Azure and select the target subscription.
3. Copy and update the example Terraform variable files with your environment-specific values.
4. Run the included deployment script to provision the base resources, build and push the container image, and create the hosted agent.
5. Confirm that the generated agent version reaches an active state before invoking it.

Refer to the repository README for the current commands, configuration values, and cleanup steps.

Process Overview

Let’s level set on what our end-to-end process may look like. In many large organizations, the agent deployment process could be decoupled from the Foundry base architecture. Components such as the Foundry account, project, connections, and model may be controlled by a centralized team. These shared components often follow a different deployment lifecycle from an individual agent. A development team may own the code. We need the code to deploy the hosted agent. Quite the chicken-and-egg problem. So let’s break it down from a day 1 perspective:

1. Deploy Foundry Base Architecture
   • Foundry Account
   • Foundry Project
   • Model
   • Project Connection
   • Application Insights
2. Build and Push code to Azure Container Registry
3. Deploy the hosted agent pointed to the image defined in Azure Container Registry

For this example, I assume that Azure Container Registry is managed outside the Foundry lifecycle because many organizations prefer to consolidate container images into a smaller number of shared registries. For illustration purposes, the provided example includes the registry deployment.

Day n perspective would potentially look like:

1. Build and Push code to Azure Container Registry
2. Deploy the hosted agent pointed to the image defined in Azure Container Registry

Updating the hosted-agent configuration creates a new agent version under the existing logical agent. Foundry manages the version history, while Terraform manages the logical agent configuration represented by the azapi_data_plane_resource. After each deployment, confirm that the new version reaches an active state before directing workloads to it.

Technical Details

At this time, let’s take a minute and discuss some of the technical details around how the hosted agent is created in Foundry. The Foundry project and its connections are Azure Resource Manager control-plane resources. The logical agent is created through the Foundry project’s data-plane API, while Foundry manages the supporting deployment resources required to host it. This is in contrast to services represented directly as Azure Resource Manager resources, such as App Service (Microsoft.Web/sites) and Azure Container Apps (Microsoft.App/containerApps).

Here is a visual that depicts the data plane vs control plane objects:

The Foundry project is the agent’s logical parent and provides the data-plane endpoint through which the agent is created. The project itself is deployed as the Azure Resource Manager resource Microsoft.CognitiveServices/accounts/projects Foundry connections can be deployed as Microsoft.CognitiveServices/accounts/projects/connections. In this case, the connection is used for connecting and authenticating to Azure Container Registry.

At this point, the project and connection resources can be deployed through AzAPI or Bicep. The next step requires a data-plane call. For Terraform deployments, this operation can be managed declaratively with the AzAPI provider’s azapi_data_plane_resource. Foundry also supports agent deployment through its SDKs and REST API.

azapi_data_plane_resource

The AzAPI provider’s azapi_data_plane_resource resource is the key component for deploying a hosted agent in Foundry Agent Service through Terraform.

Per official MS Learn documentation:

Some Azure services expose a separate data plane API—a service-specific HTTPS endpoint where you interact directly with the service rather than through ARM. Examples include the Key Vault secrets API at {vaultName}.vault.azure.net, the Azure AI Search index API at {searchServiceName}.search.windows.net, and the Synapse workspace pipeline API at {workspaceName}.dev.azuresynapse.net.

azapi_data_plane_resource bridges this gap by enabling Terraform to manage resources on these data plane endpoints using the same AzAPI provider authentication and lifecycle model.

https://learn.microsoft.com/en-us/azure/developer/terraform/concept-azapi-data-plane-framework

So how would a terraform implementation for this work? First let’s create the appropriate resource type, name and parent reference, in this case the Foundry Project:

resource "azapi_data_plane_resource" "hosted_agent" {

  type = "Microsoft.Foundry/agents@v1"

  name = var.agent_name

  # AzAPI data-plane parents use the endpoint host/path without a URI scheme.

  parent_id = trimprefix(var.project_endpoint, "https://")

…}

Now we need to pass in the dedicated parameters as part of the body. To find these parameters refer to the Foundry REST API documentation.

body = {

    name = var.agent_name

    definition = {

      kind = "hosted"

      container_configuration = {

        image = var.image_uri

      }

      cpu    = var.cpu

      memory = var.memory

      protocol_versions = [

        {

          # The hosted container must implement this Foundry Responses contract.

          protocol = "responses"

          version  = "2.0.0"

        }

      ]

      environment_variables = merge(var.environment_variables, {

        AZURE_AI_MODEL_DEPLOYMENT_NAME = var.model_deployment_name

      })

      rai_config = {

        # Hosted agents require the full policy ARM ID; model deployments use its name.

        rai_policy_name = var.rai_policy_id

      }

    }

  }

For the entire reusable module check out https://github.com/JFolberth/simple-hosted-agent-deploy-azapi/tree/main/simple_agent/azure/infra/modules/hosted_agent

Conclusion

Hosted Agents in Foundry Agent Service provides a way to run custom agent code on Foundry-managed compute while reducing the operational overhead of managing the underlying hosting infrastructure. By using the AzAPI provider’s azapi_data_plane_resource, teams can incorporate the logical agent deployment into an existing Terraform workflow alongside the Foundry project, model, connections, identity, and container registry resources it depends on.

This approach is especially useful when platform and application responsibilities are separated. A platform team can manage the shared Foundry and Azure infrastructure, while application teams independently build, publish, and deploy new versions of their agent container. With the appropriate remote state, access controls, image-versioning strategy, and deployment validation in place, the same pattern can be extended into a repeatable CI/CD workflow for both initial deployment and ongoing agent updates.

The linked sample demonstrates this end-to-end pattern, from provisioning the supporting Azure resources and publishing the container image through creating the hosted agent with Terraform. Use it as a starting point, then adapt its state management, access controls, artifact promotion, and validation steps to meet your organization’s production requirements.