Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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.
The Azure Developer CLI (azd) ai extensions let you build, deploy, evaluate, and operate AI agents on Microsoft Foundry from your terminal. In this article, you install the extensions, verify the installation, and authenticate to Azure.
Prerequisites
- An Azure subscription. Create one for free.
- Azure Developer CLI (
azd) version 1.37.0 or later. Install azd. - Python 3.10 or later, or .NET 8 or later, depending on the agent framework you plan to use.
Azure permissions
Permissions depend on the resources your workflow creates or reuses. For prompt-agent workflows:
| Scenario | Required permissions |
|---|---|
| Reuse an existing project and model deployment | Foundry User on the project to create and invoke agents. |
| Create resources and assign project roles during provisioning | Permission to create the resources and assign roles at the target scope. For example, Contributor and Role Based Access Control Administrator together provide these permissions. |
Create project connections, including a Toolbox connection created by azd |
Foundry Project Manager on the project. Reusing an existing connection doesn't require permission to create one. |
Important
The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.
Scope roles to the resources your workflow uses. For details, see Elevated-role tasks in Foundry. Hosted-agent deployment has additional requirements; see Hosted agent permissions.
Understand how the extensions are packaged
The azd ai namespace is composed of multiple independent azd extensions. Each one contributes a top-level command group under azd ai.
| Extension ID | Command group | What it does |
|---|---|---|
microsoft.foundry |
meta-package | Bundles the seven core Foundry extensions listed below. |
azure.ai.agents |
azd ai agent |
Ship agents with Foundry from your terminal. |
azure.ai.connections |
azd ai connection |
Manage Foundry project connections. |
azure.ai.inspector |
azd ai inspector |
Browser-based inspector UI for locally running agents. |
azure.ai.projects |
azd ai project |
Configure project resources and model deployments, and manage endpoint context. |
azure.ai.routines |
azd ai routine |
Manage Foundry routines (timers, schedules, event triggers). |
azure.ai.skills |
azd ai skill |
Manage Foundry skills (reusable agent behavioral guidelines). |
azure.ai.toolboxes |
azd ai toolbox |
Manage Foundry toolboxes (versioned tool collections). |
The microsoft.foundry package doesn't contribute its own commands. It installs the seven core extensions listed above, not every extension in the ai namespace. Installing azure.ai.agents also installs its dependencies, including the inspector and project, connection, and toolbox support.
Install these independently when your workflow needs them:
| Extension ID | Command group | Job |
|---|---|---|
azure.ai.content-understanding |
azd ai cu |
Analyze documents, images, audio, and video with Azure Content Understanding (preview). |
azure.ai.evaluations |
azd ai eval |
Scaffold project evaluations, manage evaluators, inspect results, and gate builds. |
azure.ai.dataset |
azd ai dataset |
Register, version, download, and delete datasets. |
azure.ai.finetune |
azd ai finetuning |
Submit and manage fine-tuning jobs and deploy their models. |
azure.ai.models |
azd ai models |
Upload, register, inspect, and maintain custom model weights. |
azd ext install azure.ai.content-understanding
azd ext install azure.ai.evaluations
azd ext install azure.ai.dataset
azd ext install azure.ai.finetune
azd ext install azure.ai.models
Install the full bundle
Install the core Foundry extensions in one step through the meta-package:
azd ext install microsoft.foundry
To update later:
azd ext upgrade microsoft.foundry
Install or upgrade an individual extension
You can also manage each extension on its own:
# Just the agent surface
azd ext install azure.ai.agents
# Just the routine surface
azd ext install azure.ai.routines
# Upgrade one extension without touching the others
azd ext upgrade azure.ai.connections
The individual extensions are independently versioned, so you can pin or upgrade one at a time.
Verify the installation
List installed extensions:
azd ext list
You should see microsoft.foundry plus its core extensions. Optional extensions appear only if installed separately. Each extension with a command namespace also exposes a version subcommand:
azd ai agent version
azd ai connection version
azd ai cu version
azd ai inspector version
azd ai project version
azd ai routine version
azd ai skill version
azd ai toolbox version
Use azd ai --help to see the namespaces contributed by your installed extensions, and append --help to a command to inspect its current flags. Extensions are independently versioned; a newer source checkout doesn't mean a feature is in the published extension.
Enable the Copilot harness preview
To use the Microsoft Copilot harness with prompt agents, install azure.ai.agents version 1.0.0-beta.22 or later and enable its preview in the shell where you run azd.
For Bash:
export AZD_ALPHA_ENABLE_AGENTS_MANAGED_HARNESS=true
For PowerShell:
$env:AZD_ALPHA_ENABLE_AGENTS_MANAGED_HARNESS = "true"
Set the variable in each new shell or CI job. This CLI opt-in doesn't grant access to the service or change your Azure permissions.
Authenticate
Sign in to Azure so the CLI can provision and manage resources on your behalf:
azd auth login
This command opens a browser window for interactive authentication. After you sign in, the CLI caches your credentials locally for subsequent commands.