Resources, projects, and endpoints

Every permission, quota, network rule, and invoice in Foundry is attached to a specific level of the Azure resource hierarchy. This lesson defines each level, explains what belongs where, shows the difference between the new Foundry projects and the older hub-based projects, and walks through creating a resource and project from the command line so you understand every field.

Last updated: 01 Nov, 2026 · azure-ai-projects 2.x · Python 3.10+

The Azure hierarchy, level by level

Tenant (contoso.onmicrosoft.com)
└── Subscription: "AI-Prod"                       ← billing, quota per region
    └── Resource group: rg-support-bot-prod       ← lifecycle + RBAC boundary
        ├── Foundry resource: contoso-ai          ← deployments, connections, network
        │   ├── deployment: gpt-5-mini
        │   ├── deployment: text-embedding-3-large
        │   ├── connection: search-support (Azure AI Search)
        │   ├── project: support-bot              ← agents, files, evals, traces
        │   └── project: sales-assistant
        ├── Azure AI Search: srch-support-prod
        ├── Storage account: stsupportprod
        └── Application Insights: appi-support-prod

What lives at which level

Foundry projects vs hub-based projects

You will meet two project types. Know the difference so you pick the right one and recognise old instructions.

Choosing a region

The region of the Foundry resource decides which models and features you can use, where data is stored at rest, and latency for your users.

• Model availability differs by region and deployment type. Check the model card or the region availability table before you create anything.
• Feature availability (some agent tools, evaluation features, hosted agents) also varies. Preview features usually reach a few US and European regions first.
• Data residency: data at rest stays in the resource's region. With Global deployments, inference may run in any Azure region; Data Zone deployments keep processing inside the US or the EU.
• Quota is per subscription, per region, per model. If one region is exhausted, another may have room.

Create a resource and project with the Azure CLI

The portal wizard does the same thing, but the CLI shows every decision explicitly and is repeatable. You need Azure CLI 2.80 or newer and the Contributor or Owner role on the resource group.

# variables — the custom domain must be globally unique
RG=rg-foundry-course
LOC=eastus2
RES=foundry-course-$RANDOM
PROJ=support-bot

# 1. resource group
az group create --name $RG --location $LOC

# 2. Foundry resource
az cognitiveservices account create \
  --name $RES \
  --resource-group $RG \
  --kind AIServices \
  --sku S0 \
  --location $LOC \
  --custom-domain $RES \
  --assign-identity \
  --allow-project-management true

# 3. project
az cognitiveservices account project create \
  --name $RES \
  --resource-group $RG \
  --project-name $PROJ \
  --location $LOC

# 4. verify both
az cognitiveservices account show -n $RES -g $RG --query properties.provisioningState -o tsv
az cognitiveservices account project show -n $RES -g $RG --project-name $PROJ \
  --query properties.provisioningState -o tsv

Both show commands should print Succeeded. If project creation fails with a managed identity error, the resource was created without --assign-identity.

Endpoints: which URL is which

A Foundry resource exposes several endpoints. Using the wrong one is the most common beginner error.

Here is a small offline helper that validates a project endpoint and derives the related URLs — handy as a startup check so a misconfigured environment variable fails fast with a clear message.

from urllib.parse import urlparse


def parse_project_endpoint(endpoint: str) -> dict:
    """Split a Foundry project endpoint into its parts."""
    url = urlparse(endpoint)
    host = url.hostname or ""
    if not host.endswith(".services.ai.azure.com"):
        raise ValueError(f"not a Foundry endpoint: {host}")
    parts = [p for p in url.path.split("/") if p]
    if len(parts) != 3 or parts[:2] != ["api", "projects"]:
        raise ValueError("expected /api/projects/<project-name>")
    resource = host.split(".")[0]
    return {
        "resource": resource,
        "project": parts[2],
        "openai_v1": f"{endpoint.rstrip('/')}/openai/v1",
        "account_openai": f"https://{resource}.openai.azure.com/openai/v1",
    }


ep = "https://contoso-ai.services.ai.azure.com/api/projects/support-bot"
for key, value in parse_project_endpoint(ep).items():
    print(f"{key:<15} {value}")

try:
    parse_project_endpoint("https://contoso-ai.openai.azure.com/")
except ValueError as err:
    print("error:", err)

Infrastructure as code

For real projects, describe the resources in Bicep or Terraform instead of clicking or running ad-hoc commands. You get code review, repeatable environments, and drift detection. The Foundry resource is Microsoft.CognitiveServices/accounts with kind: 'AIServices' and allowProjectManagement: true; projects are the child type accounts/projects; deployments are accounts/deployments. Microsoft publishes starter templates in the Foundry samples repositories and the Azure Developer CLI (azd) templates.