Agent skill

apim-bicep

Guide for building Bicep files for Azure API Management (APIM) and related Azure services. Use when users want to create, modify, or understand Bicep templates for APIM instances, APIs, backends, subscriptions, policies, products, loggers, diagnostics, and MCP servers. This skill provides Bicep syntax, patterns from Azure Verified Modules, and examples from this repository.

View SKILL.md on GitHub Repository
Stars 900
Forks 410

Install this agent skill to your Project

npx add-skill https://github.com/Azure-Samples/AI-Gateway/tree/main/.github/skills/apim-bicep

SKILL.md

APIM Bicep

This skill provides guidance for creating Azure Bicep templates for API Management and related services.

Quick Start - Basic APIM Instance

bicep
@description('The name of the API Management service instance')
param apiManagementServiceName string = 'apim-${uniqueString(resourceGroup().id)}'

@description('The email address of the publisher')
param publisherEmail string

@description('The name of the publisher')
param publisherName string

@description('The pricing tier of this API Management service')
@allowed(['Consumption', 'Developer', 'Basic', 'Basicv2', 'Standard', 'Standardv2', 'Premium'])
param sku string = 'Basicv2'

@description('Location for all resources')
param location string = resourceGroup().location

resource apimService 'Microsoft.ApiManagement/service@2024-06-01-preview' = {
  name: apiManagementServiceName
  location: location
  sku: {
    name: sku
    capacity: 1
  }
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    publisherEmail: publisherEmail
    publisherName: publisherName
  }
}

output apimId string = apimService.id
output apimName string = apimService.name
output gatewayUrl string = apimService.properties.gatewayUrl
output principalId string = apimService.identity.principalId

Resource Types Reference

Resource Type API Version Purpose
Microsoft.ApiManagement/service 2024-06-01-preview APIM service instance
Microsoft.ApiManagement/service/apis 2024-06-01-preview API definitions
Microsoft.ApiManagement/service/apis/operations 2024-06-01-preview API operations
Microsoft.ApiManagement/service/apis/policies 2024-06-01-preview API-level policies
Microsoft.ApiManagement/service/backends 2024-06-01-preview Backend services
Microsoft.ApiManagement/service/subscriptions 2024-06-01-preview API subscriptions
Microsoft.ApiManagement/service/products 2024-06-01-preview API products
Microsoft.ApiManagement/service/loggers 2024-06-01-preview Logging configuration
Microsoft.ApiManagement/service/apis/diagnostics 2024-06-01-preview API diagnostics

Essential Patterns

Backend with Managed Identity

bicep
resource backend 'Microsoft.ApiManagement/service/backends@2024-06-01-preview' = {
  name: 'my-backend'
  parent: apimService
  properties: {
    description: 'Backend with managed identity auth'
    url: 'https://my-service.azure.com'
    protocol: 'http'
    credentials: {
      managedIdentity: {
        resource: 'https://cognitiveservices.azure.com'
      }
    }
  }
}

Backend Pool (Load Balancing)

bicep
resource backendPool 'Microsoft.ApiManagement/service/backends@2024-06-01-preview' = {
  name: 'inference-backend-pool'
  parent: apimService
  properties: {
    description: 'Load balancer for multiple backends'
    type: 'Pool'
    pool: {
      services: [for (config, i) in backendsConfig: {
        id: '/backends/${backends[i].name}'
        priority: config.?priority ?? 1
        weight: config.?weight ?? 1
      }]
    }
  }
}

API with OpenAPI Spec

bicep
resource api 'Microsoft.ApiManagement/service/apis@2024-06-01-preview' = {
  name: 'my-api'
  parent: apimService
  properties: {
    displayName: 'My API'
    description: 'API description'
    path: 'api/v1'
    protocols: ['https']
    subscriptionRequired: true
    subscriptionKeyParameterNames: {
      header: 'api-key'
      query: 'api-key'
    }
    format: 'openapi+json'
    value: string(loadJsonContent('./openapi.json'))
  }
}

API Policy from File

bicep
resource apiPolicy 'Microsoft.ApiManagement/service/apis/policies@2024-06-01-preview' = {
  name: 'policy'
  parent: api
  properties: {
    format: 'rawxml'
    value: loadTextContent('policy.xml')
  }
}

Subscription

bicep
@batchSize(1)
resource subscription 'Microsoft.ApiManagement/service/subscriptions@2024-06-01-preview' = [for sub in subscriptionsConfig: {
  name: sub.name
  parent: apimService
  properties: {
    displayName: sub.displayName
    scope: '/apis'  // or '/apis/{apiId}' or '/products/{productId}'
    state: 'active'
    allowTracing: true
  }
}]

MCP Server Patterns

Native MCP API (type: 'mcp')

Create an MCP server API that wraps existing API operations:

bicep
resource mcp 'Microsoft.ApiManagement/service/apis@2024-06-01-preview' = {
  parent: apim
  name: 'weather-mcp'
  properties: {
    type: 'mcp'
    displayName: 'Weather MCP'
    description: 'MCP for weather data'
    subscriptionRequired: false
    path: 'weather-mcp'
    protocols: ['https']
    mcpTools: [
      {
        name: operation.name
        operationId: operation.id
        description: operation.properties.description
      }
    ]
  }
}

Streamable MCP with Backend

Create an MCP server with a backend service:

bicep
resource mcpBackend 'Microsoft.ApiManagement/service/backends@2024-06-01-preview' = {
  parent: apim
  name: 'weather-mcp-backend'
  properties: {
    protocol: 'http'
    url: '${mcpServiceUrl}/mcp'
    tls: {
      validateCertificateChain: true
      validateCertificateName: true
    }
    type: 'Single'
  }
}

resource mcp 'Microsoft.ApiManagement/service/apis@2024-06-01-preview' = {
  parent: apim
  name: 'weather-mcp'
  properties: {
    type: 'mcp'
    displayName: 'Weather MCP'
    subscriptionRequired: false
    backendId: mcpBackend.name
    path: 'weather'
    protocols: ['https']
    mcpProperties: {
      transportType: 'streamable'
    }
  }
}

MCP with Custom Operations

bicep
resource mcpApi 'Microsoft.ApiManagement/service/apis@2024-06-01-preview' = {
  parent: apimService
  name: 'agent-mcp'
  properties: {
    displayName: 'Agent MCP Server'
    description: 'Model Context Protocol API endpoints'
    subscriptionRequired: false
    path: 'agent'
    protocols: ['https']
    serviceUrl: containerAppUrl
  }
}

resource mcpSseOp 'Microsoft.ApiManagement/service/apis/operations@2024-06-01-preview' = {
  parent: mcpApi
  name: 'mcp-sse'
  properties: {
    displayName: 'MCP SSE Endpoint'
    method: 'GET'
    urlTemplate: '/sse'
    description: 'Server-Sent Events endpoint'
  }
}

resource mcpMessageOp 'Microsoft.ApiManagement/service/apis/operations@2024-06-01-preview' = {
  parent: mcpApi
  name: 'mcp-message'
  properties: {
    displayName: 'MCP Message Endpoint'
    method: 'POST'
    urlTemplate: '/message'
    description: 'Message endpoint for MCP Server'
  }
}

Diagnostics and Logging

Azure Monitor Logger

bicep
resource apimLogger 'Microsoft.ApiManagement/service/loggers@2024-06-01-preview' = {
  parent: apimService
  name: 'azuremonitor'
  properties: {
    loggerType: 'azureMonitor'
    isBuffered: false
  }
}

Application Insights Logger

bicep
resource appInsightsLogger 'Microsoft.ApiManagement/service/loggers@2024-06-01-preview' = {
  name: 'appinsights-logger'
  parent: apimService
  properties: {
    loggerType: 'applicationInsights'
    credentials: {
      instrumentationKey: appInsightsInstrumentationKey
    }
    description: 'APIM Logger for Application Insights'
    isBuffered: false
    resourceId: appInsightsId
  }
}

API Diagnostics with LLM Logging

bicep
resource apiDiagnostics 'Microsoft.ApiManagement/service/apis/diagnostics@2024-06-01-preview' = {
  parent: api
  name: 'azuremonitor'
  properties: {
    alwaysLog: 'allErrors'
    verbosity: 'verbose'
    logClientIp: true
    loggerId: apimLogger.id
    sampling: {
      samplingType: 'fixed'
      percentage: 100
    }
    largeLanguageModel: {
      logs: 'enabled'
      requests: {
        messages: 'all'
        maxSizeInBytes: 262144
      }
      responses: {
        messages: 'all'
        maxSizeInBytes: 262144
      }
    }
  }
}

Bicep Best Practices

Use Existing Resources

bicep
resource apim 'Microsoft.ApiManagement/service@2024-06-01-preview' existing = {
  name: apimServiceName
}

Parameter Validation

bicep
@description('The pricing tier')
@allowed(['Consumption', 'Developer', 'Basic', 'Basicv2', 'Standard', 'Standardv2', 'Premium'])
param sku string = 'Basicv2'

@minLength(1)
@maxLength(50)
param apiManagementName string

Load External Content

bicep
// Load JSON for OpenAPI specs
value: string(loadJsonContent('./specs/openapi.json'))

// Load XML for policies
value: loadTextContent('policy.xml')

// Load and parameterize policy
var updatedPolicy = replace(loadTextContent('policy.xml'), '{backend-id}', backendName)

Output Secrets Safely

bicep
#disable-next-line outputs-should-not-contain-secrets
output subscriptionKey string = subscription.listSecrets().primaryKey

Reference Documentation

For detailed patterns and examples, see:

  • APIM Resource Reference: Complete resource definitions
  • MCP Server Patterns: MCP configuration examples
  • Azure Verified Modules: Patterns from Azure Verified Modules

Official Documentation

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

Azure-Samples/AI-Gateway

apim-terraform

Guide for creating Terraform files for Azure API Management (APIM) and related Azure services. Use when users want to create, modify, or understand Terraform configurations for APIM instances, APIs, backends, subscriptions, policies, products, loggers, diagnostics, and supporting infrastructure using the azurerm provider. This skill provides HCL syntax, resource definitions, and patterns from the Terraform Registry and this repository.

900 410
Explore
Azure-Samples/AI-Gateway

apim-policies

Guide for creating Azure API Management (APIM) XML policies. Use when users want to create, modify, or understand APIM policies including inbound/outbound processing, authentication, rate limiting, caching, transformations, AI gateway policies, and policy expressions. This skill provides policy syntax, examples, and C# policy expressions for request/response manipulation.

900 410
Explore
Azure-Samples/AI-Gateway

mcp-builder

Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).

900 410
Explore
Azure-Samples/AI-Gateway

lab-creator

Guide for creating new AI Gateway labs. Use when users want to create a new lab in the labs/ folder. This skill provides the standard lab structure, templates, and patterns used across the AI Gateway repository including Jupyter notebooks, Bicep infrastructure templates, APIM policies, and README documentation.

900 410
Explore
Azure-Samples/AI-Gateway

apim-kql

Guide for creating Kusto Query Language (KQL) queries for Azure API Management tables in Azure Monitor (Log Analytics Workspace). Use when users want to query, analyze, or monitor APIM logs including gateway logs, LLM/AI logs, MCP logs, WebSocket logs, and Application Insights data. This skill provides KQL syntax, table schemas, and query patterns for APIM monitoring scenarios.

900 410
Explore
Azure-Samples/AI-Gateway

skill-creator

Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.

900 410
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results