Initialize a hosted agent project with the Azure Developer CLI

Important

Items marked preview in this article are currently in preview. This preview is provided without a service-level agreement, and Microsoft doesn't recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

Use azd ai agent init to scaffold a hosted agent project with the files you need to build, test, and deploy an AI agent to Microsoft Foundry. In this article, you choose a starting point and initialize the project from a template, from your own code, or against an existing Foundry project.

If you use a coding agent like GitHub Copilot, the Microsoft Foundry Skill can help you choose a starting template, scaffold the project, and interpret the generated azd configuration.

Prerequisites

Choose a starting point

There are three ways to begin a project. Pick the path that matches your situation.

Consideration Start from a template Bring your own code Connect an existing project
Best for New agents, learning the tooling. Existing agent code you want to host on Foundry. Agents already running in a Foundry project.
Command azd ai agent init in an empty directory. azd ai agent init in a directory with existing code. azd ai agent init, then select an existing project.
What you get A fully scaffolded project: a single azure.yaml, agent source under src/<agent-name>/, and a Dockerfile for container deployment. Infrastructure is Bicep-less by default and can be ejected later. A generated azure.yaml service entry and, for container deployment, a Dockerfile wrapping your code. Infrastructure is Bicep-less by default and can be ejected later. An azure.yaml wired to your existing Foundry project. Infrastructure is Bicep-less by default and can be ejected later.
Code changes None. Ready to run. Might need a protocol adapter. None.

Initialize from a template

Run the interactive wizard in an empty directory and select Start new from a template:

azd ai agent init

The wizard walks you through the following choices.

Prompt Description
Agent template Choose from templates organized by framework and language (Python or .NET).
Azure subscription The subscription used to find or create a Foundry project.
Foundry project Select an existing project or create a new one. If you create one, you also choose a region.
Model deployment Review the template's model settings. When adopting a template into an existing project, use --model-deployment <name> to explicitly reuse a deployment.

The agent name comes from the template. The CLI creates an azd environment named <directory>-dev and configures it with details from your selected Foundry project. Templates declare agent source and deployment settings in azure.yaml; container templates also include a Dockerfile.

Initialize from an azure.yaml URL

If you have a specific agent sample, point --template to the sample's azure.yaml. The CLI adopts that file as the project manifest and downloads the referenced agent source.

azd ai agent init --template https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml --src .

For template adoption, --src selects the destination of the entire project, not just the agent source. The preceding command writes azure.yaml in the current directory and preserves the template's relative source paths. Without --src, initialization can create a directory named after the template. Run subsequent azd env, provisioning, and deployment commands from the directory that contains the generated azure.yaml.

Templates can reference external inputs, such as a GitHub token or a service endpoint. Prepare those values before initialization; the CLI prompts for unresolved environment variables and stores them in the selected azd environment. Don't commit credentials or the .azure directory.

Note

Template adoption requires a full azure.yaml. To attach a direct agent definition to an existing project, use agent add --file. Parameterized AgentManifest wrappers aren't supported by either path.

Use --template (-t) for an azure.yaml project document. --manifest (-m) is a deprecated alias, not support for the earlier manifest format. Standalone agent definitions, AgentManifest wrappers, and azureml:// manifest pointers aren't accepted by this workflow.

Specify a model

Choose a model at init time:

azd ai agent init --model gpt-4.1

Or use an existing model deployment in your Foundry project:

azd ai agent init --model-deployment my-deployment

When adopting an azure.yaml template, add --model-deployment <name> to the same initialization command and select the existing project. This path doesn't currently offer an interactive existing-deployment picker. Without the override, the adopted configuration can retain the template's requested model. Review both the project deployment declaration and the agent's model setting before running azd provision.

Choose a deploy mode

By default, azd ai agent init uses code deployment for Python and .NET projects. Code deployment uploads your source as a ZIP package. To scaffold a container-based project instead, pass --deploy-mode container:

azd ai agent init --deploy-mode container

To deploy a prebuilt container image, pass --image and --agent-name. This option skips template and language selection, code scaffolding, Dockerfile generation, and Azure Container Registry setup.

azd ai agent init --agent-name my-agent --image myregistry.azurecr.io/my-agent:v1

For unattended source-code initialization, supply --runtime and --entry-point with --deploy-mode code. The generated .agentignore uses .gitignore syntax to exclude files from the deployment ZIP; review it before uploading source.

Browse templates noninteractively

To inspect the catalog before you scaffold, or to drive azd ai agent init from a script, list the catalog:

# Everything in the catalog
azd ai agent sample list

# Just the featured Python agent samples
azd ai agent sample list --featured-only --language python --type agent

# Full azd templates only, as JSON for scripting
azd ai agent sample list --type azd --output json

Each entry includes a ready-to-run initCommand that you copy and run in the directory you want to scaffold into.

Tip

When you reuse a sample under a different Foundry agent identity, pass --agent-name <new-name> on azd ai agent init so the name written to azure.yaml doesn't collide with the sample default name.

Initialize from existing code

If you have existing Python or .NET agent code, run azd ai agent init inside the directory that already contains your code:

cd my-agent/
azd ai agent init

The CLI detects the existing files and generates an azure.yaml service entry around them without overwriting your code. For container deployment, it also adds a Dockerfile. Infrastructure remains Bicep-less by default unless you eject infrastructure as code later.

Your agent code must meet the hosted agent runtime contract:

  • Listen on port 8088.
  • Serve a health probe at GET /readiness.
  • Handle one of the supported protocols (responses or invocations).

If your code doesn't already speak one of these protocols, add a protocol adapter, a lightweight SDK wrapper that translates between the Foundry protocol and your agent's logic.

Use --src to specify the source or target directory for initialization:

azd ai agent init --src src/my-agent

Add a file-backed agent to an existing project

Use agent add, rather than template adoption, when you have a direct agent definition in YAML or JSON:

azd ai agent add support-agent --file ./agents/support.yaml
azd deploy support-agent

support-agent is the service key in azure.yaml, not necessarily the Foundry agent name. The command adds or updates the service using a root $ref relative to azure.yaml. It validates locally; it doesn't authenticate, copy source, create remote resources, or deploy.

The project must declare exactly one azure.ai.project service. Use --project <service-key> to confirm that service and --source <directory> to override the agent's source directory. The directory must already exist inside the project.

Initialize prompt and voice agents

The same extension supports agents without hosted source code. For a prompt agent, choose --kind prompt and provide its name, model, and instructions:

azd ai agent init --kind prompt \
  --agent-name support-agent \
  --model <model-name> \
  --instructions "Answer support questions concisely."

Use --description for the prompt agent's summary. --rai-policy attaches an existing account policy by name or ARM ID; none inherits the account default. This option doesn't create policies and is ignored for hosted agents. When adopting a template, declare policies in azure.yaml instead.

For a managed prompt voice agent:

azd ai agent init --kind prompt-voice --agent-name support-voice

The managed voice model defaults to gpt-realtime and doesn't require a model deployment. Use --model and --voice to select the managed model and output voice. This path rejects source, protocol, code, and container settings. Deploy with azd provision and azd deploy, then use the voice WebSocket endpoint from azd ai agent show with a Voice Live client. Text invoke isn't a voice client.

To wrap a hosted agent with voice, adopt a full azure.yaml that declares both services. The voice service uses conversationEngine.type: hosted_agent and conversationEngine.name to reference the hosted target service. The earlier modelType: hosted_agent and targetAgent fields aren't supported.

Connect to an existing Foundry project

To manage an existing Foundry project through azd, run the wizard and select the option to connect to an existing project. You can also skip the interactive selection by providing the project's Azure resource ID directly:

azd ai agent init --project-id /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}

To find the project ID, open the Foundry portal, go to Manage > Project details, and copy the Resource ID value.

Warning

When you initialize against an existing project with --project-id, the tooling skips the automatic role assignments that it performs when it creates a new project. Make sure the required roles are already assigned. For the full matrix, see Hosted agent permissions reference.

Review what gets created

By default, init creates the following project structure. You need a Dockerfile only for container deployment:

.
|-- azure.yaml                  # Unified azd project and hosted agent configuration
|-- src/
|   \-- <agent-name>/
|       |-- Dockerfile          # Container build definition
|       \-- ...                 # Agent source code
|-- .azure/                     # Environment configuration
\-- infra/                      # Optional IaC, created when you pass --infra

Templates and samples publish a unified azure.yaml at the project root. During init, azd adopts or generates that file. By default, you don't need to maintain Bicep or Terraform files unless you choose to eject the infrastructure.

For Python agents, review the generated agent service and add PYTHONNOUSERSITE: "1" to its env map before local testing or deployment. Install dependencies in the agent's virtual environment or image rather than the user-site directory. See Configure Python startup.

Choose Terraform or Bicep infrastructure

To manage infrastructure with Terraform, select it when you initialize your project:

azd ai agent init --infra=terraform

Infrastructure and deployment mode are independent choices. For a container-based agent with Terraform infrastructure, use:

azd ai agent init --infra=terraform --deploy-mode container

For a new project, the command writes Terraform files under infra/ and configures the Terraform infrastructure provider in azure.yaml. In a project with existing infrastructure, Foundry infrastructure can be generated as a separate layer under infra/foundry/. Review the generated configuration before provisioning.

To choose Bicep instead, use --infra=bicep or the shorthand --infra. Omitting --infra preserves the default infrastructure-less workflow.

azd provision applies the selected infrastructure. azd deploy still creates the hosted-agent version; choosing Terraform doesn't move agent-version management into Terraform state.

For file structure and customization, see Hosted agent infrastructure. Before using Terraform in a pipeline, configure Terraform CI/CD and remote state.

Related content

  • Last updated on