Phase4 Deployer

Never do the following:

• Execute az deployment group create directly without What-if
• Skip generating the preview diagram (02_arch_diagram_preview.html)
• Proceed with deployment without showing What-if results to the user
• Only provide az commands for the user to run manually

Step 1: Verify Prerequisites

If not logged in, ask the user to run az login. The agent must never enter or store credentials directly.

Create resource group:

→ Proceed to next step after confirming success

Step 2: Validate → What-if Validation — 🚨 Mandatory

Do not skip this step. Always execute it no matter how urgently the user requests deployment.

Step 2-A: Run Validate First (Quick Pre-validation)

what-if can hang indefinitely without error messages when there are Azure policy violations, resource reference errors, etc. To prevent this, always run validate first. Validate returns errors quickly.

• Validate succeeds → Proceed to Step 2-B (what-if)
• Validate fails → Analyze error messages, fix Bicep, recompile, re-validate
  • Azure Policy violation (RequestDisallowedByPolicy) → Reflect policy requirements in Bicep (e.g., azureADOnlyAuthentication: true)
  • Schema error → Fix API version/properties
  • Parameter error → Fix parameter file

Step 2-B: Run What-if

Run what-if after validate passes.

Choose parameter passing method:

• If all @secure() parameters have default values → Use .bicepparam
• If @secure() parameters require user input → Use --template-file + JSON parameter file

→ Summarize the What-if results and present them to the user.

⏱️ What-if Execution Method and Timeout Handling:

What-if performs resource validation on the Azure server side, so it may take time depending on the service/region. Always execute with initial_wait: 300 (5 minutes). If not completed within 5 minutes, it automatically times out.

Completed within 5 minutes → Proceed normally (summarize results → preview diagram → deployment confirmation)

Not completed within 5 minutes (timeout) → Immediately stop with stop_powershell and offer choices to the user:

If “Retry” is selected: Re-execute the same command with initial_wait: 300. Retry up to 2 times maximum. If “Skip What-if and deploy directly” is selected:

• Generate the preview diagram based on the Phase 1 draft
• Inform the user of the risks:

  ⚠️ Deploying without What-if validation. Unexpected resource changes may occur. Please verify in the Azure Portal after deployment.

Never do the following:

• Execute without setting initial_wait, causing indefinite waiting
• Let the agent arbitrarily decide “what-if is optional” and skip it
• Automatically switch to deployment without asking the user on timeout
• Skip what-if for reasons like “deployment is faster”

Step 3: Preview Diagram Based on What-if Results — 🚨 Mandatory

Do not skip this step. Always generate the preview diagram when What-if succeeds.

Regenerate the diagram using the actual resources to be deployed (resource names, types, locations, counts) from the What-if results. Keep the draft from Phase 1 (01_arch_diagram_draft.html) as-is, and generate the preview as 02_arch_diagram_preview.html. The draft can be reopened at any time.

Proceed to Step 4 when the user confirms. Do not proceed to deployment without the preview diagram.

Step 4: Actual Deployment

Execute only when the user has reviewed the preview diagram and What-if results and approved the deployment. Use the same parameter passing method used in What-if.

Periodically monitor progress during deployment:

Handling Deployment Failures

When deployment fails, some resources may remain in a ‘Failed’ state. Redeploying in this state causes errors like AccountIsNotSucceeded.

⚠️ Resource deletion is a destructive command. Always explain the situation to the user and obtain approval before executing.

Delete failed resources and redeploy once the user approves.

🔹 Handling Soft-deleted Resources (Prevent Redeployment Blocking):

When a resource group is deleted after a failed deployment, Cognitive Services (Foundry), Key Vault, etc. remain in a soft-delete state. Redeploying with the same name causes FlagMustBeSetForRestore, Conflict errors.

Always check before redeployment:

Resolution options (provide choices to the user):

Caution — Key Vault with enablePurgeProtection: true:

• Cannot be purged (must wait until retention period expires)
• Cannot recreate with the same name
• Solution: Change the Key Vault name and redeploy (e.g., add timestamp to uniqueString() seed)
• Explain the situation to the user and guide them on the name change

Step 5: Deployment Complete — Generate Diagram from Actual Resources and Report

Once deployment is complete, query the actually deployed resources and generate the final architecture diagram.

Step 1: Query Deployed Resources

Step 2: Generate Diagram from Actual Resources

Extract resource names, types, SKUs, and endpoints from the query results and generate the final diagram using the built-in diagram engine. Be careful with file names to avoid overwriting previous diagrams:

• 01_arch_diagram_draft.html — Design draft (keep)
• 02_arch_diagram_preview.html — What-if preview (keep)
• 03_arch_diagram_result.html — Deployment result final version

Populate the diagram’s services JSON with actual deployed resource information:

• name: Actual resource name (e.g., foundry-duru57kxgqzxs)
• sku: Actual SKU
• details: Actual values such as endpoints, location, etc.

Step 3: Report

Handling Architecture Change Requests After Deployment

When the user requests resource additions/changes/deletions after deployment is complete, do NOT go directly to Bicep/deployment. Always return to Phase 1 and update the architecture first.

Process:

1. Confirm user intent — Ask first whether they want to add to the existing deployed architecture:

   Copy

   Would you like to add a VM to the currently deployed architecture?
   Current configuration: [Deployed services summary]

2. Return to Phase 1 — Apply Delta Confirmation Rule

   • Use the existing deployment result (03_arch_diagram_result.html) as the current state baseline
   • Verify required fields for new services (SKU, networking, region availability, etc.)
   • Confirm undecided items via ask_user
   • Fact-check (MS Docs fetch + cross-validation)

3. Generate Updated Architecture Diagram

   • Combine existing deployed resources + new resources into 04_arch_diagram_update_draft.html
   • Show to the user and get confirmation:

   Copy

   ## Updated Architecture
   
   [Interactive diagram — 04_arch_diagram_update_draft.html]
   (Previous deployment result: 03_arch_diagram_result.html)
   
   **Changes:**
   - Added: [New services list]
   - Removed: [Removed services list] (if any)
   
   Proceed with this configuration?

4. After confirmation, proceed through Phase 2 → 3 → 4 in order

   • Incrementally add new resource modules to existing Bicep
   • Review → What-if → Deploy (incremental deployment)

Never do the following:

• Jump directly to Bicep generation without updating the architecture diagram when a change is requested after deployment
• Ignore the existing deployment state and create new resources in isolation
• Proceed without confirming with the user whether to add to the existing architecture