1---
2name: foundry-create-project
3description: |
4  Create a new Azure AI Foundry project using Azure Developer CLI (azd) to provision infrastructure for hosting AI agents and models.
5  USE FOR: create Foundry project, new AI Foundry project, set up Foundry, azd init Foundry, provision Foundry infrastructure, onboard to Foundry, create Azure AI project, set up AI project.
6  DO NOT USE FOR: deploying agents to existing projects (use agent/deploy), creating agent code (use agent/create), deploying AI models from catalog (use microsoft-foundry main skill), Azure Functions (use azure-functions).
7allowed-tools: Read, Write, Bash, AskUserQuestion
8---
9 
10# Create Azure AI Foundry Project
11 
12Create a new Azure AI Foundry project using azd. Provisions: Foundry account, project, Application Insights, managed identity, and RBAC permissions. Optionally enables hosted-agent deployment (adds an Azure Container Registry, and — only when the **Standard Setup** capability-host flag is also enabled — a `capabilityHosts/agents` resource).
13 
14**Table of Contents:** [Prerequisites](#prerequisites) · [Workflow](#workflow) · [Best Practices](#best-practices) · [Troubleshooting](#troubleshooting) · [Related Skills](#related-skills) · [Resources](#resources)
15 
16## Prerequisites
17 
18Run checks in order. STOP on any failure and resolve before proceeding.
19 
20**1. Azure CLI** — `az version` → expects version output. If missing: https://aka.ms/installazurecli
21 
22**2. Azure login & subscription:**
23 
24```bash
25az account show --query "{Name:name, SubscriptionId:id, State:state}" -o table
26```
27 
28If not logged in, run `az login`. If no active subscription: https://azure.microsoft.com/free/ — STOP.
29 
30If multiple subscriptions, ask which to use, then `az account set --subscription "<id>"`.
31 
32**3. Role permissions:**
33 
34```bash
35az role assignment list --assignee "$(az ad signed-in-user show --query id -o tsv)" --query "[?contains(roleDefinitionName, 'Owner') || contains(roleDefinitionName, 'Contributor') || contains(roleDefinitionName, 'Foundry')].{Role:roleDefinitionName, Scope:scope}" -o table
36```
37 
38Requires Owner, Contributor, or Foundry Owner. If insufficient — STOP, request elevated access from admin.
39 
40**4. Azure Developer CLI** — `azd version`. If missing: https://aka.ms/azure-dev/install
41 
42## Workflow
43 
44### Step 1: Verify azd login
45 
46```bash
47azd auth login --check-status
48```
49 
50If not logged in, run `azd auth login` and complete browser auth.
51 
52### Step 2: Resolve Project Details
53 
54Collect only values the user has not already provided. For values not specified, use defaults:
55 
561. **Project name** — used as azd environment name and resource group (`rg-<name>`). Must contain only alphanumeric characters and hyphens.
57   - If the user provided a name, use it as-is.
58   - If the user did NOT provide a name, **auto-generate a unique name** using the pattern `ai-project-<random>` where `<random>` is a short random suffix (6-8 lowercase alphanumeric characters). Generate the suffix with a platform-appropriate method:
59     ```bash
60     # bash/zsh
61     echo "ai-project-$(openssl rand -hex 4)"
62     ```
63     ```powershell
64     # PowerShell
65     "ai-project-$(-join ((48..57)+(97..122) | Get-Random -Count 8 | ForEach-Object {[char]$_}))"
66     ```
67   - Show the generated name to the user before proceeding, but do not block on confirmation — proceed unless the user objects.
68   - Examples: `ai-project-3f8a1b2c`, `my-ai-project`, `dev-agents`
692. **Azure location** (optional) — defaults to North Central US (required for hosted agents preview)
703. **Enable hosted agents?** (yes/no) — enables hosted-agent deployment and provisions an Azure Container Registry. A capability host (`capabilityHosts/agents`, used by Foundry's **Standard Agent Setup** for bring-your-own storage) is also created only when `ENABLE_CAPABILITY_HOST=true`. Defaults to no. See [Step 3](#step-3-create-directory-and-initialize) for how the two flags interact.
71 
72### Step 3: Create Directory and Initialize
73 
74```bash
75mkdir "<project-name>" && cd "<project-name>"
76azd init -t https://github.com/Azure-Samples/azd-ai-starter-basic -e <project-name> --no-prompt
77```
78 
79- `-t` — Azure AI starter template (Foundry infrastructure)
80- `-e` — environment name
81- `--no-prompt` — non-interactive, use defaults
82- **IMPORTANT:** `azd init` requires an empty directory
83 
84If user specified a non-default location:
85 
86```bash
87azd config set defaults.location <location>
88```
89 
90If user chose to enable hosted agents:
91 
92```bash
93azd env set ENABLE_HOSTED_AGENTS true
94azd env set ENABLE_CAPABILITY_HOST false
95```
96 
97`ENABLE_HOSTED_AGENTS=true` enables hosted-agent deployment and creates an Azure Container Registry for the container image. A capability host (`capabilityHosts/agents`, used by Foundry's **Standard Agent Setup** for bring-your-own storage) is **also** created only when `ENABLE_CAPABILITY_HOST=true`. The default `azd ai agent` flow targets **Basic Agent Setup**, so it sets `ENABLE_CAPABILITY_HOST=false` automatically. The two flags are independent.
98 
99> ⚠️ **Warning:** The Bicep template parameter `enableCapabilityHost` defaults to `true`. If you set `ENABLE_HOSTED_AGENTS` by hand without also setting `ENABLE_CAPABILITY_HOST=false`, you will accidentally provision Standard Setup (with the capability host). Use `azd ai agent init` to set both flags correctly.
100 
101See the canonical env-var docs: [azure-dev/cli/azd/docs/environment-variables.md](https://github.com/Azure/azure-dev/blob/main/cli/azd/docs/environment-variables.md).
102 
103### Step 4: Provision Infrastructure
104 
105```bash
106azd provision --no-prompt
107```
108 
109Takes 5–10 minutes. Creates resource group, Foundry account/project, Application Insights, managed identity, and RBAC roles. If `ENABLE_HOSTED_AGENTS=true`, also creates an Azure Container Registry. A `capabilityHosts/agents` resource is created **only** when `ENABLE_CAPABILITY_HOST=true` (Standard Setup); the default Basic Setup uses `ENABLE_CAPABILITY_HOST=false` and no capability host is provisioned — its absence is correct.
110 
111### Step 5: Retrieve Project Details
112 
113```bash
114azd env get-values
115```
116 
117Capture `AZURE_AI_PROJECT_ID`, `AZURE_AI_PROJECT_ENDPOINT`, and `AZURE_RESOURCE_GROUP`. Direct user to verify at https://ai.azure.com.
118 
119### Step 6: Next Steps
120 
121> **Next — azd Golden Path:** create a hosted agent with [foundry-agent/create/create-hosted.md](../../foundry-agent/create/create-hosted.md). For headless / scripted flows, **pre-bootstrap the workspace with core `azd init`** so subscription + location are populated before model resolution runs:
122>
123> ```bash
124> azd init -t Azure-Samples/azd-ai-starter-basic . -e <env-name> --subscription <id> -l <region>
125> azd ai agent init -m <manifest-url> --no-prompt --deploy-mode code --runtime python_3_13 --entry-point main.py
126> ```
127>
128> Core `azd init` accepts `--subscription` and `-l/--location`; `azd ai agent init` does not. `azd ai agent init` then resolves the model from the chosen sample's manifest and writes it into `azure.yaml services.<name>.config.deployments[]`; the next `azd provision` creates the deployment through Bicep. **You do not need to deploy a model separately for this path** — no `az cognitiveservices` calls, no `azd env set AI_PROJECT_DEPLOYMENTS`.
129>
130> Use [models/deploy-model](../../models/deploy-model/SKILL.md) **only** for out-of-band scenarios: adding models to a Foundry project that is not managed by this azd project, or ad-hoc deployments outside the azd lifecycle.
131 
132- Deploy an existing agent → [foundry-agent/deploy/deploy.md](../../foundry-agent/deploy/deploy.md)
133- Browse model catalog → `foundry_models_list` MCP tool
134- Manage project → https://ai.azure.com
135 
136## Best Practices
137 
138- Use North Central US for hosted agents (preview requirement)
139- Name must be alphanumeric + hyphens only — no spaces, underscores, or special characters
140- Delete unused projects with `azd down` to avoid ongoing costs
141- `azd down` deletes ALL resources — Foundry account, agents, models, Container Registry, and Application Insights data
142- `azd provision` is safe to re-run on failure
143 
144## Troubleshooting
145 
146| Problem | Solution |
147|---------|----------|
148| `azd: command not found` | Install from https://aka.ms/azure-dev/install |
149| `ERROR: Failed to authenticate` | Run `azd auth login`; verify subscription with `az account list` |
150| `environment name '' is invalid` | Name must be alphanumeric + hyphens only |
151| `ERROR: Insufficient permissions` | Request Contributor or Foundry Owner role from admin |
152| Region not supported for hosted agents | Use `azd config set defaults.location northcentralus` |
153| Provisioning timeout | Check region availability, verify connectivity, retry `azd provision` |
154 
155## Related Skills
156 
157- **agent/deploy** — Deploy agents to the created project
158- **agent/create** — Create a new agent for deployment
159 
160## Resources
161 
162- [Azure Developer CLI](https://aka.ms/azure-dev/install) · [AI Foundry Portal](https://ai.azure.com) · [Foundry Docs](https://learn.microsoft.com/azure/ai-foundry/) · [azd-ai-starter-basic template](https://github.com/Azure-Samples/azd-ai-starter-basic)
163