Create a hub using the Azure Machine Learning SDK and CLI

2025-06-24

Important

Items marked (preview) in this article are currently in public preview. This preview is provided without a service-level agreement, and we don't recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

In this article, you learn how to create the following Azure AI Foundry resources using the Azure Machine Learning SDK and Azure CLI (with machine learning extension):

An Azure AI Foundry hub
An Azure AI Services connection

Note

A hub is used only for a hub based project. A Foundry project does not use a hub. For more information, see Types of projects.

Prerequisites

An Azure subscription. If you don't have an Azure subscription, create a free account before you begin. Try the free or paid version of Azure AI Foundry today.

Set up your environment

Use the following tabs to select whether you're using the Python SDK or Azure CLI:

Python SDK
Azure CLI

Install packages. (If in a notebook cell, use %pip install instead.)
```
pip install azure-ai-ml
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)
```

If you don't have the Azure CLI and machine learning extension installed, follow the steps in the Install and set up the machine learning extension article.
To authenticate to your Azure subscription from the Azure CLI, use the following command:
```
az login
```
For more information on authenticating, see Authentication methods.

Create the Azure AI Foundry hub and AI Services connection

Use the following examples to create a new hub. Replace example string values with your own values:

Python SDK
Azure CLI

from azure.ai.ml.entities import Hub

my_hub_name = "myexamplehub"
my_location = "East US"
my_display_name = "My Example Hub"

# construct a basic hub
my_hub = Hub(name=my_hub_name, 
            ___location=my_location,
            display_name=my_display_name)

created_hub = ml_client.workspaces.begin_create(my_hub).result()

az ml workspace create --kind hub --resource-group {my_resource_group} --name {my_hub_name}

Create an AI Foundry connection

After creating your own AI Foundry resource or Azure OpenAI resource in the same resource group, you can connect it to your hub. You can also connect Azure AI Search from any resource group in your same subscription.

Python SDK
Azure CLI

Your ml_client connection now needs to include your hub:

Provide your subscription details. For <AML_WORKSPACE_NAME>, use your hub name:

# Enter details of your AML workspace
subscription_id = "<SUBSCRIPTION_ID>"
resource_group = "<RESOURCE_GROUP>"
workspace = "<AML_WORKSPACE_NAME>"

Get a handle to the hub:

# get a handle to the workspace
from azure.ai.ml import MLClient
from azure.identity import DefaultAzureCredential

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

Use ml_client to create the connection to your AI Services. You can find endpoints in Azure portal under Resource management > Keys and endpoints. For an AI Foundry resource, use the AI Services endpoint. For Azure AI Search, use the Url for the endpoint.

from azure.ai.ml.entities import AzureAIServicesConnection

# construct an AI Services connection
my_connection_name = "myaiservivce" # any name you want
aiservices_resource_name = <resource_name> # copy from Azure portal
my_endpoint = "<endpoint>" # copy from Azure portal
my_api_keys = None # leave blank for Authentication type = AAD
my_ai_services_resource_id = f"/subscriptions/{subscription_id}/resourceGroups/{resource_group}/providers/Microsoft.CognitiveServices/accounts/{aiservices_resource_name}"

my_connection = AzureAIServicesConnection(name=my_connection_name,
                                    endpoint=my_endpoint, 
                                    api_key= my_api_keys,
                                    ai_services_resource_id=my_ai_services_resource_id)

# Create the connection
ml_client.connections.create_or_update(my_connection)

az ml connection create --file {connection.yml} --resource-group {my_resource_group} --workspace-name {my_hub_name}

You can use either an API key or credential-less YAML configuration file. For more information on the YAML configuration file, see the AI Services connection YAML schema:

API Key example:

name: myazai_ei
type: azure_ai_services
endpoint: <endpoint for your AI Services>
api_key: XXXXXXXXXXXXXXX
ai_services_resource_id: <fully_qualified_resource_id>

Credential-less

name: myazai_apk
type: azure_ai_services
endpoint: <endpoint for your AI Services>
ai_services_resource_id: <fully_qualified_resource_id>

The <fully_qualified_resource_id> is the resource ID of your AI Services resource. It is in the format /subscriptions/{subscription_id}/resourceGroups/{resource_group}/providers/Microsoft.CognitiveServices/accounts/{aiservices_resource_name}.

Create an Azure AI Foundry hub using existing dependency resources

You can also create a hub using existing resources such as Azure Storage and Azure Key Vault. In the following examples, replace the example string values with your own values:

Tip

You can retrieve the resource ID of the storage account and key vault from the Azure portal by going to the resource's overview and selecting JSON view. The resource ID is located in the id field. You can also use the Azure CLI to retrieve the resource ID. For example, az storage account show --name {my_storage_account_name} --query "id" and az keyvault show --name {my_key_vault_name} --query "id".

Python SDK
Azure CLI

from azure.ai.ml.entities import Hub

my_hub_name = "myexamplehub"
my_location = "East US"
my_display_name = "My Example Hub"
my_resource_group = "myresourcegroupname"
my_storage_account_id = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myresourcegroupname/providers/Microsoft.Storage/storageAccounts/mystorageaccountname"
my_key_vault_id = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myresourcegroupname/providers/Microsoft.KeyVault/vaults/mykeyvaultname"

# construct a basic hub
my_hub = Hub(name=my_hub_name, 
            ___location=my_location,
            display_name=my_display_name,
            resource_group=my_resource_group,
            storage_account_id=my_storage_account_id,
            key_vault_id=my_key_vault_id)

created_hub = ml_client.workspaces.begin_create(my_hub).result()

az ml workspace create --kind hub --resource-group {my_resource_group} --name {my_hub_name} --___location {hub-region} --storage-account {my_storage_account_id} --key-vault {my_key_vault_id}

Share via