Azure Architecture Autopilot

Phase 0: Existing Resource Scanner

This file contains the detailed instructions for Phase 0. When the user requests analysis of existing Azure resources (Path B), read and follow this file.

Scan results are visualized as an architecture diagram, and subsequent natural-language modification requests from the user are routed to Phase 1.

🚨 Output Storage Path Rule: All outputs (scan JSON, diagram HTML, Bicep code) must be saved in a project folder under the current working directory (cwd). NEVER save them inside ~/.copilot/session-state/. The session-state directory is a temporary space and may be deleted when the session ends.

Step 1: Azure Login + Scan Scope Selection

1-A: Verify Azure Login

az account show 2>&1

• If logged in → Proceed to Step 1-B

• If not logged in → Ask the user to run az login

1-B: Subscription Selection (Multiple Selection Supported)

az account list --output json

Present the subscription list as ask_user choices. Multiple subscriptions can be selected:

ask_user({
  question: "Please select the Azure subscription(s) to analyze. (You can add more one at a time for multiple selections)",
  choices: [
    "sub-002 (Current default subscription) (Recommended)",
    "sub-001",
    "Analyze all subscriptions above"
  ]
})

• Single subscription selected → Scan only that subscription

• "Analyze all" selected → Scan all subscriptions

• If the user wants additional subscriptions → Use ask_user again to add more

1-C: Scan Scope Selection (Multiple RG Selection Supported)

ask_user({
  question: "What scope of Azure resources would you like to analyze?",
  choices: [
    "Specify a particular resource group (Recommended)",
    "Select multiple resource groups",
    "All resource groups in the current subscription"
  ]
})

• Specific RG → Select from the RG list or enter manually

• Multiple RGs → Repeat ask_user to add RGs one at a time. Stop when the user says "that's enough." Alternatively, the user can enter multiple RGs separated by commas (e.g., rg-prod, rg-dev, rg-network)

• Entire subscription → az group list → Scan all RGs (warn if there are many resources that it may take time)

Combining multiple subscriptions + multiple RGs is supported:

• rg-prod from subscription A + rg-network from subscription B → Scan both and display in a single diagram

Diagram Hierarchy — Displaying Multiple Subscriptions/RGs

Single subscription + single RG: Same as before (VNet boundary only) Multiple RGs (same subscription): Dashed boundary per RG Multiple subscriptions: Two-level boundary of Subscription > RG

Pass hierarchy information in the diagram JSON:

Add subscription and resourceGroup fields to the services JSON:

{
  "id": "foundry",
  "name": "foundry-xxx",
  "type": "ai_foundry",
  "subscription": "sub-002",
  "resourceGroup": "rg-prod",
  "details": [...]
}

Pass hierarchy information via the --hierarchy parameter:

--hierarchy '[{"subscription":"sub-002","resourceGroups":["rg-prod","rg-dev"]},{"subscription":"sub-001","resourceGroups":["rg-network"]}]'

Based on this information, the diagram script will:

• Multiple RGs → Represent each RG as a cluster with a dashed boundary (label: RG name)

• Multiple subscriptions → Nest RG boundaries inside larger subscription boundaries

• VNet boundaries are displayed inside the RG to which the VNet belongs

Step 2: Resource Scan

🚨 az CLI Output Principles:

• az CLI output must always be saved to a file and then read with view. Direct terminal output may be truncated.

• Bundle no more than 3 az commands per PowerShell call. Bundling too many may cause timeouts.

• Use --query JMESPath to extract only the required fields and reduce output size.

# ✅ Correct approach — Save to file then read
az resource list -g "<RG>" --query "[].{name:name,type:type,kind:kind,location:location}" -o json | Set-Content -Path "$outDir/resources.json"

# ❌ Wrong approach — Direct terminal output (may be truncated)
az resource list -g "<RG>" -o json

2-A: List All Resources + Display to User

$outDir = "<project-name>/azure-scan"
New-Item -ItemType Directory -Path $outDir -Force | Out-Null

# Step 1: Basic resource list (name, type, kind, location)
az resource list -g "<RG>" --query "[].{name:name,type:type,kind:kind,location:location,id:id}" -o json | Set-Content "$outDir/resources.json"

🚨 Immediately after reading resources.json, you MUST display the full resource list table to the user:

📋 rg-<RG> Resource List (N resources)

┌─────────────────────────┬──────────────────────────────────────────────┬─────────────────┐
│ Name                    │ Type                                         │ Location        │
├─────────────────────────┼──────────────────────────────────────────────┼─────────────────┤
│ my-storage              │ Microsoft.Storage/storageAccounts             │ koreacentral    │
│ my-keyvault             │ Microsoft.KeyVault/vaults                    │ koreacentral    │
│ ...                     │ ...                                          │ ...             │
└─────────────────────────┴──────────────────────────────────────────────┴─────────────────┘

⏳ Retrieving detailed information...

Display this table first before proceeding to detailed queries. Do not make the user wait without knowing what resources exist.

2-B: Dynamic Detailed Query — Based on resources.json

Dynamically determine detailed query commands based on the resource types found in resources.json.

Do not use a hardcoded command list. Only execute commands for types that exist in resources.json, selected from the mapping table below.

Type → Detailed Query Command Mapping:

Dynamic Query Process:

1. Read resources.json

2. Extract the distinct values of the type field

3. Execute only the commands for matching types from the mapping table above (skip types not present)

4. If a type not in the mapping table is found → Use generic query: az resource show --ids "<ID>" --query "{name:name,sku:sku,kind:kind,location:location,properties:properties}" -o json

5. Execute commands in batches of 2-3 (do not run all at once)

2-C: Model Deployment Query (When Cognitive Services Exist)

# Query model deployments for each Cognitive Services resource
az cognitiveservices account deployment list --name "<NAME>" -g "<RG>" --query "[].{name:name,model:properties.model.name,version:properties.model.version,sku:sku.name}" -o json | Set-Content "$outDir/<NAME>-deployments.json"

2-D: NIC + Public IP Query (When VMs Exist)

az network nic list -g "<RG>" --query "[].{name:name,subnetId:ipConfigurations[0].subnet.id,privateIp:ipConfigurations[0].privateIPAddress,publicIpId:ipConfigurations[0].publicIPAddress.id}" -o json | Set-Content "$outDir/nics.json"
az network public-ip list -g "<RG>" --query "[].{name:name,ip:ipAddress,sku:sku.name}" -o json | Set-Content "$outDir/public-ips.json"

From the VNet:

• addressSpace.addressPrefixes → CIDR

• subnets[].name, subnets[].addressPrefix → Subnet information

• subnets[].privateEndpointNetworkPolicies → PE policies

Step 3: Inferring Relationships Between Resources

Automatically infer relationships (connections) between scanned resources to construct the connections JSON for the diagram.

Relationship Inference Rules

🚨 If there are insufficient connection lines, the diagram becomes meaningless. Infer as many relationships as possible.

Confirmed Inference (Directly verifiable from resource IDs/properties)

Reasonable Inference (Common patterns between services within the same RG)

User Confirmation After Inference

Show the inferred connection list to the user and request confirmation:

> **⏳ Relationships between resources have been inferred** — Please verify if the following are correct.

Inferred connections:
- Foundry → AI Search (RAG Search)
- Foundry → Storage (Data)
- VM → Foundry (API Call)
- Document Intelligence → Foundry (OCR/Extract)

Does this look correct? Let me know if you'd like to add or remove any connections.

Relationships That Cannot Be Inferred

There may be connections that cannot be inferred using the rules above. The user can freely add additional connections.

Model Deployment Query (When Foundry Resources Exist)

az cognitiveservices account deployment list --name "<FOUNDRY_NAME>" -g "<RG>" --query "[].{name:name,model:properties.model.name,version:properties.model.version,sku:sku.name}" -o json

Add each deployment's model name, version, and SKU to the Foundry node's details.

Step 4: services/connections JSON Conversion

Convert scan results into the input format for the built-in diagram engine.

Resource Type → Diagram type Mapping

services JSON Construction Rules

{
  "id": "resource name (lowercase, special characters removed)",
  "name": "actual resource name",
  "type": "determined from the mapping table above",
  "sku": "actual SKU (if available)",
  "private": true/false,  // true if a PE is connected
  "details": ["property1", "property2", ...]
}

Information to include in details:

• Endpoint URL

• SKU/tier details

• kind (AIServices, OpenAI, etc.)

• Model deployment list (Foundry)

• Key properties (isHnsEnabled, semanticSearch, etc.)

• Region

VNet Information → --vnet-info Parameter

If a VNet is found, display it in the boundary label via --vnet-info:

--vnet-info "10.0.0.0/16 | pe-subnet: 10.0.1.0/24 | <region>"

PE Node Generation

If PEs are found, add each PE as a separate node and connect it to the corresponding service with a private type:

{"id": "pe_<serviceId>", "name": "PE: <serviceName>", "type": "pe", "details": ["groupId: <groupId>", "<status>"]}

Step 5: Diagram Generation + Presentation to User

Diagram filename: <project-name>/00_arch_current.html

Use the scanned RG name as the default project name:

ask_user({
  question: "Please choose a project name. (This will be the folder name for scan results)",
  choices: ["<RG-name>", "azure-analysis"]
})

After generating the diagram, report:

## Current Azure Architecture

[Interactive Diagram — 00_arch_current.html]

Scanned Resources (N total):
[Summary table by resource type]

What would you like to change here?
- 🔧 Performance improvement ("it's slow", "increase throughput")
- 💰 Cost optimization ("reduce costs", "make it cheaper")
- 🔒 Security hardening ("add PE", "block public access")
- 🌐 Network changes ("separate VNet", "add Bastion")
- ➕ Add/remove resources ("add a VM", "delete this")
- 📊 Monitoring ("set up logs", "add alerts")
- 🤔 Diagnostics ("is this architecture OK?", "what's wrong?")
- Or just take the diagram and stop here

Step 6: Modification Conversation → Transition to Phase 1

When the user requests modifications, transition to Phase 1 (phase1-advisor.md). This is the Path B entry point, using the existing scan results as the baseline.

Natural Language Modification Request Handling — Clarifying Question Patterns

Ask clarifying questions to make the user's vague requests more specific:

🔧 Performance

💰 Cost

🔒 Security

🌐 Network

➕ Add/Remove Resources

📊 Monitoring/Operations

🔄 Migration/Changes

🤔 Diagnostics/Questions

Once modifications are finalized:

1. Apply Phase 1's Delta Confirmation Rule

2. Fact-check (cross-verify with MS Docs)

3. Generate updated diagram (01_arch_diagram_draft.html)

4. User confirmation → Proceed to Phases 2–4

Scan Performance Optimization

• If there are 50+ resources, warn the user: "There are many resources, so the scan may take some time."

• Run az resource list first to determine the resource count, then proceed with detailed queries

• Query key services first (Foundry, Search, Storage, KeyVault, VNet, PE), then collect only basic information for the rest via az resource show

• Keep the user informed of progress:

  ⏳ Scanning resources — M of N resources completed

Handling Unsupported Resources

For resource types not in the diagram type mapping:

• Display with default type (question mark icon)

• Include the resource name and type in details

• Show to the user, but do not attempt relationship inference