AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

azure-architecture-autopilot

Design Azure infrastructure using natural language, or analyze existing Azure resources to auto-generate architecture diagrams, refine them through conversation, and deploy with Bicep. When to use this skill: - "Create X on Azure", "Set up a RAG architecture" (new design) - "Analyze my current Azure infrastructure", "Draw a diagram for rg-xxx" (existing analysis) - "Foundry is slow", "I want to reduce costs", "Strengthen security" (natural language modification) - Azure resource deployment, Bicep template generation, IaC code generation - Microsoft Foundry, AI Search, OpenAI, Fabric, ADLS Gen2, Databricks, and all Azure services

Original source
github
License
MIT
Pinned revision
5269f7ea2d6c3a9bfda5ed878b6726cf509121fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read github--azure-architecture-autopilot at revision 5269f7ea2d6c3a9bfda5ed878b6726cf509121fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 11

references/phase1-advisor.md · 24000

y | | | front_door | Microsoft.Cdn/profiles (Front Door) | Front Door | | | vpn | Microsoft.Network/virtualNetworkGateways | VPN Gateway | | | load_balancer | Microsoft.Network/loadBalancers | Load Balancer | | | nat_gateway | Microsoft.Network/natGateways | NAT Gateway | | | cdn | Microsoft.Cdn/profiles | CDN | | IoT | iot_hub | Microsoft.Devices/IotHubs | IoT Hub | | | digital_twins | Microsoft.DigitalTwins/digitalTwinsInstances | Digital Twins | | Integration | event_hub | Microsoft.EventHub/namespaces | Event Hub | | | event_grid | Microsoft.EventGrid/topics | Event Grid | | | apim | Microsoft.ApiManagement/service | API Management | | | service_bus | Microsoft.ServiceBus/namespaces | Service Bus | | | logic_apps | Microsoft.Logic/workflows | Logic Apps | | Monitoring | log_analytics | Microsoft.OperationalInsights/workspaces | Log Analytics | | | appinsights | Microsoft.Insights/components | App Insights | | | monitor | Azure Monitor | Monitor | | Other | jumpbox, user, devops | — | Special |

When Using Private Endpoints — PE Node Addition Required:

If Private Endpoints are included in the architecture, a PE node MUST be added to the services JSON for each service, and connections must also include the PE links for them to appear in the diagram.

// Add PE node corresponding to each service
{"id": "pe_serviceID", "name": "PE: ServiceName", "type": "pe", "details": ["groupId: correspondingGroupID"]}

// Add service → PE connection in connections
{"from": "serviceID", "to": "pe_serviceID", "label": "", "type": "private"}

🚨🚨🚨 PE Connections and Business Logic Connections Are Separate — BOTH MUST Be Included 🚨🚨🚨

PE connections ("type": "private") represent network isolation. But this alone does NOT show the actual data flow/API calls between services in the diagram.

MUST include both types of connections:

  1. Business logic connections — Actual data flow between services (api, data, security types)
  2. PE connections — Network isolation between service ↔ PE (private type)
// ✅ Correct example — Function App → Foundry
// 1) Business logic: Function App calls Foundry for chat/embedding
{"from": "func_app", "to": "foundry", "label": "RAG Chat + Embedding", "type": "api"}
// 2) PE connection: Foundry's Private Endpoint
{"from": "foundry", "to": "pe_foundry", "label": "", "type": "private"}

// ❌ Wrong example — Only PE connection, no business logic connection
{"from": "foundry", "to": "pe_foundry", "label": "", "type": "private"}
// → No connection line between Function App and Foundry in the diagram, so the architecture flow is not visible

NEVER do this:

  • Create only PE connections and omit business logic connections
  • Connect from/to of business logic connections to PE nodes (use the actual service ID, not the PE)
  • Assume "the PE is there so the connection line will show up"

The PE groupId differs by service. Refer to the PE groupId & DNS Zone mapping table in references/service-gotchas.md.

Service naming convention: MUST use the latest official Azure names. If uncertain about the name, verify with MS Docs. For resource types and key properties per service, refer to references/ai-data.md.

connections JSON format:

[
  {"from": "serviceA_ID", "to": "serviceB_ID", "label": "Connection description", "type": "api|data|security|private"}
]

Connection Types:

| type | Color | Style | Use For | |------|-------|-------|---------| | api | Blue | Solid | API calls, queries | | data | Green | Solid | Data flow, indexing | | security | Orange | Dashed | Secrets, auth | | private | Purple | Dashed | Private Endpoint connections | | network | Gray | Solid | Network routing | | default | Gray | Solid | Other |

🔹 Diagram Multilingual Principle:

  • The name, details in services and label in connections are written in the user's language
  • Example: "label": "RAG Search", "label": "Data Ingestion"
  • Official Azure service names (Microsoft Foundry, AI Search, etc.) are always in English regardless of language

🔹 VNet Node — Do NOT add to services JSON:

  • VNet is automatically displayed as a purple dashed boundary in the diagram (when PEs are present)
  • Adding a separate VNet node to services JSON causes confusion by duplicating with the boundary line
  • VNet information (CIDR, subnets) is sufficiently conveyed through the sidebar VNet boundary label

Provide the full path of the generated HTML file to the user.

1-3. Finalizing Architecture Through Conversation

The architecture is finalized incrementally through conversation with the user. When the user requests changes, do NOT ask everything from scratch; instead, reflect only the requested changes based on the current confirmed state and regenerate the diagram.

⚠️ Delta Confirmation Rule — Required Verification on Service Addition/Change:

Service addition/change is not a "simple update" — it is an event that reopens undecided required fields for that service.

Process:

  1. Diff the current confirmed state + new request
  2. Identify the required fields for newly added services (refer to domain-packs or MS Docs)
  3. Fetch the region availability/options for the service from MS Docs
  4. If any required fields are undecided, ask the user via ask_user first
  5. Regenerate the diagram only after confirmation is complete

NEVER do this:

  • Finalize diagram update while required fields remain undecided
  • Arbitrarily add sub-components/workloads the user did not mention (e.g., automatically adding OneLake and data pipeline to a Fabric request)
  • Vaguely assume SKU/model like "F SKU" without confirmation

Do not re-ask settings for already confirmed services. Only confirm undecided items for newly added/changed services.


🚨🚨🚨 [Top Priority Principle] Immediate Fact Check During Design Phase 🚨🚨🚨

The purpose of Phase 1 is to confirm a "feasible architecture". No matter what the user requests, before reflecting it in the diagram, you MUST fact-check whether it is actually possible by directly querying MS Docs via web_fetch.

Design Direction vs Deployment Specs — Separate Information Paths:

| Decision Type | Reference Path | Examples | |--------------|----------------|----------| | Design direction (architecture patterns, best practices, service combinations) | references/architecture-guidance-sources.md → targeted fetch | "What's the recommended RAG structure?", "Enterprise baseline?" | | Deployment specs (API version, SKU, region, model, PE mapping) | references/azure-dynamic-sources.md → MS Docs fetch | "What's the API version?", "Is this model available in Korea Central?" |

  • Design direction comes from architecture guidance, actual deployment values from dynamic sources. Do not mix these two paths.
  • Do NOT use Architecture guidance document content to determine SKU/API version/region.
  • Do NOT crawl through all Architecture Center sub-documents for every request. Perform trigger-based targeted fetch of at most 2 relevant documents.
  • For trigger/fetch budget/decision rules by question type, refer to architecture-guidance-sources.md.

This principle applies to ALL requests without exception:

  • Model addition/change → Verify in MS Docs whether the model exists and can be deployed in the target region
  • Service addition/change → Verify in MS Docs whether the service is available in the target region
  • SKU change → Verify in MS Docs whether the SKU is valid and supports the desired features
  • Feature request → Verify in MS Docs whether the feature is actually supported
  • Service combination → Verify in MS Docs whether inter-service integration is possible
  • Any other request → Fact-check with MS Docs

MS Docs verification results:

  • Possible → Reflect in diagram
  • Not possible → Immediately explain the reason to the user and suggest available alternatives

Fact Check Process — Cross-Verification Required:

Do not simply query once and move on for user requests. Cross-verification using other MS Docs pages/sources MUST always be performed.

GHCP Environment Constraint: Sub-agents (explore/task/general-purpose) do NOT have web_fetch/web_search tools. Therefore, verification requiring MS Docs queries MUST be performed directly by the main agent.

[1st Verification] Main agent directly queries MS Docs via web_fetch (primary page)
    ↓
[2nd Verification] Main agent additionally fetches other/related MS Docs pages via web_fetch for cross-checking
    - e.g., Model availability → 1st: models page / 2nd: regional availability or pricing page
    - e.g., API version → 1st: Bicep reference page / 2nd: REST API reference page
    - Compare 1st and 2nd results and flag any discrepancies
    ↓
[Consolidate Results] If both verifications match, respond to the user
    - On discrepancy: Resolve with additional queries, or honestly inform the user about the uncertainty

Fact Check Quality Standards — Be Thorough, Not Cursory:

  • When a MS Docs page is fetched, check ALL relevant sections, tabs, and conditions without omission
  • When checking model availability: Check ALL deployment types including Global Standard, Standard, Provisioned, Data Zone, etc. Do NOT conclude "not supported" based on only one deployment type
  • When checking SKUs: Fully verify the feature list supported by that SKU
  • If the page is large, fetch relevant sections multiple times to ensure accuracy
  • If uncertain, query additional pages. NEVER answer based on guesswork

NEVER do this:

  • Add to the diagram without verification
  • Defer verification with "I'll check during Bicep generation" or "It will be validated during deployment"
  • Rely only on your memory and answer "it should work" — MUST directly query MS Docs
  • Fetch MS Docs but rush to conclusions after only partially reading
  • Finalize based on a single query — MUST cross-verify with another source

🚫 Sub-Agent Usage Rules:

Sub-agents in GHCP = task tool:

  • agent_type: "explore" — Read-only tasks like codebase exploration, file search (web_fetch/web_search NOT available)
  • agent_type: "task" — Command execution like az cli, bicep build
  • agent_type: "general-purpose" — High-level tasks like complex Bicep generation

⚠️ Sub-agent tool constraint: ALL sub-agents (explore/task/general-purpose) CANNOT use web_fetch or web_search. Fact checks requiring MS Docs queries, API version verification, model availability checks, etc. MUST be performed directly by the main agent.

Foreground vs Background Decision Criteria:

  • If results are needed before proceeding to the next step → mode: "sync" (default)
    • e.g., Query SKU list then provide choices to user, verify model availability then reflect in diagram
    • Running in background here would leave the user idle waiting for results
  • If there is other independent work that can be done while waiting for results → mode: "background"
    • e.g., Simultaneously web_fetch multiple MS Docs pages for cross-verification

Most fact checks should be run in foreground (mode: "sync") because the next question cannot be asked without the results.

How to run cross-verification in parallel:

// Execute 1st and 2nd verification simultaneously (main agent performs directly)
[Simultaneously] Directly query primary MS Docs page via web_fetch (1st)
[Simultaneously] Additionally query related MS Docs page via web_fetch (2nd)
// Compare both results to check for discrepancies
// e.g., Model availability → parallel fetch of models page + regional availability page

NEVER do this:

  • Run in background when results are needed, then sit idle doing nothing while waiting
  • Delegate tasks requiring web_fetch/web_search to sub-agents (main agent MUST perform directly)
  • Attempt to directly read files internal to sub-agents

⚠️ Important: Do NOT execute any shell commands until the user explicitly approves proceeding to the next step. However, MS Docs web_fetch for the above fact checks is exceptionally allowed.

Once the architecture is confirmed (user said no changes to the diagram), ask the user whether to proceed to the next step.

🚨 Phase 2 Transition Prerequisites — ALL of the following must be met before asking this question:

  1. 01_arch_diagram_draft.html has been generated using the built-in diagram engine
  2. The diagram has been opened in the browser and displayed to the user in the report format with the configuration table
  3. The user was asked "Would you like to change or add anything?" and responded with no changes, or modifications have been reflected and final confirmation is given

If ANY of the above conditions are not met, do NOT proceed to Phase 2. If the diagram does not exist yet, generate it right now — follow the procedure in section 1-2. If the configuration table was not shown, show it right now before asking about changes.

Following the parallel preload principle, execute az account list and az group list simultaneously with ask_user to prepare subscription/RG choices in advance.

// Call simultaneously in the same response:
[1] ask_user — "The architecture is confirmed! Shall we proceed to the next step?"
[2] powershell — az account show 2>&1              (pre-check login status)
[3] powershell — az account list --output json      (pre-prepare subscription choices)
[4] powershell — az group list --output json        (pre-prepare resource group choices)

ask_user display format:

The architecture is confirmed! Shall we proceed to the next step?

✅ Confirmed architecture: [summary]

The following steps will proceed:
1. [Bicep Code Generation] — AI automatically writes IaC code
2. [Code Review] — Automated security/best practice review
3. [Azure Deployment] — Actual resource creation (optional)

Shall we proceed? (If you'd like just the code without deployment, let me know)

Once the user approves, collect information in the following order. Since az account show + az account list + az group list were already completed during preload, subscription/RG choices can be presented immediately.

Step 1: Azure Login Verification

The az account show result is already available from preload. No additional call needed.

  • If logged in → Move to Step 2
  • If not logged in → Guide the user:
    Azure CLI login is required. Please run the following command in your terminal:
    az login
    Please let me know once completed.
    

Step 2: Subscription Selection

The az account list result is already available from preload. No additional call needed.

Provide up to 4 subscriptions from the query results as ask_user choices. If there are 5 or more, include the 3-4 most frequently used subscriptions as choices (users can also type a custom input). Once the user selects, execute az account set --subscription "<ID>".

Step 3: Resource Group Confirmation

The az group list result is already available from preload. No additional call needed.

Provide up to 4 existing resource groups from the list as ask_user choices. If the user selects an existing group, use it as-is; if they type a new name as custom input, create it during Phase 4 deployment.

Required confirmed items:

  • [ ] Service list and SKUs
  • [ ] Networking method (Private Endpoint usage)
  • [ ] Subscription ID (confirmed in Step 2)
  • [ ] Resource group name (confirmed in Step 3)
  • [ ] Location (confirmed with user — regional availability per service verified via MS Docs)

🚨 Phase 1 Completion Checklist — Required Verification Before Phase 2 Entry

Before leaving Phase 1, verify ALL items below. If any are incomplete, do NOT proceed to Phase 2.

| # | Item | Verification Method | |---|------|---------------------| | 1 | All required specs confirmed | Project name, services, SKUs, region, and networking method are all confirmed | | 2 | Fact check completed | MS Docs cross-verification has been performed | | 3 | Diagram generated | 01_arch_diagram_draft.html file has been generated using the built-in diagram engine | | 4 | Configuration table shown | Detailed table with Service/Type/SKU/Details displayed to user in report format | | 5 | User reviewed diagram | Browser auto-open + report format + "anything to change?" question asked | | 6 | User final approval | User confirmed no changes, then selected "proceed to next step" |

⚠️ Do NOT ask item 6 while items 3-5 are incomplete. The flow must be: diagram → table → ask changes → confirm → next step.


Phase 2 Handoff: Bicep Generation Agent

Once the user agrees to proceed, read the references/bicep-generator.md instructions and generate the Bicep template. Alternatively, this can be delegated to a separate sub-agent.

Sensitive Information Handling Principle (NEVER violate):

  • NEVER ask for VM passwords, API keys, or other sensitive values in chat, and NEVER store them in parameter files
  • During code review, if sensitive values are found in plaintext in main.bicepparam, remove them immediately

🔹 User-Input Sensitive Values Like VM Passwords — Complexity Validation Required:

When the user inputs a VM admin password or similar, validate complexity requirements before sending to Azure. Azure VMs must satisfy ALL of the following conditions:

  • 12 characters or more
  • Contains at least 3 of: uppercase letters, lowercase letters, numbers, special characters

On validation failure: Do NOT attempt deployment; immediately ask the user to re-enter:

⚠️ The password does not meet Azure complexity requirements. It must be 12 characters or more and contain at least 3 of: uppercase + lowercase + numbers + special characters.

NEVER do this:

  • Warn "it may not meet requirements" but attempt deployment anyway — MUST block
  • Send to Azure without complexity validation, causing deployment failure

🚨 @secure() Parameter and .bicepparam Compatibility Principle:

When a .bicepparam file has a using './main.bicep' directive, additional --parameters flags CANNOT be used together with az deployment group what-if/create. Therefore, @secure() parameter handling follows these rules:

  1. @secure() parameters MUST have default values — Use Bicep functions like newGuid(), uniqueString()
    @secure()
    param sqlAdminPassword string = newGuid()  // Auto-generated at deployment, store in Key Vault if needed
    
  2. If there are @secure() parameters that require user-specified values:
    • Do NOT use .bicepparam file; instead use --template-file + --parameters combination
    • Or generate a separate JSON parameter file (main.parameters.json)
    # When .bicepparam cannot be used — substitute with JSON parameter file
    az deployment group what-if `
      --template-file main.bicep `
      --parameters main.parameters.json `
      --parameters sqlAdminPassword='user-input-value'
    
  3. Do NOT use .bicepparam and --parameters simultaneously in a deployment command
    ❌ az deployment group create --parameters main.bicepparam --parameters key=value
    ✅ az deployment group create --parameters main.bicepparam
    ✅ az deployment group create --template-file main.bicep --parameters main.parameters.json --parameters key=value
    

Decision criteria:

  • All @secure() parameters have default values (newGuid, etc.) → .bicepparam can be used
  • Any @secure() parameter requires user input → Use JSON parameter file instead of .bicepparam

When MS Docs fetch fails:

  • If web_fetch fails due to rate limiting, etc., MUST notify the user:
    ⚠️ MS Docs API version lookup failed. Generating with the last known stable version.
    Verifying the actual latest version before deployment is recommended.
    Shall we continue?
    
  • Do NOT silently proceed with a hardcoded version without user approval

Pre-Bicep generation reference files:

  • references/service-gotchas.md — Required properties, common mistakes, PE groupId/DNS Zone mapping
  • references/ai-data.md — AI/Data service configuration guide (v1 domain)
  • references/azure-common-patterns.md — PE/security/naming common patterns
  • references/azure-dynamic-sources.md — MS Docs URL registry (for API version fetch)
  • For services not covered in the above files, directly fetch MS Docs to verify resource types, properties, and PE mappings

Output structure:

<project-name>/
├── main.bicep              # Main orchestration
├── main.bicepparam         # Parameters (environment-specific values)
└── modules/
    ├── network.bicep       # VNet, Subnet (including private endpoint subnet)
    ├── ai.bicep            # AI services (configured per user requirements)
    ├── storage.bicep       # ADLS Gen2 (isHnsEnabled: true)
    ├── fabric.bicep        # Microsoft Fabric (if needed)
    ├── keyvault.bicep      # Key Vault
    └── private-endpoints.bicep  # All PEs + DNS Zones

Bicep mandatory principles:

  • Parameterize all resource names — param openAiName string = 'oai-${uniqueString(resourceGroup().id)}'
  • Private services MUST have publicNetworkAccess: 'Disabled'
  • Set privateEndpointNetworkPolicies: 'Disabled' on pe-subnet
  • Private DNS Zone + VNet Link + DNS Zone Group — all 3 required
  • When using Microsoft Foundry, Foundry Project (accounts/projects) MUST be created alongside — without it, the portal is unusable
  • ADLS Gen2 MUST have isHnsEnabled: true (omitting this creates a regular Blob Storage)
  • Store secrets in Key Vault, reference via @secure() parameters
  • Add English comments explaining the purpose of each section

Immediately transition to Phase 3 after generation is complete.


Phase 3 Handoff: Bicep Review Agent

Review according to references/bicep-reviewer.md instructions.

⚠️ Key Point: Do NOT just visually inspect and say "pass". You MUST run az bicep build to verify actual compilation results.

az bicep build --file main.bicep 2>&1
  1. Compilation errors/warnings → Fix
  2. Checklist review → Fix
  3. Re-compile to confirm
  4. Report results (including compilation results)

For detailed checklists and fix procedures, see references/bicep-reviewer.md.

After review is complete, show the user the results before transitioning to Phase 4, and MUST guide the user on the next steps.

🚨 Required Report Format When Phase 3 Is Complete:

## Bicep Code Review Complete

[Review result summary — bicep-reviewer.md Step 6 format]

---

**Next Step: Phase 4 (Azure Deployment)**

The review is complete. The following steps will proceed:
1. **What-if Validation** — Preview planned resources without making actual changes
2. **Preview Diagram** — Architecture visualization based on What-if results (02_arch_diagram_preview.html)
3. **Actual Deployment** — Create resources in Azure after user confirmation

Shall we proceed with deployment? (If you'd like just the code without deployment, let me know)

NEVER do this:

  • Completing Phase 3 and just providing the az deployment group create command without further guidance
  • Deploying directly without What-if validation, or telling the user to run commands themselves
  • Skipping the Phase 4 steps (What-if → Preview Diagram → Deployment)