Create a project for Microsoft Foundry

Note

This document refers to the Microsoft Foundry (classic) portal.

Note

This document refers to the Microsoft Foundry (new) portal.

This article describes how to create a Foundry project in Microsoft Foundry. Projects let you organize your work—such as agents, evaluations, and files—as you build stateful apps and explore new ideas.

An Foundry project is managed under a Microsoft Foundry resource. It's a container for access management, data upload and integration, and monitoring. This lets you keep your work separated between use cases without needing to create extra Azure resources.
This project type gives you access to the latest generative AI features in Foundry, including:
- Agents
- Foundry SDK and API to build agents and switch easily between models
- Models sold directly by Azure - Azure OpenAI, Mistral, xAI, DeepSeek, etc.
- Partner & Community Models sold through Marketplace - Stability, Cohere, etc.
- Content understanding
- Evaluations
- Fine-tuning
- OpenAI SDK and API including Batch and Stored Completions
- AI Services
Do you need access to open-source models or PromptFlow? Create a hub project type instead.
See Types of projects for more information on the different project types.

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 requirements.

Prerequisites

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

An Azure account with an active subscription. If you don't have one, create a free Azure account, which includes a free trial subscription.

You must be Owner of the subscription to have the appropriate access control necessary to create the Foundry resource that's the parent of the project. If you don't have this access, have your administrator create a Foundry resource for you to use. Then skip to Create multiple projects on the same resource to create your project.

You must be Owner of the subscription to have the appropriate access control necessary to create the Foundry resource that's the parent of the project. If you don't have this access, have your administrator create a project for you.

An Azure account with an active subscription. If you don't have one, create a free Azure account, which includes a free trial subscription.
You must be Owner of the subscription to get the appropriate access control needed to use the project.
Set up your development environment
Run az login or az login --use-device-code in your environment before running code.

Complete these steps to start your Python script:
1. Install packages: pip install azure-identity azure-mgmt-cognitiveservices~=13.7.0b1. If you're in a notebook cell, use %pip install instead.
2. Use pip show azure-mgmt-cognitiveservices to check that your version is 13.7 or greater.
3. Start your script with the following code to create the client connection and variables used throughout this article. This example creates the project in East US:
```
from azure.identity import DefaultAzureCredential
from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient

subscription_id = 'your-subscription-id'
resource_group_name = 'your-resource-group-name'
foundry_resource_name = 'your-foundry-resource-name'
foundry_project_name = 'your-foundry-project-name'
location = 'eastus'

client = CognitiveServicesManagementClient(
    credential=DefaultAzureCredential(), 
    subscription_id=subscription_id,
    api_version="2025-04-01-preview"
)
```
4. (Optional) If you have multiple accounts, add the tenant ID of the Microsoft Entra ID you want to use into the DefaultAzureCredential.
```
DefaultAzureCredential(interactive_browser_tenant_id="<TENANT_ID>")
```
5. (Optional) If you're working in the Azure Government - US or Azure operated by 21Vianet regions, specify the region you want to authenticate to. This example authenticates to the Azure Government - US region:
```
from azure.identity import AzureAuthorityHosts
DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
```

Complete these steps to start your Python script:

Install packages: pip install azure-identity azure-mgmt-cognitiveservices~=13.7.0b1. If you're in a notebook cell, use %pip install instead.
Use pip show azure-mgmt-cognitiveservices to check that your version is 13.7 or greater.

Start your script with the following code to create the client connection and variables used throughout this article. This example creates the project in East US:

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

subscription_id = 'your-subscription-id'
resource_group_name = 'your-resource-group-name'
foundry_resource_name = 'your-foundry-resource-name'
foundry_project_name = 'your-foundry-project-name'
location = 'eastus'

client = CognitiveServicesManagementClient(
    credential=DefaultAzureCredential(), 
    subscription_id=subscription_id,
    api_version="2025-04-01-preview"
)

(Optional) If you have multiple accounts, add the tenant ID of the Microsoft Entra ID you want to use into the DefaultAzureCredential.
```
DefaultAzureCredential(interactive_browser_tenant_id="<TENANT_ID>")
```

An Azure account with an active subscription. If you don't have one, create a free Azure account, which includes a free trial subscription.
You must be Owner of the subscription to receive the appropriate access control needed to use the project.
Install the Azure CLI

Set default values for subscription and resource group.

  # Set your default subscription
  az account set --subscription "{subscription-name}"

  # Set default resource group
  az config set defaults.group={resource-group-name}

Create a Foundry project

These steps provide a way to create a new Azure resource with basic, default settings.

To create a Foundry project, follow these steps:

Sign in to Microsoft Foundry. Make sure the New Foundry toggle is off. These steps refer to Foundry (classic).

Sign in to Microsoft Foundry. Make sure the New Foundry toggle is on. These steps refer to Foundry (new).
What you do next depends on where you are:
- If you don't have any existing projects: Follow the steps in Quickstart: Get started with Microsoft Foundry to create your first project.
- If you're in a project: Select the project breadcrumb, then select Create new resource.
- If you're not in a project: Select Create new in the top right to create a new Foundry project
Select Foundry resource, and then select Next.
Provide a name for your project and select Create. Or see the next section for advanced options.

These steps provide a way to create a new Azure resource with basic, defaulted, settings.

To create a Foundry project, follow these steps:

Sign in to Microsoft Foundry. Make sure the New Foundry toggle is off. These steps refer to Foundry (classic).

Sign in to Microsoft Foundry. Make sure the New Foundry toggle is on. These steps refer to Foundry (new).
The project you're working on appears in the upper-left corner.
To create a new project, select the project name, and then select Create new project.
Give your project a name and select Create project. Or see next section for advanced options.

Advanced options

A Foundry project is created on an Foundry resource. This resource is created for you automatically when you create the project. 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 lets you easily manage the project and all its resources together.
Select a Location or use the default. The location is the region where the resources in the project are hosted.
Select Create. You see progress of resource creation. The project is created when the process is complete.

To create a Foundry project:

Add this code to create a Foundry project by using the variables and client connection from the Prerequisites.

# Create resource
resource = client.accounts.begin_create(
    resource_group_name=resource_group_name,
    account_name=foundry_resource_name,
    account={
        "location": location,
        "kind": "AIServices",
        "sku": {"name": "S0",},
        "identity": {"type": "SystemAssigned"},
        "properties": {
            "allowProjectManagement": True,
            "customSubDomainName": foundry_resource_name
        }
    }
)

# Wait for the resource creation to complete
resource_result = resource.result()

# Create default project
project = client.projects.begin_create(
    resource_group_name=resource_group_name,
    account_name=foundry_resource_name,
    project_name=foundry_project_name,
    project={
        "location": location,
        "identity": {
            "type": "SystemAssigned"
        },
        "properties": {}
    }
)

Authenticate to your Azure subscription from the Azure CLI with the following command:
```
az login
```
For more information on authenticating, see Authentication methods.

Create a resource group, for example in East US:

az group create --name {my_resource_group} --location eastus

Create a Foundry resource

az cognitiveservices account create \
--name {your-foundry-resource-name} \
--kind AIServices \
--location eastus \
--sku s0 \
--allow-project-management

Create a project:

az cognitiveservices account project create \
--name {your-foundry-resource-name} \
--project-name {your-project-name} \
--location eastus

Create multiple projects on the same resource

Create multiple Foundry projects on an existing Foundry resource to enable team collaboration and shared resource access including security, deployments, and connected tools. This setup is ideal in restricted Azure subscriptions where developers need self-serve exploration ability within the setup of a pre-configured environment.

Diagram shows how a team could share resource access with multiple projects on a Foundry resource.

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.

While not all Foundry capabilities support organizing work in projects yet, your resource's first "default" project is more powerful. You can identify it by the tag "default" in UX experiences and the resource property "is_default" when using code options.

Feature	Default project	Other projects
Model inference	✅	✅
Playgrounds	✅	✅
Agents	✅	✅
Evaluations	✅	✅
Tracing	✅	✅
Datasets	✅	✅
Indexes	✅	✅
Foundry SDK and API	✅	✅
Content understanding	✅	✅
OpenAI SDK and API	✅	Responses, Files, Conversations
OpenAI Batch, Fine-tuning, Stored completions	✅	-
Language fine-tuning	✅	✅
Speech fine-tuning	✅	-
Connections	✅	✅

To add a project to a Foundry resource:
Tip

Because you can customize the left pane in the Microsoft 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. Sign in to Microsoft Foundry. Make sure the New Foundry toggle is off. These steps refer to Foundry (classic).
  
  Sign in to Microsoft Foundry. Make sure the New Foundry toggle is on. These steps refer to Foundry (new).
2. Select either the Foundry project or its associated resource.
3. In the left pane, select Management center.
4. In the resource section, select Overview.
5. Select New project and provide a name.
Adding a second project is not currently supported in Foundry (new).
Add this code to your script to create a new project on your existing resource:
```
# Create additional project
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": {}
    }
)
```
Use your existing values for {foundry_resource_name} to add another project to the resource:
```
 az cognitiveservices account project create \
 --name {foundry_resource_name} \
 --project-name {my_project_name} \
 --location {location}
```
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 find information about the project.

Name: The name of the project appears in the top left corner.
Subscription: The subscription that hosts the hub that hosts the project.
Resource group: The resource group that hosts the hub that hosts the project.

On the Home page, you see the project endpoint and API key for the project. You don't need the API key if you use Microsoft Entra ID authentication.

# Get project
project = client.projects.get(
    resource_group_name=resource_group_name,
    account_name=foundry_resource_name,
    project_name=foundry_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>

Delete projects

Sign in to Microsoft Foundry. Make sure the New Foundry toggle is off. These steps refer to Foundry (classic).

Sign in to Microsoft Foundry. Make sure the New Foundry toggle is on. These steps refer to Foundry (new).
Open your project.
Select Management center.
Under Resource, select Overview.
Select any projects you no longer want to keep.
Select Delete project.

To delete the Foundry resource and all its projects:

In the Management center, select the resource name from the Overview section to go to the Azure portal.
In the Azure portal, select Delete to delete the resource and all its associated projects.

Sign in to Microsoft Foundry. Make sure the New Foundry toggle is off. These steps refer to Foundry (classic).

Sign in to Microsoft Foundry. Make sure the New Foundry toggle is on. These steps refer to Foundry (new).
In the upper-right navigation, select Operate.
In the left pane, select Admin.
Select your project.
In the upper right, select the trash can icon to delete the project.

This code uses the variables and client connection from the Prerequisites. First create the client connection:

client.projects.begin_delete(
    resource_group_name, foundry_resource_name, foundry_project_name
)

Delete a Foundry resource and all of its projects:

# Delete projects
projects = client.projects.list(resource_group_name, foundry_resource_name)

for project in projects: 
    print("Deleting project:", project.name)
    client.projects.begin_delete(resource_group_name, foundry_resource_name,
        project_name=project.name.split('/')[-1]
    ).wait()

# Delete resource
print("Deleting resource:", foundry_resource_name)
client.accounts.begin_delete(resource_group_name, foundry_resource_name).wait()

Run the following command:

az cognitiveservices account project delete \
--name {foundry_resource_name} \
--project-name {my_project_name}

Feedback

Was this page helpful?

Last updated on 2025-11-18