Designing Foundry Infrastructure

Plan the boundaries before the resources

Before anyone creates a Foundry resource, someone has to decide who shares what. Skip that step and the bill, the permissions and the incidents all end up tangled together.

A structured deployment plan helps you avoid security gaps, cost overruns, and access sprawl when you adopt Microsoft Foundry at scale. The plan starts with isolation boundaries, then capability needs, then the resource topology, and only then the security baseline and the agent data layer.

For the common organization, the recommended sequence has four steps:

1. First, define nonnegotiable sharing boundaries across business units, data domains, product ownership, and environment tiers.
2. Second, set a production policy that defaults to isolation, unless a written exception allows colocation.
3. Third, set an exploration policy that defaults to colocation for faster experimentation, unless compliance or validation requires isolation.
4. Fourth, assign ownership for each boundary, including security, cost, and incident response ownership.

Notice that steps two and three point in opposite directions. That contrast is the heart of the topic:

So production starts separated and has to justify sharing, while exploration starts shared and has to justify separation. Ownership closes the loop: every boundary needs a named owner for security, cost, and incident response.

Co-located or fully isolated topology

Once the boundaries exist, you choose how many Foundry resources to run. There are only two paths, and each buys something at a price.

In the co-located path, you run one Foundry resource with multiple projects, typically one project per use case. It fits experimentation-heavy environments, early prototypes, and teams that benefit from shared deployments and shared connected data or tools. Its main tradeoff is a shared blast radius for production incidents, quota exhaustion, and misconfiguration.

In the fully isolated path, you run one Foundry resource per production workload boundary, often with one primary project per workload. It fits production workloads that require strict operational containment, independent access control, and independent quota or cost boundaries. Its main tradeoff is that self-serve enablement gets harder, with more resources to manage and higher setup overhead.

For production, treat isolation as the default. Use colocation as a deliberate exception only when workload boundaries, data requirements, and risk acceptance are aligned.

A quick example: an innovation lab running a dozen small prototypes on non-production data wants to reuse the same model deployments and pre-connected tools. That is the co-located path, with one project per idea. A funded customer-facing workload that needs its own quota and access control is the isolated path.

Capability scope shapes the boundary

The topology must also fit what each API can do. Projects can isolate some capabilities and not others, so the capability mix can force a decision on its own.

When use cases share one Foundry resource, Foundry projects act as isolated workspaces for each use case. Most newer, agent-centric Foundry APIs support project-scope permissioning. Some traditional Foundry Tools APIs (former Azure AI Services), such as speech-to-text, still require parent resource-scope access.

So confirm the capability mix before you finalize the topology. If a required API only works at Foundry resource scope, assign roles at that scope or isolate workloads into separate Foundry resources.

Three capability areas are worth memorizing, because each one points to a different design:

Agent capabilities support project organization and project-level RBAC isolation, which makes them a good fit for project-per-use-case segmentation in shared environments. Fine-tune training runs in the default project only, without project-level RBAC isolation, so if each team needs independent fine-tuning, use separate Foundry resources. Fine-tuned deployments are shared and consumable across projects within a resource. Content Understanding has no project-level RBAC isolation, so if strict per-use-case access isolation is required, prefer separate Foundry resources.

Security baseline and the two access planes

With the topology chosen, the security baseline fills in four decisions:

• Identity and access. Map admin, project manager, and project user personas to least-privilege roles and Microsoft Entra ID groups.
• Networking. For networking, use a managed virtual network for a more secure, straightforward setup, and a bring-your-own virtual network for advanced network control and custom routing requirements.
• Keys. Decide whether Microsoft-managed keys meet policy requirements or whether customer-managed keys are required.
• Authentication. Prefer Microsoft Entra ID and RBAC for people and services, and use API keys only where role granularity isn't required.

Connections can be created at the parent Foundry resource level or at the child project level, depending on the isolation scope you want. Connections configured at the parent level are available to all projects.

One permission trap catches many teams. Foundry separates control plane RBAC actions, for resource management, from data plane RBAC actions, for development workloads.

Management roles such as Owner or Contributor aren't sufficient for all development scenarios: a user can manage resources but still need data plane roles to chat with an agent in Foundry.

Think of it as two doors. The control plane door lets you create, configure and delete the resource. The data plane door lets you work inside it, for example chatting with an agent. Holding the key to the first door says nothing about the second.

Basic or standard agent setup

Agents produce data: conversations, uploaded files and vector stores. The setup you choose decides whose resources hold it.

The basic agent setup uses Microsoft-managed resources for agent data. Standard agent setup uses customer-managed, single-tenant Azure resources to store agent state and keep all agent data under your control. Use standard setup when you need full data sovereignty, compliance with enterprise security policies, or project-level isolation.

Standard setup brings three of your own resources:

• Azure Storage stores files uploaded by developers and end users.
• Azure AI Search stores the vector stores created by the agent.
• Azure Cosmos DB stores messages, conversation history, and agent metadata.

The Azure Cosmos DB for NoSQL account must have a total throughput limit of at least 3000 RU/s, and both provisioned throughput and serverless modes are supported. Insufficient RU/s capacity in the Cosmos DB account causes provisioning failures during deployment. An Azure Key Vault resource manages secrets and connection strings for the agent infrastructure. Standard setup enforces project-level data isolation by default.

Microsoft recommends using separate Foundry accounts and projects for standard agent setup and basic agent setup, and avoiding mixing setup types within the same Foundry account.

Capability settings and capability hosts

How does a project know which Cosmos DB, AI Search and Storage to use? Through its capability settings.

Capability settings are properties on the Foundry account and the project that declare which Azure resources hold agent state, vector data, and files. You set them on the account to establish defaults for its projects, and override an individual store on a project when that project needs a different resource.

Capability settings use the 2026-07-15-preview API and are currently available in UK South and Canada Central. Check availability before choosing this provisioning path for a workload in another region.

The connections that capability settings manage are immutable while in use, so you can't edit or delete them directly. You can't update capability settings on an existing project: to change which resources a project uses, delete and recreate the project with the desired settings.

You will also meet the older name. Capability hosts are the earlier mechanism for the same job, and their article is now retained for reference. They are sub-resources at the account and project scopes, managed through the REST API.

Three rules carried over to the way people work with them:

• Updating a capability host isn't supported, so you delete it and recreate it.
• Each account and each project can have only one active capability host.
• You can't create a project capability host unless an account-level capability host already exists.

The common thread with capability settings: once agent storage is wired to a project, you change it by recreating, not by editing.

Provisioning and runtime permissions

Standard setup involves two different identities, and mixing them up is the most common failure after a deployment succeeds.

The identity that runs a capability settings deployment needs Storage Blob Data Contributor on the storage account and Cosmos DB Operator on the Cosmos DB account, while Azure AI Search doesn't require a caller role. Runtime access is a separate set of roles on the project managed identity, and one doesn't substitute for the other.

For example, the project managed identity needs Storage Blob Data Contributor on the blobstore container and Storage Blob Data Owner on the agent container, or the agent gets 403 Forbidden when it reads or writes files. Developers who create or edit agents need the Foundry User role on the project scope; without it, they get AuthorizationFailed.