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 agents (capability host + Container Registry).
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, 'Azure AI')].{Role:roleDefinitionName, Scope:scope}" -o table
36```
37 
38Requires Owner, Contributor, or Azure AI 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: Ask User for Project Details
53 
54Use AskUserQuestion for:
55 
561. **Project name** — used as azd environment name and resource group (`rg-<name>`). Must contain only alphanumeric characters and hyphens. Examples: `my-ai-project`, `dev-agents`
572. **Azure location** (optional) — defaults to North Central US (required for hosted agents preview)
583. **Enable hosted agents?** (yes/no) — provisions a capability host and Container Registry for deploying hosted agents. Defaults to no.
59 
60### Step 3: Create Directory and Initialize
61 
62```bash
63mkdir "<project-name>" && cd "<project-name>"
64azd init -t https://github.com/Azure-Samples/azd-ai-starter-basic -e <project-name> --no-prompt
65```
66 
67- `-t` — Azure AI starter template (Foundry infrastructure)
68- `-e` — environment name
69- `--no-prompt` — non-interactive, use defaults
70- **IMPORTANT:** `azd init` requires an empty directory
71 
72If user specified a non-default location:
73 
74```bash
75azd config set defaults.location <location>
76```
77 
78If user chose to enable hosted agents:
79 
80```bash
81azd env set ENABLE_HOSTED_AGENTS true
82```
83 
84This provisions a capability host (`capabilityHosts/agents`) on the Foundry account and auto-adds an Azure Container Registry for hosted agent deployments.
85 
86### Step 4: Provision Infrastructure
87 
88```bash
89azd provision --no-prompt
90```
91 
92Takes 5–10 minutes. Creates resource group, Foundry account/project, Application Insights, managed identity, and RBAC roles. If hosted agents enabled, also creates Container Registry and capability host.
93 
94### Step 5: Retrieve Project Details
95 
96```bash
97azd env get-values
98```
99 
100Capture `AZURE_AI_PROJECT_ID`, `AZURE_AI_PROJECT_ENDPOINT`, and `AZURE_RESOURCE_GROUP`. Direct user to verify at https://ai.azure.com.
101 
102### Step 6: Next Steps
103 
104- Deploy an agent → `agent/deploy` skill
105- Browse models → `foundry_models_list` MCP tool
106- Manage project → https://ai.azure.com
107 
108## Best Practices
109 
110- Use North Central US for hosted agents (preview requirement)
111- Name must be alphanumeric + hyphens only — no spaces, underscores, or special characters
112- Delete unused projects with `azd down` to avoid ongoing costs
113- `azd down` deletes ALL resources — Foundry account, agents, models, Container Registry, and Application Insights data
114- `azd provision` is safe to re-run on failure
115 
116## Troubleshooting
117 
118| Problem | Solution |
119|---------|----------|
120| `azd: command not found` | Install from https://aka.ms/azure-dev/install |
121| `ERROR: Failed to authenticate` | Run `azd auth login`; verify subscription with `az account list` |
122| `environment name '' is invalid` | Name must be alphanumeric + hyphens only |
123| `ERROR: Insufficient permissions` | Request Contributor or Azure AI Owner role from admin |
124| Region not supported for hosted agents | Use `azd config set defaults.location northcentralus` |
125| Provisioning timeout | Check region availability, verify connectivity, retry `azd provision` |
126 
127## Related Skills
128 
129- **agent/deploy** — Deploy agents to the created project
130- **agent/create** — Create a new agent for deployment
131 
132## Resources
133 
134- [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)
135