Connect to your own storage

Microsoft Foundry brings Agents, Azure OpenAI, Speech, and Language services together under one unified resource type. Bring-your-own-storage (BYOS) lets you route data produced by these capabilities to an Azure Storage account that you own and govern. The configuration patterns align with (and provide backward compatibility to) earlier standalone Speech and Language resource types.

This article shows you how to connect your storage to Foundry by using two overarching approaches:

• Connections: recommended baseline for most features. Connections provide the shared data pointer.
• Capability hosts: optionally override or explicitly bind a specific feature (for example, Agents standard setup) to one connection among several.
• userOwnedStorage field: a resource-level binding used only by Speech and Language.

Prerequisites

Before connecting your storage, ensure you have:

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

1. An Azure Storage account in the same subscription (Blob Storage supported) with the following configuration:

   • allowSharedKeyAccess set to false. Foundry uses identity-based (Microsoft Entra) access with the project managed identity and Azure RBAC, so shared key access isn't required.
   • minimumTlsVersion set to TLS1_2
   • allowBlobPublicAccess set to false
   • allowCrossTenantReplication set to false (recommended hardening)

2. Contributor or Owner permissions on both the Foundry resource and the storage account.

3. Clarity on which features you plan to use (Agents, Evaluations, Datasets, Content Understanding, Speech, Language).

4. (Optional) A plan for customer-managed keys (CMK) encryption on the storage account.

Understand storage connection approaches

Foundry connections

Foundry connections act as shared data pointers across Foundry capabilities (agents, evaluations, datasets, content understanding). Each connection wraps the target storage endpoint plus authentication so users with project access can use the data without direct storage account permissions. Use connections as the default pattern; create a capability host only when you need to explicitly bind (override) a single feature to one connection among several.

Capability hosts

Capability hosts bind specific features to designated connections when multiple storage connections exist. They define which storage connection a particular feature uses. Use capability hosts most commonly for agents standard setup. If you don't create capability hosts for agents, Foundry uses Microsoft-managed storage for that feature.

See Capability hosts for conceptual details.

userOwnedStorage (resource storage binding)

The userOwnedStorage field enables customer-managed storage for Speech and Language capabilities. Set this field during resource creation at the resource level, so all projects within the resource share the same storage account.

Speech and Language capabilities share the storage account but use different containers within it. The setting applies at the resource level and can't be changed after creation without recreating the resource.

If strict data isolation is required between Speech and Language scenarios, create separate Foundry resources with different storage accounts.

Create a storage connection

1. Sign in to Microsoft Foundry. Make sure the New Foundry toggle is on. These steps refer to Foundry (new).
2. Select Manage in the upper-right navigation.
3. Select Project details in the left pane.
4. Select the Connected resources tab, and then select Add connection.
5. In the list of available services, select Azure Storage.
6. Browse for and select your Azure Storage account, choose an Authentication type, and then select Add connection.

Configure capability host for agents (combined resource and project steps)

You create two capability hosts - one at the resource level and one at the project level - each referencing the same connection chain so agents route to your storage.

1. Create a resource-level connection (as described earlier) if you don't already have one.

   Note

   As described in the previous section, select Manage > Resource details > Connected resources > Add connection and choose Azure Storage.

2. Create a resource-level capability host that references that connection.
3. Create or open a project under the resource.
4. Create a project-level capability host that references the resource-level capability host.
5. Verify that agents data now writes to the bound storage account.

Example (REST API)

Use the Capability Hosts - Create Or Update REST API to create a capability host. Replace <connection-arm-resource-id> with the full ARM resource ID of your blob storage connection.

PUT https://management.azure.com/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<foundry-resource>/capabilityHosts/agents-host?api-version=2026-07-01

{
  "properties": {
    "capabilityHostKind": "Agents",
    "storageConnections": [
      "<connection-arm-resource-id>"
    ]
  }
}

Replace <connection-arm-resource-id> with the full ARM resource ID of your blob storage connection.

ARM template snippet

{
  "type": "Microsoft.CognitiveServices/accounts/capabilityHosts",
  "apiVersion": "2026-07-01",
  "name": "[concat(parameters('foundryName'), '/agents-host')]",
  "properties": {
    "capabilityHostKind": "Agents",
    "storageConnections": [
      "[resourceId('Microsoft.CognitiveServices/accounts/connections', parameters('foundryName'), 'myblobconnection')]"
    ]
  }
}

Configure capability hosts for agents

Set up capability hosts to use your storage connection for agents standard setup. You need to configure capability hosts at both the resource and project levels.

Create resource-level capability host

1. Use the Azure REST API through az rest or Invoke-AzRestMethod to create a resource-level capability host. Dedicated Azure CLI and PowerShell cmdlets aren't available yet.

2. Reference your previously created storage connection in the capability host configuration.

3. Set the capability type to support agents.

Create project-level capability host

After creating your Foundry project:

1. Create a project-level capability host that references the resource-level capability host.

2. Configure the capability host to enable agents functionality.

3. Verify the capability host is properly linked to your storage connection as demonstrated in this code sample for Standard agent setup.

Your agents standard setup now uses your own storage account instead of Microsoft-managed storage.

Verify your storage configuration

After you configure storage connections and capability hosts, confirm that data routes to your storage account:

1. Sign in to the Azure portal and open your storage account.
2. Navigate to Containers under Data storage.
3. Create a test agent in your Foundry project and run a simple interaction.
4. Return to the storage account and refresh the Containers view.
5. Verify that new containers or blobs appear in your storage account.

If data doesn't appear in your storage account, check the following:

• Both resource-level and project-level capability hosts exist and reference the correct connection.
• The project managed identity has the required storage roles: Storage Account Contributor on the storage account, Storage Blob Data Contributor on the <workspaceId>-azureml-blobstore container, and Storage Blob Data Owner on the <workspaceId>-agents-blobstore container. See Standard agent setup for the complete role list.
• Network settings on the storage account allow access from Microsoft Foundry.

Set userOwnedStorage for Speech and Language

Set the field during resource creation—via Bicep, ARM, Terraform, CLI, or PowerShell.

Bicep example

resource foundry 'Microsoft.CognitiveServices/accounts@2026-07-01' = {
  name: myFoundryName
  location: location
  kind: 'AIServices'
  sku: { name: 'S0' }
  properties: {
    userOwnedStorage: [
      {
        resourceId: storageAccount.id
      }
    ]
  }
}

Terraform snippet

Refer to Terraform cognitive_account.

resource "azurerm_cognitive_account" "foundry" {
  name                = var.foundry_name
  location            = var.location
  resource_group_name = azurerm_resource_group.rg.name
  kind                = "AIServices"
  sku_name            = "S0"

  storage { # userOwnedStorage equivalent
    storage_account_id = azurerm_storage_account.speechlang.id
  }
}

Role assignment

Create the role assignment on the Azure Storage account for the Foundry project managed identity. Assign the Storage Blob Data Contributor role so the project identity can read and write blobs in your storage account.

az role assignment create \
  --assignee <project-managed-identity-principal-id> \
  --role "Storage Blob Data Contributor" \
  --scope /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Storage/storageAccounts/<storage-account-name>

End-to-end customer-managed storage checklist

1. Create resource with userOwnedStorage (if Speech or Language features are needed).
2. Create storage connection.
3. Create resource-level capability host (Agents override when needed).
4. Create project-level capability host (Agents override at project).
5. Bind Content Understanding to the storage connection.

After these steps, all features (Agents, Evaluations, Datasets, Content Understanding, Speech, Language) route to customer-managed storage.

Troubleshooting

Agents still use Microsoft-managed storage

If agents continue to write data to Microsoft-managed storage instead of your storage account:

• Verify that both resource-level and project-level capability hosts exist. Both levels are required for the binding chain to work.
• Check that each capability host references the correct connection ID.
• Confirm the storage connection points to the expected storage account.
• Review role assignments on the storage account. Standard agent setup requires Storage Account Contributor on the account, Storage Blob Data Contributor on the <workspaceId>-azureml-blobstore container, and Storage Blob Data Owner on the <workspaceId>-agents-blobstore container.

Permission errors when accessing storage

If you get authorization or permission errors:

• Confirm that the project managed identity (not the resource identity) has the required storage roles on the storage account and containers.
• Confirm the storage account permits the authentication method your connection uses.
• Check that network rules on the storage account allow traffic from Microsoft Foundry. If the storage account uses a firewall, add the appropriate exceptions.

Speech or Language stops working after storage changes

If Speech or Language capabilities stop functioning after changes to your storage account:

• Don't delete or move (change the resource ID of) the storage account bound by userOwnedStorage.
• If the storage account was deleted, attempt recovery first: Recover a storage account.
• If recovery isn't possible, recreate the Foundry resource with a new storage account. You can't change the userOwnedStorage field after resource creation.

Related content

• Capability hosts for Agents
• Understanding Agents standard setup
• Add connections to your project
• Recover a storage account.
• Azure Storage documentation.
• Infrastructure setup samples.
• Connect storage for Speech/Language.