Introduction
An AI agent can deliver an impressive demo—and still face a production roadblock when enterprise data must stay in organization-controlled storage behind private endpoints. Moving to production means deciding not just what an agent can do, but where its data lives and how it reaches private resources.
Microsoft Foundry brings these decisions together through outbound virtual network injection, bring-your-own (BYO) Azure resources, and Capability Hosts. This post connects the dots between them: establishing private connectivity, choosing your backing resources, and configuring each project to use them—so data ownership and network isolation become part of your architecture, not last-minute deployment hurdles.
Connecting agents to private resources
By default, agents use public outbound connectivity to access external services and Azure resources. If an agent must connect to resources that are accessible only through a private network, you can configure outbound virtual network injection.With outbound VNet injection, the Foundry Agent Service runtime is connected to a dedicated subnet delegated to Microsoft.App/environments. This delegation allows Foundry to deploy and manage the networking required for the agent runtime.The same VNet also contains a separate private-endpoint subnet that hosts private endpoints for resources such as Azure Storage, Azure Cosmos DB, Azure AI Search, and the Foundry account. Agent traffic flows from the delegated subnet through the VNet to these private endpoints, without traversing the public internet.
Note : Private endpoints can be in the same VNet or in a reachable peered VNet.
Foundry Agent Service
Foundry Agent Service is a managed platform for building, deploying, and scaling AI agents. By default, Foundry Agent Service manages storage for files, conversations, and vector stores. If your organization requires full data ownership, customer-managed keys (CMK), or network isolation i.e. enforce enterprise security and compliance policies, you can connect or use your own Azure resources instead.
- Azure Cosmos DB for NoSQL — stores conversations, agent state, and related metadata.
- Azure Storage — stores uploaded files and intermediate file-processing data.
- Azure AI Search — stores and searches vector indexes used for retrieval.
Capability Host
Capability hosts are sub-resources that you configure at both the Microsoft Foundry account and Foundry project scopes. They tell Foundry Agent Service where to store and process agent data, including Conversation History, File uploads and Vector stores. This is like a configuration mapping between Agent Service and its required backing resources.
Note: If you don't create capability hosts, Agent Service automatically uses Microsoft-managed Azure resources for history, file uploads and vector stores.
Account Capability Host : enables the Agent Service capability at the Foundry account level and associates agent service with the delegated subnet .
In a private-network deployment using network injection, the account capability host can be created automatically as part of provisioning (refer Template 15 deployment).
Project Capability Host: tells Agent Service exactly which resources a particular project should use. Even if the account capability host references connections, Agent Service doesn't use them for a project unless those connections are explicitly referenced in a project capability host.
| Capability-host property | Purpose | Azure resource |
|---|---|---|
| storageConnections | Uploaded files and intermediate data | Azure Storage |
| threadStorageConnections | Conversations, agent state, and metadata | Azure Cosmos DB |
| vectorStoreConnections | Vector indexes and retrieval data | Azure AI Search |
In summary the account-level Capability Host enables Foundry Agent Service and associates it with the delegated subnet to enable access to private resources/connections referenced by the projects. The project-level Capability Host defines where the project’s agent data is stored by referencing its Azure Storage, Azure Cosmos DB, and Azure AI Search connections.
Deploying a Foundry Account with ARM Json Template
Template 15 – Private Network Standard Agent Setup, which deploys Foundry Agent Service with BYO data resources and Vnet injection. Below link takes you to custom deployment in Azure Portal.
Follow below instructions to run the deployment and once its completed, we will have a Foundry account and the first project created with both Account and project level Capability Hosts.
Prerequisites :
- Virtual network with 2 subnets created one each for Private endpoints and another delegated subnet
- Cosmos, Storage and Search Services created
Custom Deployment Parameters:
Successful deployment :
Verifying the Account and Project Capability Hosts:
Account Capability Host:
az rest --method get --url "https://management.azure.com/subscriptions/<subscriptionid>/resourceGroups/<resourcegroupname>/providers/Microsoft.CognitiveServices/accounts/<foundryaccountname>/capabilityHosts?api-version=2025-06-01"
Output:
{
"value": [
{
"id": "/subscriptions/<subscriptionid>/resourceGroups/<resourcegroupname>/providers/Microsoft.CognitiveServices/accounts/<foundryaccountname>/capabilityHosts/<accountlevelcapabilityhostname>",
"name": "<accountlevelcapabilityhostname>",
"properties": {
"aiServicesConnections": null,
"capabilityHostKind": "Agents",
"customerSubnet": "/subscriptions/<subscriptionid>/resourceGroups/<resourcegroupname>/providers/Microsoft.Network/virtualNetworks/<vnetname>/subnets/<delegatedsubnetname>",
"description": null,
"properties": null,
"provisioningState": "Succeeded",
"storageConnections": null,
"tags": null,
"threadStorageConnections": null,
"vectorStoreConnections": null
},
"systemData": {
"createdAt": "2026-11-08T18:21:21.0327639+00:00",
"lastModifiedAt": "2026-11-08T18:25:17.3252644+00:00"
},
"type": "Microsoft.CognitiveServices/accounts/capabilityHosts"
}
]
}
Project Capability Host
az rest --method get --url "https://management.azure.com/subscriptions/<subscriptionid>/resourceGroups/<resourcegroupname>/providers/Microsoft.CognitiveServices/accounts/<foundryaccountname>/projects/<projectname>/capabilityHosts?api-version=2025-06-01"
Output:
{
"value": [
{
"id": "/subscriptions/<subscriptionid>/resourceGroups/<resourcegroupname>/providers/Microsoft.CognitiveServices/accounts/<foundryaccountname>/projects/<projectname>/capabilityHosts/<projectlevelcapabilityhostname>",
"name": "<projectlevelcapabilityhostname>",
"properties": {
"aiServicesConnections": null,
"capabilityHostKind": "Agents",
"customerSubnet": null,
"description": null,
"properties": null,
"provisioningState": "Succeeded",
"storageConnections": [
"<storageconnectionname>"
],
"tags": null,
"threadStorageConnections": [
"cosmosconnectionname"
],
"vectorStoreConnections": [
"searchconnectionname"
]
},
"systemData": {
"createdAt": "2026-11-08T18:34:34.6044253+00:00",
"lastModifiedAt": "2026-11-08T18:37:12.8222622+00:00"
},
"type": "Microsoft.CognitiveServices/accounts/projects/capabilityHosts"
}
]
}
Creating account/project level capability hosts on a Foundry Account with VNET injection.
This is mainly required to understand the flow how capability host provisioning works and troubleshoot any existing project.
Sign in and set variables
$tenantId = '<tenantid>'
$subscriptionId = '<subscriptionId>'
$resourceGroup = '<resourceGroup>'
$accountName = '<FoundryAccountName>'
$projectName = '<FoundryProjectName>'
$storageAccountName = '<StorageAccountName>'
$cosmosAccountName = '<CosmosAccountName>'
$searchServiceName = '<AzureAISearchServiceName>'
$accountHostName = 'account-agents-host' # new host name: letters, digits, '-' or '_' only (no '@')
$projectHostName = 'project-agents-host'
$storageConnectionName = 'hub-storage-connection'
$searchConnectionName = 'hub-search-connection'
$cosmosConnectionName = 'hub-cosmos-connection'
$agentSubnetId = '<ResourceIdOfDelegatedSubnet>'
$apiVersion = '2025-06-01'
$accountResourceId = "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.CognitiveServices/accounts/$accountName"
$accountUri = "https://management.azure.com$accountResourceId"
$projectUri = "$accountUri/projects/$projectName"
# Stop early if any variable is blank (for example, if this block was not run in the current session)
$required = 'accountName','projectName','storageAccountName','cosmosAccountName','searchServiceName','accountHostName','projectHostName','storageConnectionName','searchConnectionName','cosmosConnectionName','agentSubnetId'
$missing = $required | Where-Object { [string]::IsNullOrWhiteSpace((Get-Variable -Name $_ -ValueOnly -ErrorAction SilentlyContinue)) }
if ($missing) { throw "Variables not set: $($missing -join ', ')" }
az login --tenant $tenantId
if ($LASTEXITCODE -ne 0) { throw 'Azure login failed.' }
az account set --subscription $subscriptionId
if ($LASTEXITCODE -ne 0) { throw 'Could not select the Azure subscription.' }
az account show --query '{subscription:id,tenant:tenantId}' --output json
if ($LASTEXITCODE -ne 0) { throw 'Could not verify the Azure context.' }
Inspect the existing account connections
az rest --method get --uri "$accountUri/connections/$($cosmosConnectionName)?api-version=$apiVersion"
az rest --method get --uri "$accountUri/connections/$($searchConnectionName)?api-version=$apiVersion"
az rest --method get --uri "$accountUri/connections/$($storageConnectionName)?api-version=$apiVersion"
Creating Connections
Run below function to create connections for Search, Storage and Cosmos
function Set-FoundryConnection {
param(
[Parameter(Mandatory)] [string] $Name,
[Parameter(Mandatory)] [string] $Category,
[Parameter(Mandatory)] [string] $Target,
[Parameter(Mandatory)] [string] $ResourceId
)
$body = @{
properties = @{
category = $Category
target = $Target
authType = 'AAD'
metadata = @{ ResourceId = $ResourceId }
}
} | ConvertTo-Json -Depth 5
$file = [IO.Path]::GetTempFileName()
try {
[IO.File]::WriteAllText($file, $body, [Text.UTF8Encoding]::new($false))
az rest --method put --uri "$accountUri/connections/$($Name)?api-version=$apiVersion" --headers 'Content-Type=application/json' --body "@$file"
if ($LASTEXITCODE -ne 0) { throw "Connection PUT failed: $Name (az exit code $LASTEXITCODE)." }
}
finally {
Remove-Item -LiteralPath $file
}
}
$backingResourceId = "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup"
Set-FoundryConnection -Name $storageConnectionName -Category 'AzureStorageAccount' -Target "https://$storageAccountName.blob.core.windows.net/" -ResourceId "$backingResourceId/providers/Microsoft.Storage/storageAccounts/$storageAccountName"
Set-FoundryConnection -Name $searchConnectionName -Category 'CognitiveSearch' -Target "https://$searchServiceName.search.windows.net" -ResourceId "$backingResourceId/providers/Microsoft.Search/searchServices/$searchServiceName"
Set-FoundryConnection -Name $cosmosConnectionName -Category 'CosmosDb' -Target "https://$cosmosAccountName.documents.azure.com:443/" -ResourceId "$backingResourceId/providers/Microsoft.DocumentDB/databaseAccounts/$cosmosAccountName"
Grant managed identity RBAC permissions
Before capability host provisioning can succeed, the project's system-assigned managed identity (or user assigned managed identity) must be granted the required access to Storage, AI Search, and Cosmos DB. Run below to assign the required roles.
# Step 1: Set the active context and get the managed identity object ID
Set-AzContext -SubscriptionId $subscriptionId -TenantId $tenantId -ErrorAction Stop
$managedIdentityObjectId = az rest --method get --uri "$($projectUri)?api-version=$apiVersion" --query identity.principalId --output tsv
if ([string]::IsNullOrWhiteSpace($managedIdentityObjectId)) { throw 'Could not read the project managed identity principal ID.' }
$managedIdentityObjectId
# Step 2: Grant Storage blob data access
New-AzRoleAssignment -ObjectId $managedIdentityObjectId -RoleDefinitionName 'Storage Blob Data Contributor' -Scope "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.Storage/storageAccounts/$storageAccountName"
# Step 3: Grant AI Search roles
"Search Index Data Contributor", "Search Service Contributor" | ForEach-Object { New-AzRoleAssignment -ObjectId $managedIdentityObjectId -RoleDefinitionName $_ -Scope "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.Search/searchServices/$searchServiceName" }
#Step 4: Grant Cosmos DB roles
New-AzRoleAssignment -ObjectId $managedIdentityObjectId -RoleDefinitionName 'Cosmos DB Operator' -Scope "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/databaseAccounts/$cosmosAccountName"
New-AzCosmosDBSqlRoleAssignment -ResourceGroupName $resourceGroup -AccountName $cosmosAccountName -RoleDefinitionId '00000000-0000-0000-0000-000000000002' -PrincipalId $managedIdentityObjectId -Scope '/'
#Step 5. Check the account-level capability host
az rest --method get --uri "$accountUri/capabilityHosts?api-version=$apiVersion" --query 'value[].{name:name,kind:properties.capabilityHostKind,state:properties.provisioningState}' --output table
if ($LASTEXITCODE -ne 0) { throw 'Could not list account capability hosts.' }
Account-level capability host
Check if account level capability host exists and is in failed state. If yes, delete and create using below code
# The project capability host requires an account-level host. Check whether one already exists before creating anything:
az rest --method get --uri "$accountUri/capabilityHosts?api-version=$apiVersion" --query 'value[].{name:name,kind:properties.capabilityHostKind,state:properties.provisioningState}' --output table
if ($LASTEXITCODE -ne 0) { throw 'Could not list account capability hosts.' }
#-------------------------
#Delete the account-level capability host
#-------------------------
$existingAccountHostName = az rest --method get --uri "$accountUri/capabilityHosts?api-version=$apiVersion" --query 'value[0].name' --output tsv
az rest --method delete --uri "$accountUri/capabilityHosts/$($existingAccountHostName)?api-version=$apiVersion"
#-------------------------
#Create the account-level capability host
#-------------------------
if ($accountHostName -notmatch '^[A-Za-z0-9_-]+$') { throw "Invalid account host name: '$accountHostName'" }
$accountHostBody = @{
properties = @{
capabilityHostKind = 'Agents'
customerSubnet = $agentSubnetId
}
} | ConvertTo-Json -Depth 5
$file = [IO.Path]::GetTempFileName()
[IO.File]::WriteAllText($file, $accountHostBody, [Text.UTF8Encoding]::new($false))
az rest --method put --uri "$accountUri/capabilityHosts/$($accountHostName)?api-version=$apiVersion" --headers 'Content-Type=application/json' --body "@$file"
Remove-Item -LiteralPath $file
#Verify the result
az rest --method get --uri "$accountUri/capabilityHosts?api-version=$apiVersion" --output json
if ($LASTEXITCODE -ne 0) { throw 'Account capability host verification failed.' }
Project-level capability host
Check if project level capability host exists and is in failed state. If yes, delete and create using below code.
Also we can create project specific Cosmos, Search and Storage connections/resources.
If the Cosmos account is shared my multiple projects, each projects needs 3-5K RU's
# Check and create the project-level capability host
az rest --method get --uri "$projectUri/capabilityHosts?api-version=$apiVersion" --output json
if ($LASTEXITCODE -ne 0) { throw 'Could not list project capability hosts.' }
# Delete the project-level capability host
if ([string]::IsNullOrWhiteSpace($projectHostName)) { throw 'Set $projectHostName to the existing host name from the GET output.' }
az rest --method delete --uri "$projectUri/capabilityHosts/$($projectHostName)?api-version=$apiVersion"
# Create the project-level capability host
# An empty host name produces '.../capabilityHosts/?api-version=...', which Azure
# rejects with a misleading "UnsupportedApiVersion ... does not support HTTP method 'PUT'" error.
if ([string]::IsNullOrWhiteSpace($projectHostName)) { $projectHostName = 'project-agents-host' }
if ($projectHostName -notmatch '^[A-Za-z0-9_-]+$') { throw "Invalid project host name: '$projectHostName'" }
if ([string]::IsNullOrWhiteSpace($projectUri) -or [string]::IsNullOrWhiteSpace($apiVersion)) { throw 'Run the variables block in step 1 first.' }
$projectHostBody = @{
properties = @{
capabilityHostKind = 'Agents'
storageConnections = @($storageConnectionName)
vectorStoreConnections = @($searchConnectionName)
threadStorageConnections = @($cosmosConnectionName)
}
} | ConvertTo-Json -Depth 5
$file = [IO.Path]::GetTempFileName()
[IO.File]::WriteAllText($file, $projectHostBody, [Text.UTF8Encoding]::new($false))
az rest --method put --uri "$projectUri/capabilityHosts/$($projectHostName)?api-version=$apiVersion" --headers 'Content-Type=application/json' --body "@$file"
Remove-Item -LiteralPath $file
#Verify the result
az rest --method get --uri "$projectUri/capabilityHosts?api-version=$apiVersion" --output json
if ($LASTEXITCODE -ne 0) { throw 'Project capability host verification failed.' }
References
Capability hosts for Foundry Agent Service - Microsoft Foundry | Microsoft Learn
Use your own resources in the Foundry Agent Service - Microsoft Foundry | Microsoft Learn