azd<\/code>), which we’re excited to announce at Ignite 2025. Our goal was to simplify the entire workflow. This new extension helps you build, provision, and publish AI agents on Microsoft Foundry, bridging the gap between local development and cloud deployment. It brings everything you need into your terminal and code editor, letting you go from an agent idea on your machine to a running, shareable agent in Azure with minimal friction.<\/p>\nWith this extension, agents become a part of your toolchain. You get the power of Foundry’s advanced features (from multi-model reasoning to integrated evaluations) combined with the developer-first workflow of azd<\/code>. This extension empowers you to rapidly iterate on AI agents locally and reliably push them to the cloud for at-scale use, all using a consistent set of tools.<\/p>\nWhat is the new azd<\/code> AI agent extension?<\/h2>\nThe new azd ai agent<\/code> extension adds agent-centric workflows directly into the Azure Developer CLI. It integrates Foundry projects, model deployments, and agent definitions leveraging the azd<\/code> concepts, such as azd init<\/code> and azd up<\/code>. When paired with a template that includes Infrastructure as Code (IaC) or when you bring your own IaC, this extension automates the process of provisioning Azure resources, configuring model deployments, and publishing agents.<\/p>\n![\"azd](\"https:\/\/devblogs.microsoft.com\/azure-sdk\/wp-content\/uploads\/sites\/58\/2025\/11\/11-19-azd-ai-agent-extension.png\")
<\/p>\n
These new features handle three critical aspects of agent development:<\/p>\n
\n- Project scaffolding<\/strong>: Initialize a new project with an agent-ready starter template that includes pre-configured IaC files you need to get started, then initializes agents from a manifest file.<\/li>\n
- Resource provisioning<\/strong>: After you’ve initialized your IaC and agents, then the extension will provision and configure Foundry projects, deploy models with proper SKUs and capacity settings, and establish required connections.<\/li>\n
- Agent deployment<\/strong>: Package your agent, push container images to Azure Container Registry, and deploy agents to Foundry where they become shareable, production-ready services.<\/li>\n<\/ul>\n
The result? You can go from an empty folder to a deployed, callable agent endpoint in minutes instead of hours. Ready to see how?<\/p>\n
Key features<\/h2>\n
The new azd ai agent<\/code> extension provides several powerful features that accelerate your agent development:<\/p>\n\n- \n
Simplify agent project initialization<\/strong>: Use starter templates that include the necessary IaC to scaffold complete projects. azd<\/code> creates the necessary directory structure, IaC files, and configuration so you can start building immediately.<\/p>\n<\/li>\n- \n
Declarative configuration<\/strong>: Define your entire agent stack\u2014services, resources, and model deployments\u2014in a declarative azure.yaml<\/code> file. This approach makes your agent infrastructure version-controlled, repeatable, and easy to share across teams.<\/p>\n<\/li>\n- \n
Unified provisioning and deployment<\/strong>: Use the familiar azd up<\/code> command to provision infrastructure and deploy your agent. azd<\/code> handles the container builds, registry pushes, resource provisioning, and agent deployment automatically.<\/p>\n<\/li>\n- \n
Agent definition management<\/strong>: Pull agent definitions from GitHub repositories or local paths. The azd ai agent init<\/code> command analyzes the definition, updates your project configuration, and maps parameters to environment variables automatically.<\/p>\n<\/li>\n- \n
Secure by default<\/strong>: azd<\/code> handles, with IaC files in templates, the boilerplate security configuration for you. It automatically configures your agent with a managed identity for secure access to Azure resources, following recommended practices without manual setup.<\/p>\n<\/li>\n<\/ul>\nGetting started<\/h2>\n
Let’s walk through creating and deploying your first Foundry agent using the new AI agent features in azd<\/code>.<\/p>\nPrerequisites<\/h3>\n
Before you begin, ensure you have:<\/p>\n
\n- Azure Developer CLI (
azd<\/code>)<\/a> (version 1.21.3 or later) installed and authenticated (azd auth login<\/code>). <\/li>\n- The
azd ai agent<\/code> extension installed (azd extension install azure.ai.agents<\/code>); and, if you don’t have the extension installed, when you initialize the starter template or run azd ai agent<\/code> the extension is installed automatically.<\/li>\n- An Azure subscription with permissions to create resource groups and Foundry resources. Sign up for a free account at azure.com\/free<\/a> if you don’t have one.<\/li>\n
- Azure CLI (
az<\/code>) installed for certain operations.<\/li>\n<\/ul>\nInitialize with a Foundry configuration template<\/h3>\n
This extension works with an azd template and is also able to connect to an existing project using azd ai agent init --project-id [resourceID]<\/code>.<\/p>\nIn this post, we’ll walk through the approach of starting with a template. It’s a basic template for Foundry Agent Service to get started quickly.<\/p>\n
\n- Basic Setup<\/strong> (
azd-ai-starter-basic<\/code>): Optimized for speed and simplicity with all essential resources<\/li>\n<\/ul>\nStart by initializing a new project with the Basic Setup template. In an empty folder, run:<\/p>\n
azd init -t Azure-Samples\/azd-ai-starter-basic<\/code><\/pre>\nWhen prompted, provide an environment name for your agent project (for example, “my-agent-project”).<\/p>\n
The azd init<\/code> process:<\/p>\n\n- Clones the starter template files into your project<\/li>\n
- Creates the directory structure with
infra\/<\/code> (IaC files) and src\/<\/code> folders<\/li>\n- Generates an
azure.yaml<\/code> configuration file<\/li>\n- Sets up
.azure\/<env>\/.env<\/code> for environment-specific variables<\/li>\n<\/ul>\nReview your project structure<\/h3>\n
The initialized template includes these key files:<\/p>\n
\u251c\u2500\u2500 .azure\/ # Environment-specific settings (.env)\n\u251c\u2500\u2500 infra\/ # Bicep files for Azure infrastructure\n\u2514\u2500\u2500 azure.yaml # Project configuration<\/code><\/pre>\nOpen the azure.yaml<\/code> file to see how your agent project is configured:<\/p>\n# yaml-language-server: $schema=https:\/\/raw.githubusercontent.com\/Azure\/azure-dev\/main\/schemas\/v1.0\/azure.yaml.json\nname: my-agent-project\n\ninfra:\n provider: bicep\n path: .\/infra\n\nrequiredVersions:\n extensions:\n # the azd ai agent extension is required for this template\n \"azure.ai.agents\": latest<\/code><\/pre>\nThis declarative configuration defines your agent service and the Azure AI resources it needs, including model deployments. To read more about the azure.yaml<\/code> schema, see the Azure Developer CLI documentation<\/a> and azd environment variables that the agent relies on, such as AZURE_AI_ACCOUNT_NAME<\/code> and AZURE_AI_PROJECT_NAME<\/code>, see the azd environment variables documentation<\/a>.<\/p>\nInitialize your agent definition<\/h3>\n
The starter template provides the project structure, but you need to add a specific agent definition. Agent definitions describe your agent’s behavior, tools, and capabilities. You can find example definitions in the Agent Framework repository<\/a>.<\/p>\nFor this walkthrough, use an agent definition manifest:<\/p>\n
azd ai agent init -m <agent-definition-url><\/code><\/pre>\nAs an example, you can use the following URL for a simple calculator agent:<\/p>\n
azd ai agent init -m https:\/\/github.com\/azure-ai-foundry\/foundry-samples\/blob\/main\/samples\/microsoft\/hosted-agents\/python\/calculator-agent\/agent.yaml<\/code><\/pre>\nHere’s what happens when you run azd ai agent init<\/code>:<\/p>\n\n- Downloads the agent definition YAML file into your project’s
src\/<\/code> directory.<\/li>\n- Analyzes the agent definition to understand its requirements.<\/li>\n
- Updates
azure.yaml<\/code> with the corresponding services and configurations.<\/li>\n- Maps agent parameters to environment variables.<\/li>\n<\/ul>\n
After running azd ai agent init<\/code>, review the updated azure.yaml<\/code> and .env<\/code> files to see how your agent is configured. The azure.yaml<\/code> file looks like:<\/p>\nrequiredVersions:\n extensions:\n azure.ai.agents: latest\n azure.ai.agents: latest\nname: my-agent-project\nservices:\n CalculatorAgent:\n project: src\/CalculatorAgent\n host: azure.ai.agent\n language: docker\n docker:\n remoteBuild: true\n config:\n container:\n resources:\n cpu: \"1\"\n memory: 2Gi\n scale:\n maxReplicas: 3\n minReplicas: 1\n deployments:\n - model:\n format: OpenAI\n name: gpt-4o-mini\n version: \"2024-07-18\"\n name: gpt-4o-mini\n sku:\n capacity: 10\n name: GlobalStandard<\/code><\/pre>\nProvision and deploy your agent<\/h3>\n
Now with your project is configured, you can deploy everything to Azure with one command:<\/p>\n
azd up<\/code><\/pre>\nThis single command orchestrates the entire deployment workflow, from infrastructure to a live agent endpoint. Here’s what happens step-by-step:<\/p>\n
\n- Provisions Infrastructure<\/strong>: Creates the Foundry account, project, and all necessary Azure resources defined in the Bicep files.\n
\n- Pre-provision hooks inspect the agents and their dependencies, models, and other resources, then populates environment variables so that Bicep knows what to provision, including:<\/li>\n
AI_PROJECT_DEPLOYMENTS<\/code> (JSON): Specification of the models to deploy.<\/li>\nAI_PROJECT_CONNECTIONS<\/code> (JSON): Specification of the connections to create.<\/li>\nAI_PROJECT_DEPENDENT_RESOURCES<\/code> (JSON): Specification of the dependent resources.<\/li>\nENABLE_HOSTED_AGENTS<\/code> (boolean): Whether hosted agents need to be provisioned (with an ACR and CapHost).<\/li>\n<\/ul>\n<\/li>\n- Deploys Models<\/strong>: Provisions the model deployments specified in
azure.yaml<\/code> (for example, GPT-4o-mini with the configured SKU and capacity).<\/li>\n- Builds & Pushes Container<\/strong>: If the agent has custom code,
azd<\/code> packages it into a container image and pushes it to your Azure Container Registry.<\/li>\n- Publishes Agent<\/strong>: Creates an Agent Application in Foundry and deploys your agent as a live, callable service.<\/li>\n<\/ol>\n
The entire process typically completes in 5-10 minutes for a new project. When azd up<\/code> finishes, there are links in the terminal output to the agent playground portal and the agent endpoint.<\/p>\nThe agent is now live and ready to use. From an empty folder to a running agent, all with just three commands:<\/p>\n
\nazd init -t Azure-Samples\/azd-ai-starter-basic<\/code><\/li>\nazd ai agent init -manifest <agent-definition-url><\/code><\/li>\nazd up<\/code><\/li>\n<\/ol>\nTest your agent in Foundry<\/h3>\n
Now for the fun part\u2014let’s make sure your agent is working.<\/p>\n
\n- Follow the link in the terminal output. (Alternatively, open the Foundry portal<\/a> and navigate to the project provisioned by
azd<\/code> which is the project name was displayed in the azd up<\/code> output).<\/li>\n- Open the Agents<\/strong> section to see your deployed agent.<\/li>\n
- Launch the agent in the playground and send a test query, for example: “Summarize your capabilities.”<\/li>\n<\/ol>\n
If your agent responds successfully, congratulations! You’ve just deployed a working Foundry agent from your local development environment.<\/p>\n
How it works: Under the hood<\/h2>\n
So, what’s happening behind the scenes when you run these azd<\/code> commands? Let’s break down the how this transforms your local project into a cloud-native AI agent. The process follows a clear, logical flow from scaffolding to a secure, running service.<\/p>\n1. Project scaffolding and configuration<\/h3>\n
When you run azd init<\/code> with a Foundry template, azd<\/code> sets up a complete, well-structured project. The template includes:<\/p>\n\n- Bicep infrastructure files<\/strong> in the
infra\/<\/code> directory that define all the necessary Foundry resources, model deployments, and networking.<\/li>\n- An
azure.yaml<\/code> file<\/strong> that provides a declarative map of your services, resources, and dependencies.<\/li>\n- Environment configurations<\/strong> in
.azure\/<env>\/.env<\/code> that store subscription IDs, resource names, and endpoints.<\/li>\n- An
agent.yaml<\/code> file<\/strong> in the src\/<\/code> directory that stores the environment variables the agent needs. For example:<\/li>\n<\/ul>\nkind: hosted\nname: CalculatorAgent\ndescription: This LangGraph agent can perform arithmetic calculations such as addition, subtraction, multiplication, and division.\nmetadata:\n authors:\n - migu\n example:\n - content: What is the size of France in square miles, divided by 27?\n role: user\n tags:\n - example\n - learning\nprotocols:\n - protocol: responses\n version: v1\nenvironment_variables:\n - name: AZURE_OPENAI_ENDPOINT\n value: ${AZURE_OPENAI_ENDPOINT}\n - name: OPENAI_API_VERSION\n value: 2025-03-01-preview<\/code><\/pre>\nNext, when you run azd ai agent init<\/code>, the CLI:<\/p>\n\n- Fetches the agent definition from the URL or local path you provided.<\/li>\n
- Parses the YAML to understand the agent’s requirements (models, tools, connections).<\/li>\n
- Updates
azure.yaml<\/code> to include the agent as a service.<\/li>\n- Creates or updates the environment variables needed for the agent’s runtime.<\/li>\n<\/ul>\n
2. Resource provisioning<\/h3>\n
The azd up<\/code> command triggers all infrastructure provisioning through Azure Resource Manager. Based on your azure.yaml<\/code> and Bicep files, azd<\/code>:<\/p>\n\n- Compiles your Bicep templates into ARM templates.<\/li>\n
- Creates the resource group in your specified Azure region.<\/li>\n
- Provisions the Foundry account and project.<\/li>\n
- Deploys the specified models to the project with your configured SKUs and capacity.<\/li>\n<\/ul>\n
For example, if your azure.yaml<\/code> specifies gpt-4o-mini<\/code> with version 2024-07-18<\/code>, azd<\/code> creates that exact model deployment in your Foundry project. This declarative approach ensures consistency between environments, so your development, staging, and production deployments use identical configurations.<\/p>\n3. Container build and publishing<\/h3>\n
For agents with custom code (for custom tools, integrations, or business logic), azd<\/code> handles the complete containerization workflow:<\/p>\n\n- Build<\/strong>: Packages your agent code into a Docker container image using the configuration from your project.<\/li>\n
- Push<\/strong>: Authenticates to Azure Container Registry and pushes the image with a unique tag.<\/li>\n
- Deploy<\/strong>: Creates an agent in the Foundry and a deployment that runs your container.<\/li>\n<\/ol>\n
Your agent is deployed to the Foundry hosted agent service, which provides automatic scaling, managed compute, and integrated monitoring. The Agent Application becomes the stable, versionable interface for your agent, with a unique name and endpoint.<\/p>\n
4. Identity and security<\/h3>\n
Finally, azd<\/code> automatically configures secure access patterns with IaC so you don’t have to manage credentials manually:<\/p>\n\n- Managed Identity<\/strong>: Your agent uses the Foundry project’s system-assigned managed identity for authenticating to other Azure resources.<\/li>\n
- Role Assignments<\/strong>: Required permissions are granted automatically (for example, giving your agent access to Azure AI services, storage, or databases) with the starter template.<\/li>\n
- Endpoint Security<\/strong>: Agent endpoints use Azure AD authentication by default to ensure only authorized users or applications can call your agent.<\/li>\n<\/ul>\n
These security configurations in the template follow Azure recommended practices and work out of the box, giving you a secure foundation from the start.<\/p>\n
Use cases and scenarios<\/h2>\n
Now that you have a solid understanding of how these azd<\/code> features work, let’s explore how you can use them to build different kinds of agents. For complete, ready-to-deploy examples, check out:<\/p>\n\n- Python hosted agents samples<\/a><\/li>\n
- .NET hosted agents samples<\/a>.<\/li>\n<\/ul>\n
Building conversational AI assistants<\/h3>\n
Create intelligent customer service agents that understand context, access knowledge bases, and provide personalized responses. With azd<\/code>, you can:<\/p>\n\n- Rapidly deploy multiple agent variations for A\/B testing<\/li>\n
- Integrate agents with Azure AI Search for retrieval-augmented generation<\/li>\n
- Connect to business systems and APIs through custom tools<\/li>\n
- Version and roll back agent deployments as you iterate<\/li>\n<\/ul>\n
Data analysis and insights agents<\/h3>\n
Build agents that analyze data, generate visualizations, and provide insights. With azd<\/code>, you can:<\/p>\n\n- Provision agents with access to Azure SQL Database or Cosmos DB.<\/li>\n
- Deploy specialized models for quantitative analysis.<\/li>\n
- Create agents that use code interpreter tools for calculations.<\/li>\n
- Publish agents to help learn French.<\/li>\n<\/ul>\n
Multi-agent orchestration<\/h3>\n
Develop systems where multiple specialized agents collaborate on complex tasks:<\/p>\n
\n- Deploy a coordinator agent that routes requests to specialist agents<\/li>\n
- Provision each agent with different model configurations for optimal performance<\/li>\n
- Use the declarative
azure.yaml<\/code> to define agent relationships and dependencies<\/li>\n- Scale individual agents independently based on workload<\/li>\n<\/ul>\n
Enterprise agent deployment<\/h3>\n
Standardize agent development and deployment across your organization:<\/p>\n
\n- Create reusable agent blueprints that encode your organization’s best practices<\/li>\n
- Publish agent templates to internal catalogs for teams to consume<\/li>\n
- Enforce consistent security, compliance, and monitoring configurations<\/li>\n
- Automate agent deployment in CI\/CD pipelines using
azd provision<\/code> and azd deploy<\/code><\/li>\n<\/ul>\nAdvanced configuration<\/h2>\n
Once you’re comfortable with the basic workflow, you can start customizing your deployments to meet more advanced requirements.<\/p>\n
Customizing model deployments<\/h3>\n
Your azure.yaml<\/code> file gives you full control over which models get deployed. To add or change a model, edit the file:<\/p>\nservices:\n CalculatorAgent:\n project: src\/CalculatorAgent\n host: azure.ai.agent\n language: docker\n docker:\n remoteBuild: true\n config:\n container:\n resources:\n cpu: \"1\"\n memory: 2Gi\n scale:\n maxReplicas: 3\n minReplicas: 1\n deployments:\n - model:\n format: OpenAI\n name: gpt-4o-mini\n version: \"2024-07-18\"\n name: gpt-4o-mini\n sku:\n capacity: 10\n name: GlobalStandard<\/code><\/pre>\nThis configuration provisions multiple models, enabling your agent to use different models for different tasks (for example, a larger model for complex reasoning and a smaller one for simple queries). When you next run azd up<\/code>, it automatically deploys the new model and update your project.<\/p>\nManaging environment variables<\/h3>\n
Key environment variables azd<\/code> sets or uses:<\/p>\n\n\n\nVariable<\/th>\n Purpose<\/th>\n<\/tr>\n<\/thead>\n \n\nAZURE_SUBSCRIPTION_ID<\/code><\/td>\nTarget subscription for resources.<\/td>\n<\/tr>\n \nAZURE_RESOURCE_GROUP<\/code><\/td>\nResource group hosting the AI project.<\/td>\n<\/tr>\n \nAZURE_LOCATION<\/code><\/td>\nAzure region (must support chosen models).<\/td>\n<\/tr>\n \nAZURE_AI_PROJECT_ID<\/code><\/td>\nThe full Azure resource ID of your project.<\/td>\n<\/tr>\n \nAZURE_AI_PROJECT_NAME<\/code><\/td>\nProject hosting the agent.<\/td>\n<\/tr>\n \nAZURE_AI_PROJECT_ENDPOINT<\/code><\/td>\n