Create a project for Azure AI Foundry

Article
2025-05-19

This article describes how to create an Azure AI Foundry project. Projects are folders that let you organize your work for exploring new ideas, and as you're prototyping on a particular use cases.

Azure AI Foundry supports two types of projects: a Foundry project and a hub based project. For more information about the differences between these two project types, see Types of projects.

Tip

The rest of this article shows how to create a hub based project. Select Foundry project at the top of this article if you want to create a Foundry project instead.

A hub based project is hosted by an Azure AI Foundry hub. If your company has an administrative team that created a hub for you, you can create a project from that hub. If you're working on your own, you can create a project and a default hub is automatically be created for you.
Use this project type for:
- Prompt flow
- Managed compute
- Azure Machine Learning compatibility
This project can also be used for:
- Agents (preview)
- Project-level isolation of files and outputs
- Evaluations
- Playgrounds

Prerequisites

Use the following tabs to select the method you plan to use to create a hub based project:

An Azure subscription. If you don't have an Azure subscription, create a free account.

Create a project

To create a hub based project in Azure AI Foundry, follow these steps:

Tip

Because you can customize the left pane in the Azure AI Foundry portal, you might see different items than shown in these steps. If you don't see what you're looking for, select ... More at the bottom of the left pane.

Sign in to Azure AI Foundry.
Select any existing project if you aren't already in one.
At the bottom of the left pane, select Management center.
At the top of the page, select All resources.
Select Create.
Select AI hub resource.
Enter a name for the project.
If you have a hub, you'll see the one you most recently used selected.
- If you have access to more than one hub, you can select a different hub from the dropdown.
- If you want to create a new one, select Create new hub and supply a name.
If you don't have a hub, a default one is created for you.
Select Create.

Or, if you want to customize a new hub, follow the steps in the next section before you select Create.

Customize the hub

A hub based project exists inside a hub. A hub allows you to share configurations like data connections with all projects, and to centrally manage security settings and spend. If you're part of a team, hubs are shared across other team members in your subscription. For more information about the relationship between hubs and projects, see the hubs and projects overview documentation.

When you create a new hub, you must have Owner or Contributor permissions on the selected resource group. If you're part of a team and don't have these permissions, your administrator should create a hub for you.

While you can create a hub as part of the project creation, you have more control and can set more advanced settings for the hub if you create it separately. For example, you can customize network security or the underlying Azure Storage account. For more information, see How to create and manage an Azure AI Foundry hub.

When you create a new hub as part of the project creation, default settings are provided. If you want to customize these settings, do so before you create the project:

In the Create a project form, select the arrow on the right side.
Select an existing Resource group you want to use, or leave the default to create a new resource group.

Tip

Especially for getting started we recommend you create a new resource group for your project. The resource group allows you to easily manage the project and all of its resources together. When you create a project, several resources are created in the resource group, including a hub, a container registry, and a storage account.
Select a Location or use the default. The ___location is the region where the hub is hosted. The ___location of the hub is also the ___location of the project. Azure AI services availability differs per region. For example, certain models might not be available in certain regions.
Select Create a project. You see progress of the resource creation. The project is created when the process is complete.

The code in this section assumes you have an existing hub. If you don't have a hub, see How to create and manage an Azure AI Foundry hub to create one.

Install azure-identity: pip install azure-identity. If in a notebook cell, use %pip install azure-identity.

Provide your subscription details:

# Enter details of your subscription
subscription_id = "<SUBSCRIPTION_ID>"
resource_group = "<RESOURCE_GROUP>"

Get a handle to the subscription. All the Python code in this article uses ml_client:

# get a handle to the subscription

from azure.ai.ml import MLClient
from azure.identity import DefaultAzureCredential

ml_client = MLClient(DefaultAzureCredential(), subscription_id, resource_group)

(Optional) If you have multiple accounts, add the tenant ID of the Microsoft Entra ID you wish to use into the DefaultAzureCredential. Find your tenant ID from the Azure portal under Microsoft Entra ID, External Identities.
```
DefaultAzureCredential(interactive_browser_tenant_id="<TENANT_ID>")
```
(Optional) If you're working on in the Azure Government - US or Azure China 21Vianet regions, specify the region into which you want to authenticate. You can specify the region with DefaultAzureCredential. The following example authenticates to the Azure Government - US region:
```
from azure.identity import AzureAuthorityHosts
DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
```

Use the following code to create a project from a hub you or your administrator created previously. Replace example string values with your own values:

from azure.ai.ml.entities import Project

my_project_name = "myexampleproject"
my_display_name = "My Example Project"
hub_name = "myhubname" # Azure resource manager ID of the hub
hub_id=f"/subscriptions/{subscription_id}/resourceGroups/{resource_group}/providers/Microsoft.MachineLearningServices/workspaces/{hub_name}"

my_project = Project(name=my_project_name, 
                display_name=my_display_name,
                hub_id=hub_id)

created_project = ml_client.workspaces.begin_create(workspace=my_project).result()

The code in this section assumes you have an existing hub. If you don't have a hub, see How to create and manage an Azure AI Foundry hub to create one.

To authenticate to your Azure subscription from the Azure CLI, use the following command:
```
az login
```
For more information on authenticating, see Authentication methods.
Once the extension is installed and authenticated to your Azure subscription, use the following command to create a new Azure AI Foundry project from an existing Azure AI Foundry hub:
```
az ml workspace create --kind project --hub-id {my_hub_ID} --resource-group {my_resource_group} --name {my_project_name}
```
Form my_hub_ID with this syntax: /subscriptions/{subscription_id}/resourceGroups/{resource_group}/providers/Microsoft.MachineLearningServices/workspaces/{hub_name}.

View project settings

On the project Overview page, you can find information about the project.

Name: The name of the project appears in the top left corner. You can rename the project using the edit tool.
Subscription: The subscription that hosts the hub that hosts the project.
Resource group: The resource group that hosts the hub that hosts the project.

Select Management center to navigate to the project resources in Azure AI Foundry portal. Select Manage in Azure portal to navigate to the project resources in the Azure portal.

To manage or use the new project, include it in the MLClient:

ml_client = MLClient(workspace_name=my_project_name, resource_group_name=resource_group, subscription_id=subscription_id,credential=DefaultAzureCredential())

To view settings for the project, use the az ml workspace show command. For example:

az ml workspace show --name {my_project_name} --resource-group {my_resource_group}

Access project resources

Common configurations on the hub are shared with your project, including connections, compute instances, and network access, so you can start developing right away.

In addition, many resources are only accessible by users in your project workspace:

Components including datasets, flows, indexes, deployed model API endpoints (open and serverless).
Connections created by you under 'project settings.'

Azure Storage blob containers, and a fileshare for data upload within your project. Access storage using the following connections:

Data connection	Storage ___location	Purpose
workspaceblobstore	{project-GUID}-azureml-blobstore	Default container for data uploads
workspaceartifactstore	{project-GUID}-azureml	Stores components and metadata for your project such as model weights
workspacefilestore	{project-GUID}-code	Hosts files created on your compute and using prompt flow

Note

Storage connections aren't created directly with the project when your storage account has public network access set to disabled. These are created instead when a first user accesses Azure AI Foundry over a private network connection. Troubleshoot storage connections

Tip

The rest of this article shows how to create a Foundry project. Select hub based project at the top of this article if you want to create a hub based project instead.

A Foundry project is built on an Azure AI Foundry resource. This project type allows for a simple setup, access to agents, and industry leading models from OpenAI, Mistral, Meta, and more.
This project type gives you the best support for:
- Agents
- AI Model Inference including Azure Open AI
- AI Foundry API that works with agents and across models
- Project files (directly upload files and start experimenting)
- Evaluations
- Fine-tuning
- Playgrounds

Prerequisites

Use the following tabs to select the method you plan to use to create a Foundry project:

An Azure subscription. If you don't have an Azure subscription, create a free account.
You must be Owner of the subscription to receive the appropriate access control needed to use the project.

Create a project

To create a Foundry project in Azure AI Foundry, follow these steps:

Go to Azure AI Foundry. If you are in a project, select Azure AI Foundry at the top left of the page to go to the Home page.
In the middle of the page, select Start building. This creates a project and also include steps to start working with a basic agent.
Or select + Create project in the top right corner of the page if you have existing projects. This creates the project alone, without extra steps to start working with an agent.
Enter a name for the project.
Select Create. Or, if you want to customize your settings, follow the steps in the next section.

Advanced options

A Foundry project is created on an AIServices resource. This resource is created for you automatically when you create the project.

To customize the settings for your project, follow these steps:

In the Create a project form, select Advanced options.
Select an existing Resource group you want to use, or leave the default to create a new resource group.

Tip

Especially for getting started we recommend you create a new resource group for your project. The resource group allows you to easily manage the project and all of its resources together.
Select a Location or use the default. The ___location is the region where the hub is hosted. Azure AI services availability differs per region. For example, certain models might not be available in certain regions.
Select Create. You see progress of resource creation and the project is created when the process is complete.

To create a Foundry project:

Install azure-identity: pip install azure-identity azure_mgmt_cognitiveservices. If in a notebook cell, use %pip install azure-identity azure_mgmt_cognitiveservices.

Use the following code to create a Foundry project. This example creates the project in West US:

from azure.identity import DefaultAzureCredential
from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient
import os
import json

sub_id = 'your-sub'
rgp = 'your-resource-group'
resource_name = 'your-resource'
project_name = 'your-project'
___location = 'westus'

client = CognitiveServicesManagementClient(
    credential=DefaultAzureCredential(), 
    subscription_id=sub_id,
    api_version="2025-04-01-preview"
)
# Create resource
resource = client.accounts.begin_create(
    resource_group_name=rgp,
    account_name=resource_name,
    account={
        "___location": ___location,
        "kind": "AIServices",
        "sku": {"name": "S0",},
        "identity": {"type": "SystemAssigned"},
        "properties": {"allowProjectManagement": True}
    }
)
# Create default project
project = client.projects.begin_create(
    resource_group_name=rgp,
    account_name=resource_name,
    project_name=project_name,
    project={
        "___location": ___location,
        "identity": {"type": "SystemAssigned"},
        "properties": {}
    }
)

(Optional) If you have multiple accounts, add the tenant ID of the Microsoft Entra ID you wish to use into the DefaultAzureCredential. Find your tenant ID from the Azure portal under Microsoft Entra ID, External Identities.
```
DefaultAzureCredential(interactive_browser_tenant_id="<TENANT_ID>")
```
(Optional) If you're working on in the Azure Government - US or Azure China 21Vianet regions, specify the region into which you want to authenticate. You can specify the region with DefaultAzureCredential. The following example authenticates to the Azure Government - US region:
```
from azure.identity import AzureAuthorityHosts
DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
```

CLI comannds not currently available for creating a Foundry project.

Create multiple projects on the same resource

Create multiple Foundry projects on an existing AI Services resource, so you can share your environment with your team for collaboration.

Foundry projects as Azure child resources may get assigned their own access controls, but share common settings such as network security, deployments, and Azure tool integration from their parent resource.

Your first project (default project) plays a special role and has access to more features:

Feature	Default Foundry project	Nondefault Foundry project
Model inference	✅	✅
Playgrounds	✅	✅
Agents	✅	✅
Evaluations	✅	✅
Connections	✅	✅
AI Foundry API that works with agents and across models	✅	✅
Project-level isolation of files and outputs	✅	✅
Azure OpenAI with Batch, StoredCompletions, Fine-tuning	✅
Backwards compatible with project-less {account}.cognitiveservices.com data plane API	✅
Content safety	✅

To add a nondefault project to a resource:
Tip

Because you can customize the left pane in the Azure AI Foundry portal, you might see different items than shown in these steps. If you don't see what you're looking for, select ... More at the bottom of the left pane.
1. In Azure AI Foundry, select either the Foundry project or its associated resource.
2. In the left pane, select Management center.
3. In the resource section, select Overview.
4. Select New project and provide a name.
```
new_project_name = 'your-new-project-name'

project = client.projects.begin_create(
  resource_group_name=resource_group_name,
  account_name=foundry_resource_name,
  project_name=new_project_name,
  project={
      "___location": ___location,
      "identity": {
          "type": "SystemAssigned"
      },
      "properties": {}
  }
)
```
CLI comannds not currently available for creating a Foundry project.
If you delete your Foundry resource's default project, the next project created will become the default project.

View project settings

On the project Home page, you can find information about the project.

Name: The name of the project appears in the top left corner. You can rename the project using the edit tool.
Subscription: The subscription that hosts the hub that hosts the project.
Resource group: The resource group that hosts the hub that hosts the project.

    # Get project
    project = client.projects.get(
        resource_group_name=rgp,
        account_name=account_name,
        project_name=project_name
    )
    print(project)

To view settings for the project, use the az cognitiveservices account connection show command. For example:

az cognitiveservices account connection show --name {my_project_name} --resource-group {my_resource_group}

Share via

Create a project for Azure AI Foundry

Prerequisites

Create a project

Customize the hub

View project settings

Access project resources

Related content

Prerequisites

Create a project

Advanced options

Create multiple projects on the same resource

View project settings

Related content

Feedback

Additional resources