Edit

Share via

Quickstart: Set up your first AI Foundry resource

In this quickstart, you create an Azure AI Foundry resource and verify access.

Learn how to create and manage an Azure AI Foundry resource. It's the primary Azure resource type for building, deploying, and managing generative AI models and applications including agents in Azure.

An Azure resource is required to use and manage services in Azure. It defines the scope for configuring access, security such as networking, billing, and monitoring.

Azure AI Foundry resource is the next version and renaming of former "Azure AI Services". It provides the application environment for hosting your agents, model deployments, evaluations, and more.

An Azure AI Foundry resource can organize the work for multiple use cases, and is typically shared between a team of developers that work on use cases in a similar business or data domain. Projects act as folders to group related work.

Diagram showing Azure AI Foundry resource containing multiple projects, each with deployments and connections.

Looking to configure AI Foundry with advanced security settings? See advanced AI Foundry creation options

Looking to use Azure AI Search skills? See Use Azure AI Foundry with Azure AI Search skills.

Create your first resource

To create your first resource, with basic Azure settings, follow the below steps using either Azure portal, Azure CLI, or PowerShell.

Prerequisites

  • A valid Azure subscription - Create one for free.
  • Azure RBAC role to create resources. You need one of the following roles assigned on your Azure subscription or resource group:
    • Contributor
    • Owner
    • Custom role with Microsoft.CognitiveServices/accounts/write permission

Create a new Azure AI Foundry resource

If your organization requires customized Azure configurations like alternative names, security controls or cost tags, you might need to use the Azure portal or template options to comply with your organization's Azure Policy compliance.

The Azure AI Foundry resource is listed under AI Foundry > AI Foundry in the Azure portal. The API kind is AIServices. Look for the logo as shown here:

Screenshot of the Azure AI Foundry resource in the Azure portal.

Tip

Azure AI Foundry portal provides a way to create a new Azure AI Foundry resource with basic, defaulted, settings.

To create an AI Foundry resource in the Azure portal follow these instructions:

  1. Select this AI Foundry resource link: https://portal.azure.com/#create/Microsoft.CognitiveServicesAIFoundry

  2. On the Create page, provide the following information:

    Project details Description
    Subscription Select one of your available Azure subscriptions.
    Resource group The Azure resource group that will contain your Azure AI Foundry resource. You can create a new group or add it to a preexisting group.
    Region The location of your Azure AI service instance. Different locations may introduce latency, but have no impact on the runtime availability of your resource.
    Name A descriptive name for your Azure AI Foundry resource. For example, MyAIServicesResource.

  3. Configure other settings for your resource as needed, read and accept the conditions (as applicable), and then select Review + create.

Tip

If your subscription doesn't allow you to create an AI Foundry resource, you might need to enable the privilege of that Azure resource provider using the Azure portal, PowerShell command or an Azure CLI command. If you are not the subscription owner, ask someone with the role of Owner or Admin to complete the registration for you or ask for the /register/action privileges to be granted to your account.

Clean up resources

If you want to clean up and remove an AI Foundry resource, you can delete the resource or resource group. Deleting the resource group also deletes any other resources contained in the group.

  1. In the Azure portal, expand the menu on the left side to open the menu of services, and choose Resource Groups to display the list of your resource groups.
  2. Locate the resource group containing the resource to be deleted.
  3. If you want to delete the entire resource group, select the resource group name. On the next page, Select Delete resource group, and confirm.
  4. If you want to delete only the Azure AI Foundry resource, select the resource group to see all the resources within it. On the next page, select the resource that you want to delete, select the ellipsis menu for that row, and select Delete.

Use this quickstart to create an AI Foundry resource using Azure Command-Line Interface (CLI) commands.

Prerequisites

  • A valid Azure subscription - Create one for free.
  • The Azure CLI version 2.0 or later.
  • Azure RBAC role to create resources. You need one of the following roles assigned on your Azure subscription or resource group:
    • Contributor
    • Owner
    • Custom role with Microsoft.CognitiveServices/accounts/write permission

Install the Azure CLI and sign in

Install the Azure CLI. To sign into your local installation of the CLI, run the az login command:

az login

Create a new resource group

Before you create an AI Foundry resource, you must have an Azure resource group to contain the resource. When you create a new resource, you can either create a new resource group, or use an existing one. This article shows how to create a new resource group.

To create a resource, you'll need one of the Azure locations available for your subscription. You can retrieve a list of available locations with the az account list-locations command. Most Azure AI services can be accessed from several locations. Choose the one closest to you, or see which locations are available for the service.

Important

  • Remember your Azure location, as you will need it when calling the Azure AI Foundry resources.
  • The availability of some Azure AI services can vary by region. For more information, see Azure products by region.
az account list-locations --query "[].{Region:name}" --out table

After you have your Azure location, create a new resource group in the Azure CLI using the az group create command. In the example below, replace the Azure location westus2 with one of the Azure locations available for your subscription.

az group create --name ai-services-resource-group --location westus2

Create an AI Foundry resource

To create and subscribe to a new Azure AI Foundry resource, use the az cognitiveservices account create command. This command adds a new billable resource to the resource group you created earlier. When you create your new resource, you'll need to know the kind of service you want to use, along with its pricing tier (or SKU) and an Azure location.

Important

Azure provides more than one resource kinds for Azure AI services. Be sure to create one with the kind of AIServices.

You can create an AI Foundry resource named foundry-multi-service-resource with the command below.

az cognitiveservices account create --name foundry-multi-service-resource --resource-group ai-services-resource-group  --kind AIServices --sku S0 --location westus2 --yes

Tip

If your subscription doesn't allow you to create an AI Foundry resource, you might need to enable the privilege of that Azure resource provider using the Azure portal, PowerShell command or an Azure CLI command. If you are not the subscription owner, ask someone with the role of Owner or Admin to complete the registration for you or ask for the /register/action privileges to be granted to your account.

Get current quota usage for your resource

Use the az cognitiveservices account list-usage command to get the usage for your resource.

az cognitiveservices account list-usage --name foundry-multi-service-resource --resource-group ai-services-resource-group --subscription subscription-name

Clean up resources

If you want to clean up and remove an AI Foundry resource, you can delete it or the resource group. Deleting the resource group also deletes any other resources contained in the group.

To remove the resource group and its associated resources, use the az group delete command.

az group delete --name ai-services-resource-group

Use this quickstart to create an AI Foundry resource using Azure PowerShell commands.

Prerequisites

  • A valid Azure subscription - Create one for free.
  • Azure PowerShell version 5.0 or later.
  • Azure RBAC role to create resources. You need one of the following roles assigned on your Azure subscription or resource group:
    • Contributor
    • Owner
    • Custom role with Microsoft.CognitiveServices/accounts/write permission

Install Azure PowerShell and sign in

Install Azure PowerShell. To sign in, run the Connect-AzAccount command:

Connect-AzAccount

Create a new Azure AI Foundry resource group

Before you create an AI Foundry resource, you must have an Azure resource group to contain the resource. When you create a new resource, you can either create a new resource group, or use an existing one. This article shows how to create a new resource group.

To create a resource, you'll need one of the Azure locations available for your subscription. You can retrieve a list of available locations with the Get-AzLocation command. Most Azure AI services can be accessed from several locations. Choose the one closest to you, or see which locations are available for the service.

Important

  • Remember your Azure location, as you will need it when calling the Azure AI Foundry resources.
  • The availability of some Azure AI services can vary by region. For more information, see Azure products by region.
Get-AzLocation | Select-Object -Property Location, DisplayName

After you have your Azure location, create a new resource group in Azure PowerShell using the New-AzResourceGroup command. In the example below, replace the Azure location westus2 with one of the Azure locations available for your subscription.

New-AzResourceGroup -Name ai-services-resource-group -Location westus2

Create an AI Foundry resource

To create and subscribe to a new Azure AI Foundry resource, use the New-AzCognitiveServicesAccount command. This command adds a new billable resource to the resource group you created earlier. When you create your new resource, you'll need to know the "kind" of service you want to use, along with its pricing tier (or SKU) and an Azure location:

Important

Azure provides more than one resource kinds for Azure AI services. Be sure to create one with the Type (kind) of AIServices.

You can create an AI Foundry resource named foundry-multi-service-resource with the command below.

New-AzCognitiveServicesAccount -ResourceGroupName ai-services-resource-group -Name foundry-multi-service-resource -Type AIServices -SkuName S0 -Location westus2

Tip

If your subscription doesn't allow you to create an AI Foundry resource, you might need to enable the privilege of that Azure resource provider using the Azure portal, PowerShell command or an Azure CLI command. If you are not the subscription owner, ask someone with the role of Owner or Admin to complete the registration for you or ask for the /register/action privileges to be granted to your account.

Get current quota usage for your resource

Use the Get-AzCognitiveServicesAccountUsage command to get the usage for your resource.

Get-AzCognitiveServicesAccountUsage -ResourceGroupName ai-services-resource-group -Name foundry-multi-service-resource

Clean up resources

If you want to clean up and remove an AI Foundry resource, you can delete it or the resource group. Deleting the resource group also deletes any other resources contained in the group.

To remove the resource group and its associated resources, use the Remove-AzResourceGroup command.

Remove-AzResourceGroup -Name ai-services-resource-group

Access your resource

With your first resource created, you can access it via Foundry Portal for UX prototyping, Foundry SDK for development, or via Azure portal for administrative management.

Verify your setup

You can verify that your resource is set up correctly by using the Azure AI Projects SDK to connect and list projects. This minimal example confirms authentication and access.

# Install the SDK: pip install azure-ai-projects azure-identity
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

# Replace with your actual values from Azure portal
client = AIProjectClient(
    subscription_id="<your-subscription-id>",
    resource_group_name="<your-resource-group>",
    project_name="<your-project-name>",
    credential=DefaultAzureCredential()
)

# List projects to verify connection
projects = client.projects.list()
print(f"Successfully connected. Found {len(list(projects))} projects.")

Expected output: Successfully connected. Found X projects. where X is the number of projects in your resource.

References:

Grant or obtain developer permissions

Azure Role Based Access Control (RBAC) differentiates permissions between management and development actions. To build with Foundry, your user account must be assigned developer permissions ("data actions"). You can either use one of the built-in RBAC roles, or use a custom RBAC role.

Built-in Azure RBAC developer roles for Foundry include:

Role Description
Azure AI project manager Grants development permissions, and project management permissions. Can invite other users to collaborate on a project as 'Azure AI user'.
Azure AI user Grants development permissions.

Only authorized users, typically the Azure subscription or resource group owner, can assign a role via either [Azure portal] or [AI Foundry Portal via management center]. Learn more about role-based access control.

Important

Azure Owner and Contributor roles do only include management permissions, and not development permissions. Development permissions are required to build with all capabilities in Foundry.

Start building in your first project

With permissions set up, you're now ready to start building Foundry. In Azure AI Foundry Portal open or create your first project. Projects organize your agent and model customization work in Foundry, and you can create multiple under the same resource.

Explore some of the services that come bundled with your resource:

Service Description
Azure AI Foundry icon Azure AI Foundry Agent Service Combine the power of generative AI models with tools that allow agents to access and interact with real-world data sources.
Azure AI Foundry icon Azure AI Model Inference Performs model inference for flagship models in the Azure AI Foundry model catalog.
Azure OpenAI in Azure AI Foundry Models icon Azure OpenAI Perform a wide variety of natural language tasks.
Content Safety icon Content Safety An AI service that detects unwanted contents.
Document Intelligence icon Document Intelligence Turn documents into intelligent data-driven solutions.
Language icon Language Build apps with industry-leading natural language understanding capabilities.
Speech icon Speech Speech to text, text to speech, translation, and speaker recognition.
Translator icon Translator Use AI-powered translation technology to translate more than 100 in-use, at-risk, and endangered languages and dialects.

Next steps