Agent Instructions for APIM Samples

This document provides AI agents with structured guidance for working with the Azure API Management (APIM) Samples repository.

Repository Purpose

This repository provides resources to deploy Azure API Management infrastructures and experiment with APIM policies. It offers:

• Infrastructures: Pre-built Azure architectures featuring APIM in various configurations
• Samples: Real-world policy examples that can be deployed to any supported infrastructure
• Shared Resources: Reusable Bicep modules, Python helpers, and policy templates

Accessibility Baseline

All repository contributions should treat accessibility as a first-class quality requirement.

• Use WCAG 2.0 AA as the default baseline for user-facing outputs, including documentation, web content, workbook/dashboard visuals, and presentation materials.
• Do not rely on color alone to convey meaning; pair color cues with labels, text, icons, or structure.
• Preserve or improve contrast and readability when editing existing assets.

Repository Structure

/
├── infrastructure/          # Azure infrastructure deployments
│   ├── afd-apim-pe/         # Azure Front Door + APIM with Private Endpoint
│   ├── apim-aca/            # APIM with Azure Container Apps
│   ├── appgw-apim/          # Application Gateway + APIM (VNet)
│   ├── appgw-apim-pe/       # Application Gateway + APIM with Private Endpoint
│   └── simple-apim/         # Basic APIM setup (fastest, lowest cost)
│
├── samples/                 # APIM policy samples
│   ├── _TEMPLATE/           # Template for creating new samples
│   ├── authX/               # Authentication and authorization
│   ├── authX-pro/           # Advanced auth with policy fragments
│   ├── azure-maps/          # Azure Maps integration
│   ├── aoai-v1-migration/   # Azure OpenAI v1 Migration on existing lab resources
│   ├── costing/             # APIM costing and showback
│   ├── dynamic-cors/        # Dynamic per-API CORS origin validation
│   ├── egress-control/      # Egress control via NVA routing
│   ├── general/             # Basic policy demonstrations
│   ├── inference-failover/  # AOAI model failover with LLM telemetry
│   ├── load-balancing/      # Backend pool load balancing
│   ├── oauth-3rd-party/     # OAuth 3rd-party (Spotify example)
│   └── secure-blob-access/  # Valet key pattern for blob storage
│
├── shared/                  # Reusable components
│   ├── apim-policies/       # Common APIM policy XML files
│   ├── bicep/modules/       # Versioned Bicep modules
│   ├── jupyter/             # Reusable Jupyter notebooks
│   └── python/              # Python helper modules
│
├── tests/                   # Unit tests for Python code
│   └── python/              # pytest-based tests
│
├── setup/                   # Environment setup scripts
├── assets/                  # Images and diagrams
└── .github/                 # CI/CD and Copilot instructions
    ├── agents/              # Custom agents for focused repository workflows
    ├── copilot-instructions.md
    └── skills/              # Agent skills for specialized tasks

Key Files in Each Sample/Infrastructure

Available Skills

Use these skills for specialized tasks. Skills are located in .github/skills/.

Available Agents

Use these custom agents for focused repository workflows. Agents are located in .github/agents/.

How to Use Skills

When a task matches a skill's domain, read the skill file first:

.github/skills/<skill-name>/SKILL.md

Skills provide templates, patterns, and step-by-step workflows.

Creating New Samples

Quick Process

1. Prefer the custom agent: Use .github/agents/apim-sample-creator.agent.md for end-to-end sample creation.
2. Read the skill: Load .github/skills/sample-creator/SKILL.md
3. Gather requirements: Sample name, description, supported infrastructures, learning objectives
4. Create folder: samples/<sample-name>/ unless the user explicitly requests another location
5. Create required files:
   • README.md - Follow the template structure
   • create.ipynb - Jupyter notebook with initialization, deployment, and verification cells
   • <domain>_helpers.py - Add a descriptive sample-local module when parsing, retries, sessions, persistence, command composition, or multi-step orchestration would otherwise live in notebook cells
   • main.bicep - Reference shared modules from shared/bicep/modules/; add sample-owned policy files under apim-policies/ and KQL queries under queries/ when needed
6. Update repo surfaces:
   • Root README.md sample table
   • docs/index.html sample cards and JSON-LD list
   • assets/APIM-Samples-Slide-Deck.html when sample inventory or descriptions are shown
   • tests/Test-Matrix.md
   • Compatibility diagrams when supported infrastructures change visually

Sample Addition Requirements

• Ask the user for the sample name if it is not provided.
• Ask the user for supported infrastructures if they are not provided.
• Keep sample display names consistent across README tables, the website, the slide deck, and compatibility artifacts.
• If a broadly useful improvement is discovered while creating a sample, suggest updating samples/_TEMPLATE so future samples inherit it.

Publishing a Sample

Use .github/agents/apim-sample-publisher.agent.md after sample implementation is ready for a final quality pass. The publisher agent checks the working-tree diff, synchronizes README, website, SEO metadata and structured data, slideshow, matrix, and compatibility-diagram surfaces, runs the applicable linting and unit tests, exports the presentation, and reports any manual or live-Azure verification that remains.

Sample Naming Conventions

• Folder: kebab-case (e.g., oauth-validation, rate-limiting)
• API prefix: Short, unique, with trailing hyphen (e.g., oauth-, rl-)
• Policy files: Descriptive, kebab-case, and stored under samples/<sample-name>/apim-policies/ (e.g., token-validation.xml)
• Query files: Descriptive, kebab-case, and stored under samples/<sample-name>/queries/ (e.g., request-summary.kql)
• Workbook files: Azure Monitor Workbook JSON files use the <name>.workbook.json suffix (e.g., costing.workbook.json). One workbook per file, stored in the sample folder, loaded into Bicep via loadJsonContent('<name>.workbook.json'), and pushed back to Azure via a sample-local update-workbook.ps1. See the Azure Monitor Workbook File Convention section in .github/copilot-instructions.md.
• Admin APIs: Samples needing admin/operational endpoints use path {api_prefix}admin with subscriptionRequired=True and kebab-case operation paths (e.g., /load-cache)

Infrastructure Constants

Available in Python via from apimtypes import INFRASTRUCTURE:

Working with Existing Samples

Running a Sample

1. Ensure an infrastructure is deployed (or will be created on first run)
2. Open samples/<sample-name>/create.ipynb
3. Adjust USER CONFIGURATION section if needed
4. Execute all cells

Modifying Policies

1. Edit the *.xml policy file in the sample's apim-policies/ folder
2. Re-run the deployment cell in create.ipynb
3. Test via the verification cells

Existing root-level policy files may remain until their sample is migrated. Policy helpers should resolve apim-policies/ first and the sample root second as a temporary fallback. After moving policy XML or KQL files, verify every notebook, helper, Bicep, test, script, and documentation reference, including path-resolution tests for canonical locations, fallback behavior, explicit paths, auto-detection, and missing files.

Adding APIs to a Sample

In create.ipynb, define APIs using:

from apimtypes import API, GET_APIOperation, POST_APIOperation

# Create operations
get_op = GET_APIOperation('Description of the operation')
post_op = POST_APIOperation('Description', policyXml = '<policy-xml>')

# Create API
api = API(
    '<name>',               # API name (resource identifier)
    '<Display Name>',       # Human-readable display name
    '<path>',               # URL path segment (often same value as name)
    '<Description>',        # API description
    operations = [get_op, post_op],
    tags = ['tag1', 'tag2']
)

# Add to apis array
apis = [api]

Python Modules

The Python helper strategy is the authoritative guide for notebook boundaries, helper ownership, supporting-class design, state, lifecycles, promotion criteria, and testing.

Apply this sequence whenever creating or refactoring a notebook:

1. Keep educational configuration, scenario definitions, APIM concepts, expected outcomes, and assertions visible in the notebook.
2. Extract incidental mechanics behind explicit inputs and typed outputs.
3. Start one-consumer behavior in samples/<sample>/<domain>_helpers.py; promote only after a second active consumer needs the same stable contract.
4. Compose existing NotebookHelper, ApimRequests, ApimTesting, and azure_resources boundaries without adding forwarding wrappers.
5. Make the helper own deterministic cleanup for sessions, files, and temporary resources, and inject remote or timing boundaries for tests.
6. Add focused tests under tests/python/test_<sample>_helpers.py, then replace notebook mechanics with a scenario-readable call.
7. Call configure_notebook_autoreload() after the first code cell's imports and declare each runtime module's reload_safe, reload_conditional, or reload_unsafe classification in its opening docstring. Follow the helper strategy for limitations; do not use broad autoreload or unconditional reloads.

Key modules in shared/python/:

When extracting notebook mechanics, start with a focused sample-local module. Promote it to shared/python/ only after a second real consumer establishes a stable cross-sample contract.

Bicep Modules

Shared modules in shared/bicep/modules/:

• Use versioned modules (e.g., v1/api.bicep) for stability
• Reference with relative paths: ../../shared/bicep/modules/apim/v1/api.bicep
• See apim-bicep skill for APIM-specific patterns

Code Quality Requirements

Dependency Supply-Chain Safety

• Every package or GitHub Action release must complete an eight-day waiting period before use.
• MockAPI container images from simonkurtzmsft/mockapi are exempt from the eight-day waiting period. Keep an exact version tag and immutable digest; package and GitHub Actions waiting periods remain unchanged.
• Preserve tool.uv.exclude-newer = "8 days" and Dependabot cooldowns for all configured ecosystems.
• Before a locked Python install, run python setup/verify_dependency_age.py --scope python, then uv sync --locked.
• Generate uv.lock against canonical public PyPI only by running python setup/sync_dependencies.py --upgrade. Never commit private mirror URLs, proxy configuration, credentials, or internal endpoints. Do not manually remove the registry and artifact URLs required by uv's lock schema.
• If the lock's direct artifact URLs are inaccessible, export the frozen lock without index settings and install the temporary names, versions, markers, and hashes through the approved mirror with uv pip sync --no-config --require-hashes --strict. Use this fallback only after the age verifier succeeds, and never commit the temporary export.
• Keep GitHub Actions pinned to 40-character commit SHAs with version comments and validate them with python setup/verify_dependency_age.py --scope github-actions.
• Do not introduce direct install or upgrade commands that bypass the lockfile, age verifier, or release exclusion.

Python

• Follow Ruff configuration in pyproject.toml
• Use type hints and docstrings
• Run ruff check before committing
• Tests in tests/python/ with pytest

Bicep

• Follow bicepconfig.json linter rules
• Use @description for all parameters
• Include Microsoft Learn template reference links above resources
• Follow section structure: Parameters → Constants → Variables → Resources → Outputs

Jupyter Notebooks

• Clear all cell outputs before committing
• Set index = 1 in the first code cell
• Follow the standard cell structure from _TEMPLATE

Markdown

• Generate Markdown, including repository instructions, skills, and agents, against .markdownlint.json and .github/markdown.instructions.md.
• Preserve semantic heading, list, table, and code-block structure instead of flattening content to satisfy lint rules.
• After any Markdown change, run npx --no-install markdownlint-cli2 "**/*.md" "#**/.venv/**" "#**/node_modules/**" from the repository root and require zero violations.

Testing

Running Tests

# Via Developer CLI
./start.ps1  # Windows
./start.sh   # macOS/Linux
# Select "Tests" menu

# Or directly
pytest tests/python/
ruff check shared/python/

Writing Tests

• Place tests in tests/python/
• Mock Azure CLI interactions (no live Azure access in tests)
• Target 95%+ code coverage
• Use test_helpers.py for common test utilities

Common Tasks Reference

Additional Resources

• Troubleshooting: See TROUBLESHOOTING.md for common issues
• Contributing: See CONTRIBUTING.md for contribution guidelines
• Python instructions: .github/python.instructions.md
• Bicep instructions: .github/bicep.instructions.md
• JSON instructions: .github/json.instructions.md