1# Customize Workflow — Detailed Phase Instructions
2 
3> Reference for: `models/deploy-model/customize/SKILL.md`
4 
5## Phase 1: Verify Authentication
6 
7```bash
8az account show --query "{Subscription:name, User:user.name}" -o table
9```
10 
11If not logged in: `az login`
12 
13Set subscription if needed:
14```bash
15az account list --query "[].[name,id,state]" -o table
16az account set --subscription <subscription-id>
17```
18 
19---
20 
21## Phase 2: Get Project Resource ID
22 
23Check `PROJECT_RESOURCE_ID` env var. If not set, prompt user.
24 
25**Format:** `/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}`
26 
27---
28 
29## Phase 3: Parse and Verify Project
30 
31Parse ARM resource ID to extract components:
32 
33```powershell
34$SUBSCRIPTION_ID = ($PROJECT_RESOURCE_ID -split '/')[2]
35$RESOURCE_GROUP = ($PROJECT_RESOURCE_ID -split '/')[4]
36$ACCOUNT_NAME = ($PROJECT_RESOURCE_ID -split '/')[8]
37$PROJECT_NAME = ($PROJECT_RESOURCE_ID -split '/')[10]
38```
39 
40Verify project exists and get region:
41```bash
42az account set --subscription $SUBSCRIPTION_ID
43az cognitiveservices account show \
44  --name $ACCOUNT_NAME \
45  --resource-group $RESOURCE_GROUP \
46  --query location -o tsv
47```
48 
49---
50 
51## Phase 4: Get Model Name
52 
53List available models if not provided:
54```bash
55az cognitiveservices account list-models \
56  --name $ACCOUNT_NAME \
57  --resource-group $RESOURCE_GROUP \
58  --query "[].name" -o json
59```
60 
61Present sorted unique list. Allow custom model name entry.
62 
63**Detect model format:**
64 
65```bash
66# Get model format (e.g., OpenAI, Anthropic, Meta-Llama, Mistral, Cohere)
67MODEL_FORMAT=$(az cognitiveservices account list-models \
68  --name "$ACCOUNT_NAME" \
69  --resource-group "$RESOURCE_GROUP" \
70  --query "[?name=='$MODEL_NAME'].format" -o tsv | head -1)
71 
72MODEL_FORMAT=${MODEL_FORMAT:-"OpenAI"}
73echo "Model format: $MODEL_FORMAT"
74```
75 
76> 💡 **Model format determines the deployment path:**
77> - `OpenAI` — Standard CLI, TPM-based capacity, RAI policies, version upgrade policies
78> - `Anthropic` — REST API with `modelProviderData`, capacity=1, no RAI, no version upgrade
79> - All other formats (`Meta-Llama`, `Mistral`, `Cohere`, etc.) — Standard CLI, capacity=1 (MaaS), no RAI, no version upgrade
80 
81---
82 
83## Phase 5: List and Select Model Version
84 
85```bash
86az cognitiveservices account list-models \
87  --name $ACCOUNT_NAME \
88  --resource-group $RESOURCE_GROUP \
89  --query "[?name=='$MODEL_NAME'].version" -o json
90```
91 
92Recommend latest version (first in list). Default to `"latest"` if no versions found.
93 
94---
95 
96## Phase 6: List and Select SKU
97 
98> ⚠️ **Warning:** Never hardcode SKU lists — always query live data.
99 
100**Step A — Query model-supported SKUs:**
101```bash
102az cognitiveservices model list \
103  --location $PROJECT_REGION \
104  --subscription $SUBSCRIPTION_ID -o json
105```
106 
107Filter: `model.name == $MODEL_NAME && model.version == $MODEL_VERSION`, extract `model.skus[].name`.
108 
109**Step B — Check subscription quota per SKU:**
110```bash
111az cognitiveservices usage list \
112  --location $PROJECT_REGION \
113  --subscription $SUBSCRIPTION_ID -o json
114```
115 
116Quota key pattern: `OpenAI.<SKU>.<model-name>`. Calculate `available = limit - currentValue`.
117 
118**Step C — Present only deployable SKUs** (available > 0). If no SKUs have quota, direct user to the [quota skill](../../../../quota/quota.md).
119 
120---
121 
122## Phase 7: Configure Capacity
123 
124> ⚠️ **Non-OpenAI models (MaaS):** If `MODEL_FORMAT != "OpenAI"`, capacity is always `1` (pay-per-token billing). Skip capacity configuration and set `DEPLOY_CAPACITY=1`. Proceed to Phase 7c (Anthropic) or Phase 8.
125 
126**For OpenAI models only — query capacity via REST API:**
127```bash
128# Current region capacity
129az rest --method GET --url \
130  "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/providers/Microsoft.CognitiveServices/locations/$PROJECT_REGION/modelCapacities?api-version=2024-10-01&modelFormat=$MODEL_FORMAT&modelName=$MODEL_NAME&modelVersion=$MODEL_VERSION"
131```
132 
133Filter result for `properties.skuName == $SELECTED_SKU`. Read `properties.availableCapacity`.
134 
135**Capacity defaults by SKU (OpenAI only):**
136 
137| SKU | Unit | Min | Max | Step | Default |
138|-----|------|-----|-----|------|---------|
139| ProvisionedManaged | PTU | 50 | 1000 | 50 | 100 |
140| Others (TPM-based) | TPM | 1000 | min(available, 300000) | 1000 | min(10000, available/2) |
141 
142Validate user input: must be >= min, <= max, multiple of step. On invalid input, explain constraints.
143 
144### Phase 7b: Cross-Region Fallback
145 
146If no capacity in current region, query ALL regions:
147```bash
148az rest --method GET --url \
149  "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/providers/Microsoft.CognitiveServices/modelCapacities?api-version=2024-10-01&modelFormat=$MODEL_FORMAT&modelName=$MODEL_NAME&modelVersion=$MODEL_VERSION"
150```
151 
152Filter: `properties.skuName == $SELECTED_SKU && properties.availableCapacity > 0`. Sort descending by capacity.
153 
154Present available regions. After user selects region, find existing projects there:
155```bash
156az cognitiveservices account list \
157  --query "[?kind=='AIProject' && location=='$PROJECT_REGION'].{Name:name, ResourceGroup:resourceGroup}" \
158  -o json
159```
160 
161If projects exist, let user select one and update `$ACCOUNT_NAME`, `$RESOURCE_GROUP`. If none, direct to project/create skill.
162 
163Re-run capacity configuration with new region's available capacity.
164 
165If no region has capacity: fail with guidance to request quota increase, check existing deployments, or try different model/SKU.
166 
167---
168 
169## Phase 7c: Anthropic Model Provider Data (Anthropic models only)
170 
171> ⚠️ **Only execute this phase if `MODEL_FORMAT == "Anthropic"`.** For OpenAI and other models, skip to Phase 8.
172 
173Anthropic models require `modelProviderData` in the deployment payload. Collect this before deployment.
174 
175**Step 1: Prompt user to select industry**
176 
177Present the following list and ask the user to choose one:
178 
179```
180 1. None                    (API value: none)
181 2. Biotechnology           (API value: biotechnology)
182 3. Consulting              (API value: consulting)
183 4. Education               (API value: education)
184 5. Finance                 (API value: finance)
185 6. Food & Beverage         (API value: food_and_beverage)
186 7. Government              (API value: government)
187 8. Healthcare              (API value: healthcare)
188 9. Insurance               (API value: insurance)
18910. Law                     (API value: law)
19011. Manufacturing           (API value: manufacturing)
19112. Media                   (API value: media)
19213. Nonprofit               (API value: nonprofit)
19314. Technology              (API value: technology)
19415. Telecommunications      (API value: telecommunications)
19516. Sport & Recreation      (API value: sport_and_recreation)
19617. Real Estate             (API value: real_estate)
19718. Retail                  (API value: retail)
19819. Other                   (API value: other)
199```
200 
201> ⚠️ **Do NOT pick a default industry or hardcode a value. Always ask the user.** This is required by Anthropic's terms of service. The industry list is static — there is no REST API that provides it.
202 
203Store selection as `SELECTED_INDUSTRY` (use the API value, e.g., `technology`).
204 
205**Step 2: Fetch tenant info (country code and organization name)**
206 
207```bash
208TENANT_INFO=$(az rest --method GET \
209  --url "https://management.azure.com/tenants?api-version=2024-11-01" \
210  --query "value[0].{countryCode:countryCode, displayName:displayName}" -o json)
211 
212COUNTRY_CODE=$(echo "$TENANT_INFO" | jq -r '.countryCode')
213ORG_NAME=$(echo "$TENANT_INFO" | jq -r '.displayName')
214```
215 
216*PowerShell version:*
217```powershell
218$tenantInfo = az rest --method GET `
219  --url "https://management.azure.com/tenants?api-version=2024-11-01" `
220  --query "value[0].{countryCode:countryCode, displayName:displayName}" -o json | ConvertFrom-Json
221 
222$countryCode = $tenantInfo.countryCode
223$orgName = $tenantInfo.displayName
224```
225 
226Store `COUNTRY_CODE` and `ORG_NAME` for use in Phase 13.
227 
228---
229 
230## Phase 8: Select RAI Policy (Content Filter)
231 
232> ⚠️ **Note:** RAI policies only apply to OpenAI models. Skip this phase if `MODEL_FORMAT != "OpenAI"` (Anthropic, Meta-Llama, Mistral, Cohere, etc. do not use RAI policies).
233 
234Present options:
2351. `Microsoft.DefaultV2` — Balanced filtering (recommended). Filters hate, violence, sexual, self-harm.
2362. `Microsoft.Prompt-Shield` — Enhanced prompt injection/jailbreak protection.
2373. Custom policies — Organization-specific (configured in Azure Portal).
238 
239Default: `Microsoft.DefaultV2`.
240 
241---
242 
243## Phase 9: Configure Advanced Options
244 
245Options are SKU-dependent:
246 
247**A. Dynamic Quota** (GlobalStandard only)
248- Auto-scales beyond base allocation when capacity available
249- Default: enabled
250 
251**B. Priority Processing** (ProvisionedManaged only)
252- Prioritizes requests during high load; additional charges apply
253- Default: disabled
254 
255**C. Spillover** (any SKU)
256- Redirects requests to backup deployment at capacity
257- Requires existing deployment; list with:
258```bash
259az cognitiveservices account deployment list \
260  --name $ACCOUNT_NAME \
261  --resource-group $RESOURCE_GROUP \
262  --query "[].name" -o json
263```
264- Default: disabled
265 
266---
267 
268## Phase 10: Configure Version Upgrade Policy
269 
270> ⚠️ **Note:** Version upgrade policies only apply to OpenAI models. Skip this phase if `MODEL_FORMAT != "OpenAI"`.
271 
272| Policy | Description |
273|--------|-------------|
274| `OnceNewDefaultVersionAvailable` | Auto-upgrade to new default (Recommended) |
275| `OnceCurrentVersionExpired` | Upgrade only when current expires |
276| `NoAutoUpgrade` | Manual upgrade only |
277 
278Default: `OnceNewDefaultVersionAvailable`.
279 
280---
281 
282## Phase 11: Generate Deployment Name
283 
284List existing deployments to avoid conflicts:
285```bash
286az cognitiveservices account deployment list \
287  --name $ACCOUNT_NAME \
288  --resource-group $RESOURCE_GROUP \
289  --query "[].name" -o json
290```
291 
292Auto-generate: use model name as base, append `-2`, `-3` etc. if taken. Allow custom override. Validate: `^[\w.-]{2,64}$`.
293 
294---
295 
296## Phase 12: Review Configuration
297 
298Display summary of all selections for user confirmation before proceeding:
299- Model, version, deployment name
300- SKU, capacity (with unit), region
301- RAI policy, version upgrade policy
302- Advanced options (dynamic quota, priority, spillover)
303- Account, resource group, project
304 
305User confirms or cancels.
306 
307---
308 
309## Phase 13: Execute Deployment
310 
311> 💡 `MODEL_FORMAT` was already detected in Phase 4. Use the stored value here.
312 
313### Standard CLI deployment (non-Anthropic models):
314 
315**Create deployment:**
316```bash
317az cognitiveservices account deployment create \
318  --name $ACCOUNT_NAME \
319  --resource-group $RESOURCE_GROUP \
320  --deployment-name $DEPLOYMENT_NAME \
321  --model-name $MODEL_NAME \
322  --model-version $MODEL_VERSION \
323  --model-format "$MODEL_FORMAT" \
324  --sku-name $SELECTED_SKU \
325  --sku-capacity $DEPLOY_CAPACITY
326```
327 
328> 💡 **Note:** For non-OpenAI MaaS models, `$DEPLOY_CAPACITY` is `1` (set in Phase 7).
329 
330### Anthropic model deployment (requires modelProviderData):
331 
332The Azure CLI does not support `--model-provider-data`. Use the ARM REST API directly.
333 
334> ⚠️ Industry, country code, and organization name should have been collected in Phase 7c.
335 
336```bash
337echo "Creating Anthropic model deployment via REST API..."
338 
339az rest --method PUT \
340  --url "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.CognitiveServices/accounts/$ACCOUNT_NAME/deployments/$DEPLOYMENT_NAME?api-version=2024-10-01" \
341  --body "{
342    \"sku\": {
343      \"name\": \"$SELECTED_SKU\",
344      \"capacity\": 1
345    },
346    \"properties\": {
347      \"model\": {
348        \"format\": \"Anthropic\",
349        \"name\": \"$MODEL_NAME\",
350        \"version\": \"$MODEL_VERSION\"
351      },
352      \"modelProviderData\": {
353        \"industry\": \"$SELECTED_INDUSTRY\",
354        \"countryCode\": \"$COUNTRY_CODE\",
355        \"organizationName\": \"$ORG_NAME\"
356      }
357    }
358  }"
359```
360 
361*PowerShell version:*
362```powershell
363Write-Host "Creating Anthropic model deployment via REST API..."
364 
365$body = @{
366    sku = @{
367        name = $SELECTED_SKU
368        capacity = 1
369    }
370    properties = @{
371        model = @{
372            format = "Anthropic"
373            name = $MODEL_NAME
374            version = $MODEL_VERSION
375        }
376        modelProviderData = @{
377            industry = $SELECTED_INDUSTRY
378            countryCode = $countryCode
379            organizationName = $orgName
380        }
381    }
382} | ConvertTo-Json -Depth 5
383 
384az rest --method PUT `
385  --url "https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.CognitiveServices/accounts/$ACCOUNT_NAME/deployments/${DEPLOYMENT_NAME}?api-version=2024-10-01" `
386  --body $body
387```
388 
389> 💡 **Note:** Anthropic models use `capacity: 1` (MaaS billing model), not TPM-based capacity. RAI policy is not applicable for Anthropic models.
390 
391### Monitor deployment status:
392```bash
393az cognitiveservices account deployment show \
394  --name $ACCOUNT_NAME \
395  --resource-group $RESOURCE_GROUP \
396  --deployment-name $DEPLOYMENT_NAME \
397  --query "properties.provisioningState" -o tsv
398```
399 
400Poll until `Succeeded` or `Failed`. Timeout after 5 minutes.
401 
402**Get endpoint:**
403```bash
404az cognitiveservices account show \
405  --name $ACCOUNT_NAME \
406  --resource-group $RESOURCE_GROUP \
407  --query "properties.endpoint" -o tsv
408```
409 
410On success, display deployment name, model, version, SKU, capacity, region, RAI policy, rate limits, endpoint, and Azure AI Foundry portal link.
411