Quickstart: Set up Microsoft Foundry resources

• Install the Azure CLI version 2.80.0 or later. Check your version with az version, and run az upgrade if you need a newer one.

  Version 2.80.0 added the az cognitiveservices account project commands that these steps use. On an earlier version, the commands fail with unrecognized arguments or 'project' is misspelled or not recognized by the system.

• Sign in to Azure:

  az login
  

• Access to the Microsoft Foundry portal.

1. Create a resource group or use an existing one. For example, create my-foundry-rg in eastus:

   az group create --name my-foundry-rg --location eastus
   

   Verify that the resource group exists:

   az group show --name my-foundry-rg --query properties.provisioningState --output tsv
   

   The output shows Succeeded.

2. Create the Foundry resource with project management enabled. For example, create my-foundry-resource in the my-foundry-rg resource group:

   az cognitiveservices account create \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --kind AIServices \
       --sku S0 \
       --location eastus \
       --custom-domain my-foundry-resource \
       --assign-identity \
       --allow-project-management true
   

   Use these values:

   Parameter	Purpose
   --assign-identity	Creates the managed identity that project management requires. Without it, project creation fails with an error that a managed identity must be enabled on the resource.
   --allow-project-management	Enables project management. You can't change this setting after you create the resource.
   --custom-domain	Must be globally unique. If my-foundry-resource is taken, the command fails with CustomDomainInUse. Choose a different name and run the command again.

3. Create a project. For example, create my-foundry-project in the my-foundry-resource:

   az cognitiveservices account project create \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --project-name my-foundry-project \
       --location eastus
   

4. Verify that the resource is provisioned:

   az cognitiveservices account show \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --query properties.provisioningState --output tsv
   

   The output should show Succeeded. If the output shows a different state, check your permissions, region availability, and resource quotas. For more help, see Create a multi-service resource.

5. Verify the project was created:

   az cognitiveservices account project show \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --project-name my-foundry-project \
       --query properties.provisioningState --output tsv
   

   The output should show Succeeded. If the command fails with a message that a managed identity must be enabled, confirm that you created the resource with --assign-identity.

Reference: az cognitiveservices account project

1. Sign in to Microsoft Foundry. Make sure the New Foundry toggle is on. These steps refer to Foundry (new).

   

2. Create a project.

   • If this is your first use of Foundry, you'll be asked to create or search for a project to continue. Select Create a new project in the dropdown.
   • If you already have a project loaded, select its name in the upper-left corner, and then select Create new project.

3. Enter a project name, such as my-foundry-project.

4. Select Advanced options to configure the resource group and location:

   • Resource group: Create a new resource group or select an existing one. If you create a new resource group, you can more easily manage the project and all its resources together.
   • Location: Select the region closest to your team.

5. Select Create project.

   Wait for the project to be created. When the project overview page appears, your project is ready.

1. List the models available in your region so you can confirm the model name and version:

   az cognitiveservices model list \
       --location eastus \
       --query "[?model.name=='gpt-5-mini'].{version:model.version,skus:join(',',model.skus[].name)}" \
       --output table
   

2. Deploy the model:

   az cognitiveservices account deployment create \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --deployment-name gpt-5-mini \
       --model-name gpt-5-mini \
       --model-version "2025-08-07" \
       --model-format OpenAI \
       --sku-capacity 10 \
       --sku-name GlobalStandard
   

   If the command fails with DeploymentModelNotSupported, the model, version, or SKU isn't available in your region. Use the output of the previous step to choose a supported combination.

3. Verify the deployment succeeded:

   az cognitiveservices account deployment show \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --deployment-name gpt-5-mini \
       --query properties.provisioningState --output tsv
   

   The output shows Succeeded when the deployment is ready.

Reference: az cognitiveservices account deployment

1. Select Discover in the upper-right navigation, then Models in the left pane.
2. Search for gpt-5-mini.
3. Select Deploy > Default settings to add it to your project.
4. Note the deployment name (for example, gpt-5-mini). Your team needs this name to use the model.

Get the project endpoint:

az cognitiveservices account project show \
    --name my-foundry-resource \
    --resource-group my-foundry-rg \
    --project-name my-foundry-project \
    --query 'properties.endpoints."AI Foundry API"' --output tsv

The output is your project endpoint, in the form https://my-foundry-resource.services.ai.azure.com/api/projects/my-foundry-project. Use this value in other quickstarts and tutorials.

1. Sign in to Microsoft Foundry by using your Azure account.
2. Select your project.
3. Find your project endpoint on the welcome screen of the project.
4. Copy the endpoint value. You use this value in other quickstarts and tutorials.

1. Get the project's resource ID:

   PROJECT_ID=$(az cognitiveservices account project show \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --project-name my-foundry-project \
       --query id -o tsv)
   

2. Assign the Foundry User role to a team member:

   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.

   az role assignment create \
       --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
       --assignee "user@contoso.com" \
       --assignee-principal-type User \
       --scope $PROJECT_ID
   

To add a security group instead of an individual user:

az role assignment create \
    --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
    --assignee-object-id "<security-group-object-id>" \
    --assignee-principal-type Group \
    --scope $PROJECT_ID

1. Verify the role assignment:

   az role assignment list \
       --scope $PROJECT_ID \
       --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
       --output table
   

Reference: az role assignment

1. In the Foundry portal, select Manage in the upper-right navigation.
2. Select Project details in the left pane.
3. Select the Users tab.
4. Select Add user in the upper right.
5. Enter the email address of the team member.
6. Select Add.

Repeat these steps for each team member or security group.

az group delete --name my-foundry-rg --yes --no-wait

Deletion runs in the background. To confirm that the resource group is gone, run:

az group exists --name my-foundry-rg

The output shows false when deletion finishes.

In the Azure portal, find and select your resource group. Select Delete and confirm to delete the resource group and all its associated resources.