Hosted agent infrastructure with the Azure Developer CLI

When you run azd ai agent init --infra or azd ai agent init --infra=bicep, the Azure Developer CLI (azd) ejects editable infrastructure from your Foundry service declarations. Without existing infrastructure, the default path is infra. To preserve existing application infrastructure, ejection adds a Foundry layer under infra/foundry. Running azd provision deploys the declared infrastructure.

What gets provisioned

By default, azd ai agent init doesn't create infrastructure-as-code files. Use --infra or --infra=bicep to eject Bicep. Use --infra=terraform to eject Terraform and record the layer's provider. If your project already declares Foundry services, invoke --infra alone; that path rejects unrelated initialization inputs.

Ejected templates come from the extension's infrastructure synthesizer, not a separate starter repository. For a new project, the generated infrastructure provisions the declared Foundry account, project, and model deployments. Additional resources depend on the service configuration:

When the project declares network isolation, the templates also configure subnets, an account private endpoint, and private DNS. The egress mode selects customer-network injection or a Microsoft-managed network.

The current templates don't automatically provision Application Insights, a Log Analytics workspace, Azure AI Search, a storage account, or a Bing grounding resource. Declare and manage additional application infrastructure separately rather than assuming a tool reference creates it.

Project structure

infra/
|-- main.bicep
|-- main.parameters.json
|-- abbreviations.json
\-- modules/

This example shows the default Bicep output without existing infrastructure. A project with existing application infrastructure receives a separate infra/foundry layer; existing layered configurations retain their declared paths. The exact modules depend on whether you create a project or connect to an existing one. Terraform ejection writes .tf files and main.tfvars.json instead.

How parameters flow

The generated main.parameters.json contains parameter bindings and values derived from azure.yaml. For example, a Bicep layer uses environment bindings such as:

{
  "parameters": {
    "location": { "value": "${AZURE_LOCATION}" },
    "foundryProjectName": { "value": "${AZURE_AI_PROJECT_NAME=${AZURE_ENV_NAME}}" },
    "resourceTokenSalt": { "value": "${AZD_RESOURCE_TOKEN_SALT}" }
  }
}

During azd provision, azd resolves these ${VAR} references from the environment (.azure/<env>/.env) and passes them to the Bicep deployment. Outputs from the deployment, such as the Foundry project endpoint and container registry endpoint, are written back to the environment for use by azd deploy, azd ai agent run, and the azd ai resource commands.

Terraform infrastructure

For a new project, azd ai agent init --infra=terraform generates files such as the following:

infra/
|-- main.tf
|-- provider.tf
|-- variables.tf
|-- outputs.tf
|-- main.tfvars.json
\-- .azd-foundry

Container-based services can also generate container-registry.tf. Existing projects can retain their infrastructure and receive a separate Foundry layer under infra/foundry/. Use the actual generated layout rather than moving files between layers.

The Terraform configuration provisions the Foundry account, project, model deployments, and related resources required by the selected services. Container registry creation depends on the deployment mode and image configuration.

main.tfvars.json binds infrastructure inputs to azd environment values. outputs.tf exposes values such as the Foundry project endpoint to azd after provisioning. These bindings are part of the azd workflow; don't assume a generated parameter file works unchanged with a standalone terraform apply.

To customize Terraform infrastructure, edit the generated .tf files, preserve the outputs needed by your agent services, and run azd provision. Review the Terraform plan before applying infrastructure changes.

Terraform state and CI/CD

The generated files don't bootstrap a remote-state backend. For team deployments, configure Azure Storage-backed state, separate state keys for each environment, and the required backend permissions before configuring CI/CD.

See Set up CI/CD with Terraform for the deployment flow and Use Terraform with azd for backend configuration.

Terraform ejection limitations

The Terraform ejection path doesn't support service network: configuration in the current Foundry agents extension. Review existing-resource constraints before ejecting a project that already has infrastructure. Ejection isn't a general Bicep-to-Terraform state migration, and deleting production resources isn't a prerequisite for adopting Terraform.

Existing resources

To reuse an existing Foundry account and project, initialize against the project's resource ID:

azd ai agent init --project-id "<foundry-project-resource-id>"

Ejection for an existing project references the account and project rather than creating replacements. It can add declared model deployments and create or reuse a container registry. For an existing connected registry, use --acr-connection during initialization. See Deploy with a private container registry.

Customize the infrastructure

The infra/ directory is standard azd infrastructure. To add or change Bicep resources:

1. Edit infra/main.bicep or add new modules under infra/modules/. For layered infrastructure, use the Foundry layer's declared path.
2. Add new parameters to main.parameters.json with ${VAR} bindings.
3. Set the corresponding azd environment variables with azd env set.
4. Run azd provision to apply the changes.

Changes to the Bicep files persist across deployments.

Region restrictions

The current generated main.bicep doesn't contain an allowed-region list. Choose a region that supports the required hosted-agent features and models. Editing a template doesn't enable a service in an unsupported region.

Related content

• azure.yaml reference for hosted agents
• Deploy a hosted agent
• Configure virtual networks