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 backwards 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/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 true
   • minimumTlsVersion set to TLS1_2
   • allowBlobPublicAccess set to false
   • allowCrossTenantReplication set to false
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 cannot 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. In the upper right, select Build.
3. In the left pane, select Tools and then Connect a tool in the upper right of the pane.
4. In the Select a tool dialog, select the Catalog tab and find Azure Blob Storage.
5. Select Create.

Configure capability host for Agents (combined resource + 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 above) if not already present.

   Note

   As described in the previous section, select the Catalog tab and look for Azure Blob Storage.

2. Create a resource-level capability host referencing that connection.
3. Create (or open) a project under the resource.
4. Create a project-level capability host referencing the resource-level capability host.
5. Verify 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:

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

{
  "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": "2025-05-01-preview",
  "name": "[concat(parameters('foundryName'), '/agents-host')]",
  "properties": {
    "feature": "agents",
    "connectionId": "[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 CLI or Azure REST API sample to create a resource-level capability host.

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 Storage Blob Data Contributor role on the storage account.
• The storage account has allowSharedKeyAccess set to true.
• 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@2025-05-01-preview' = {
  name: myFoundryName
  location: location
  kind: 'AIServices'
  sku: { name: 'S0' }
  properties: {
    userOwnedStorage: {
      storageResourceId: 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
    resource_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/Language needed).
2. Create storage connection (connections).
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 to ensure the project managed identity has Storage Blob Data Contributor.

Permission errors when accessing storage

If you get authorization or permission errors:

• Confirm that the project managed identity (not the resource identity) has the Storage Blob Data Contributor role on the storage account.
• Verify the storage account has allowSharedKeyAccess set to true.
• 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. The userOwnedStorage field can't be changed 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