Standard Agent Setup
⚠️ Warning: This page covers Foundry's Standard Agent Setup (capability host + bring-your-own Cosmos DB / Azure Storage / Azure AI Search). The default
azd ai agentflow uses Basic Agent Setup and does not provision acapabilityHosts/agentsresource — stop reading this page if you arrived fromazd ai agent. See foundry-agent/create/create-hosted.md and the canonical env vars in environment-variables.md.
MANDATORY: Read Standard Agent Setup docs before proceeding with standard setup.
Overview
Microsoft Foundry supports two agent setup configurations:
| Setup | Capability Host | Description |
|---|---|---|
| Basic | None | Default setup. All resources are Microsoft-managed. No additional connections required. |
| Standard | Azure AI Services | Advanced setup. Bring-your-own storage and search connections for full control over data residency and scaling. |
Standard Setup Connections
| Connection | Service | Required | Purpose |
|---|---|---|---|
| Thread storage | Azure Cosmos DB | ✅ Yes | Store conversation threads in your own Cosmos DB instance |
| File storage | Azure Storage | ✅ Yes | Store uploaded files in your own Azure Storage account |
| Vector store | Azure AI Search | ✅ Yes | Use your own Azure AI Search instance for vector/knowledge retrieval |
| Azure AI Services | Azure AI Services | ❌ Optional | Use OpenAI models from a different AI Services resource |
💡 Tip: Standard setup is recommended for production workloads that require control over data storage, custom vector search, or integration with models from a separate AI Services resource.
Prerequisites
Before starting deployment, confirm the following with the user:
- RBAC role on the resource group: The user must have Owner or User Access Administrator role on the target resource group. The Bicep template assigns RBAC roles (Storage Blob Data Contributor, Cosmos DB Operator, AI Search roles) to the project's managed identity — this will fail without
Microsoft.Authorization/roleAssignments/writepermission. - Subscription quota: Verify the target region has available quota for AI Services. If quota is exhausted, try an alternate region (e.g.,
swedencentral,eastus,westus3). - Azure Policy compliance: Some subscriptions enforce policies (e.g., storage accounts must disable public network access). If the Bicep template fails due to policy violations, patch the template to comply (e.g., set
publicNetworkAccess: 'Disabled'anddefaultAction: 'Deny'on the storage account).
Deployment
- Standard setup always creates a new Foundry resource and a new project. Do not ask the user for a project endpoint — one will be provisioned as part of the deployment.
- Always use the official Bicep template: Standard Agent Setup Bicep Template
⚠️ Warning: Capability host provisioning is asynchronous and can take 10–20 minutes. After deploying the Bicep template, you must poll the deployment status until it succeeds. Do not assume the setup is complete immediately.
Post-Deployment: Model & Agent
After infrastructure provisioning succeeds:
- Deploy a model to the new AI Services account (e.g.,
gpt-4o). IfGlobalStandardSKU quota is exhausted, fall back toStandardSKU. - Create the agent using MCP tools (
agent_update) or the Python SDK (client.agents.create_version). See SDK Operations for details.