Azure AI Agent App Deployment

Up Skill

Goal

Provision a fresh Azure environment end-to-end and verify the app starts successfully.

Before starting

When the skill is triggered, always re-read this SKILL.md file from disk before executing, in case it has been updated since the last run.

Then proceed to Step 1 (Choose environment name) immediately — the user must pick an environment before anything else.

Terminal usage

All shell commands in this skill must be run using the powershell tool with mode="sync". Use a short initial_wait (30 seconds) for quick commands like az account show, az ad signed-in-user show, az role assignment list, azd env list, azd env new, and azd env set.

Exception — azd up and azd down: These long-running commands must be run with mode="async" and a short initial_wait (10 seconds) so the user can see streaming progress output in real time (just like running in a terminal). After launching, poll frequently using read_powershell with a short delay (15–20 seconds) — this is critical so the user sees output updates as they happen, similar to watching the command in a terminal. Keep calling read_powershell in a loop (each call in a new response turn) until the command completes or you receive a completion notification. Do NOT use long delays like 120 seconds — that defeats the purpose of streaming output.

Chain short related commands with && or ; into a single powershell call when they have no branching logic between them.

Steps

1. Choose environment name

1a. Resolve existing environment

First, check whether there is already a default azd environment:

$existingEnvs = azd env list -o json 2>$null | ConvertFrom-Json

Find the default environment (the entry where IsDefault is true or the DefaultEnvironment field is set, depending on the azd version).

1b. Generate a suggested new name

Regardless of whether a default environment exists, always prepare a suggested new name for use as a choice.

Scan $existingEnvs for names matching the pattern <prefix><number> (e.g., agent1, test-env3, agent-qt-2). If found, take the one with the highest number and suggest the next increment (e.g., agent2, test-env4, agent-qt-3).

If no numbered environments exist, generate a default name:

$suffix = -join ((0..9) + ('a','b','c','d','e','f','g','h','i','j','k','l','m','n','o','p','q','r','s','t','u','v','w','x','y','z') | Get-Random -Count 6)
$suggestedName = "agent-qt-$suffix"

1c. Ask the user

If a default environment was found, present the user with choices:

1. Use the current environment <defaultEnvName> — re-provision/update the existing environment (first choice, include the environment name in the label)
2. Create a new environment <suggestedName> — use the suggested new name from 1b
3. Enter a different name — the user provides their own name

For example:

Do you want to azd up the current environment agent-qt-2, or create a new one?

If no default environment was found, present the user with choices:

1. Use the suggested name <suggestedName> — use the name generated in 1b
2. Enter a different name — the user provides their own name

• If the user provides a different name, use their name instead.
• Environment names must be lowercase alphanumeric and hyphens only, max 64 characters.

The resource group will be rg-<envName>.

1½. Check for existing AI project (shortcut)

After resolving the environment name, check whether the selected environment already has AZURE_EXISTING_AIPROJECT_RESOURCE_ID set:

$existingProject = azd env get-value AZURE_EXISTING_AIPROJECT_RESOURCE_ID --environment $envName 2>$null

If the value is non-empty, the environment is pre-configured to use an existing AI project. Print the short-path steps overview and jump directly to Step 9 (azd up):

Up Skill — Steps Overview (environment: <envName>, existing AI project)

1. ✅ Choose environment name 2–8. ⏭️ Skipped (existing AI project detected)
2. Run azd up
3. Retrieve the app endpoint
4. Health-check the app
5. Report results

If the value is empty or not set, print the full-path steps overview and continue to Step 2:

Up Skill — Steps Overview (environment: <envName>)

1. ✅ Choose environment name
2. Resolve subscription
3. Check RBAC permissions
4. Resolve region
5. Check agent model quota
6. Ask about Azure AI Search
7. Check embedding model quota (if AI Search enabled)
8. Create the azd environment and set overrides
9. Run azd up
10. Retrieve the app endpoint
11. Health-check the app
12. Report results

2. Resolve subscription

Auto-detect the default Azure Subscription ID using this priority order (use the first one found):

1. Environment variable AZURE_SUBSCRIPTION_ID
2. azd config get defaults.subscription (may return empty)
3. az account show --query id -o tsv (current Azure CLI login)

Present the user with 2 choices:

1. Use the detected subscription — show the subscription ID (and name if available via az account show --query "{id:id, name:name}" -o json) as the default choice
2. Enter a different subscription — prompt the user to input a subscription ID

If no subscription was detected, skip choice 1 and ask the user to provide one directly.

Show the resolved subscription to the user for confirmation before proceeding.

3. Check RBAC permissions (prerequisite)

Verify the user has sufficient permissions to create role assignments on the subscription, which is required for provisioning. The user needs Owner or User Access Administrator — either assigned directly or inherited through a group membership.

3a. Check direct role assignments

$principalId = az ad signed-in-user show --query id -o tsv
$subScope = "/subscriptions/<subscriptionId>"
$roles = az role assignment list --assignee $principalId --scope $subScope --query "[].roleDefinitionName" -o json | ConvertFrom-Json

Check if $roles contains Owner or User Access Administrator.

• If yes, proceed to Step 4.
• If no, continue to 3b to check group-based assignments.

3b. Check group-based role assignments

The user may hold the required role through a group membership. Query the user's group memberships and check whether any of those groups have the required roles on the subscription.

$groupIds = az ad signed-in-user get-member-of --query "[].id" -o json | ConvertFrom-Json

If $groupIds is non-empty, check role assignments for each group on the subscription:

$groupRoles = @()
foreach ($gid in $groupIds) {
    $gr = az role assignment list --assignee $gid --scope $subScope --query "[].roleDefinitionName" -o json 2>$null | ConvertFrom-Json
    if ($gr) { $groupRoles += $gr }
}

Check if $groupRoles contains Owner or User Access Administrator.

• If yes, proceed to Step 4.
• If no, report the issue:
  • Show the subscription name and ID that failed the check
  • Show the user's current roles on the subscription
  • Explain that azd up will fail because the deployment creates Microsoft.Authorization/roleAssignments
  • Present 3 choices:
    1. "I just added the role — re-check" → Re-run the RBAC check on the same subscription
    2. "Use a different subscription" → Prompt the user for a new subscription ID, then go back to Step 3
    3. "Exit" → Stop the skill

4. Resolve region

Check environment variable AZURE_LOCATION first. If not set, ask the user — must be one of: eastus, eastus2, swedencentral, westus, westus3. Default to eastus if the user has no preference.

Show the resolved region to the user for confirmation before proceeding.

5. Check agent model quota (prerequisite)

Before provisioning, verify the default agent model has sufficient quota in the selected region.

Default model: gpt-5-mini | SKU: GlobalStandard | Required capacity: 80

5a. Query quota and model availability

$usage = az cognitiveservices usage list --location <region> --subscription <subscriptionId> -o json | ConvertFrom-Json
$modelList = az cognitiveservices model list --location <region> --subscription <subscriptionId> -o json | ConvertFrom-Json

Cache both $usage and $modelList — they are reused in Step 7 for embedding checks.

5b. Check default agent model quota

$defaultUsageName = "OpenAI.GlobalStandard.gpt-5-mini"
$entry = $usage | Where-Object { $_.name.value -eq $defaultUsageName }

If the entry exists, compute available = limit - currentValue.

• If available >= 80, the default model has enough quota — skip to Step 6.
• If the entry is missing, the model/SKU is not available in this region — continue to 5c.
• If available < 80, quota is insufficient — continue to 5c.

Report the finding to the user (e.g., "gpt-5-mini has 40/80 quota available — insufficient").

5c. Find alternative agent models

From the quota usage list, find all GPT entries with Global or GlobalStandard SKUs that have sufficient available quota:

$gptEntries = $usage | Where-Object {
    $_.name.value -match '^OpenAI\.(Global|GlobalStandard)\.gpt-' -and
    ($_.limit - $_.currentValue) -ge 80
}

For each candidate, cross-reference with $modelList to confirm the model is actually deployable (exists with format OpenAI and is not retired). Discard any candidate not confirmed by the model list.

5d. Rank agent model candidates

Use this preference order (higher is better):

1. gpt-5.2
2. gpt-5.2-mini
3. gpt-5.1
4. gpt-5.1-mini
5. gpt-5
6. gpt-5-mini
7. gpt-4.1
8. gpt-4.1-mini
9. gpt-4o
10. gpt-4o-mini

Within the same model name, prefer GlobalStandard over Global.