Create a project for Microsoft Foundry

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.

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

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

• Access to a role that allows you to create a Foundry resource, such as Azure Account AI Owner or Azure AI Owner on the subscription or resource group. For more information about permissions, see Role-based access control for Microsoft Foundry.

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

  Foundry portal

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

  Python SDK

  • Set up your development environment

  • Run az login or az login --use-device-code in your environment before running code.

  • Quick validation: Before creating a project, verify your SDK and authentication are working by testing the client:

    from azure.identity import DefaultAzureCredential
    from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient
    
    # Test authentication by instantiating the client
    credential = DefaultAzureCredential()
    subscription_id = "<your-subscription-id>"  # Replace with your subscription ID
    client = CognitiveServicesManagementClient(credential, subscription_id)
    print("✓ Authentication successful! Ready to create a project.")
    

  • 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>")
       

  Azure CLI

  • Install the Azure CLI.

  • Set default values for subscription.

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

Create a Foundry project

Foundry portal

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

To create a Foundry project, follow these steps:

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

   

2. The project you're working on appears in the upper-left corner.

3. To create a new project, select the project name, and then select Create new project.

4. Give your project a name and select Create project. Or see next section for advanced options.

Advanced options

1. You create a Foundry project on a Foundry resource. The portal automatically creates this resource when you create the project. Select an existing Resource group to use, or leave the default to create a new resource group.

   Tip

   Especially for getting started, create a new resource group for your project. The resource group makes it easy to manage the project and all its resources together.

2. Select a Location or use the default. The location is the region where the project resources are hosted.

3. Select Create. You see the progress of resource creation. The project is created when the process is complete.

Python SDK

To create a Foundry project:

• Add the following 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": {}
      }
  )
  

  References: CognitiveServicesManagementClient.

Azure CLI

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
   

2. Create the Foundry resource. 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 \
      --allow-project-management
   

   The --allow-project-management flag enables project creation within this resource.

3. Create a custom subdomain for the resource. The custom domain name must be globally unique. If my-foundry-resource is taken, try a more unique name.

   az cognitiveservices account update \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --custom-domain my-foundry-resource
   

4. Create the 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
   

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
   

   The output displays the project properties, including its resource ID.

Reference: az cognitiveservices account

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 preconfigured environment.

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:

  Foundry portal

  The Foundry (new) portal displays only the default project for each Foundry resource. You can't create multiple projects, or view any of the nondefault projects in the Foundry (new) portal.

  Python SDK

  While this code can add additional projects to a resource, you won't be able to view them in the Foundry (new) portal. Only the default project for a resource is available in the Foundry (new) portal.
  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": {}
      }
  )
  

  Azure CLI

  While this code can add additional projects to a resource, you won't be able to view them in the Foundry (new) portal. Only the default project for a resource is available in the Foundry (new) portal. To add a new project to my-foundry-resource:

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

• If you delete your Foundry resource's default project, the next project created will become the default project.

View project settings

Foundry portal

On the Home project 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.

Python SDK

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

References: CognitiveServicesManagementClient.

Azure CLI

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

az cognitiveservices account connection show \
--name my-foundry-project \
--resource-group my-foundry-rg

Delete projects

Foundry portal

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

Python SDK

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
)

References: CognitiveServicesManagementClient.

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()

References: CognitiveServicesManagementClient.

Azure CLI

Run the following command:

az cognitiveservices account project delete \
--name my-foundry-rg \
--project-name my-foundry-project

References: az cognitiveservices account project delete.

Important

Use with caution. You can't recover a project after it's deleted.

Related content

• Microsoft Foundry Quickstart
• What is Foundry?