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 public preview. This preview is provided without a service-level agreement, and we don'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.25.2 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
You need the following roles on your Azure subscription.
| Role | Purpose |
|---|---|
| Contributor | Provision and manage Azure resources. |
| Foundry Owner | Required only if you create new Foundry projects. |
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.
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 all of the Foundry extensions for a single install. |
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 |
Manage Foundry project context (set, unset, show). |
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 is a thin meta-package that doesn't contribute its own commands. Installing it pulls in every individual extension, which is the recommended starting point. Installing azure.ai.agents on its own also pulls in azure.ai.inspector automatically, because the agent extension depends on it.
Install the full bundle
Install every Foundry extension 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 each individual extension. Each extension also exposes a version subcommand:
azd ai agent version
azd ai connection version
azd ai inspector version
azd ai project version
azd ai routine version
azd ai skill version
azd ai toolbox version
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.