Skill

Official

Review

Audit score 70

azure-aigateway

microsoft/azure-skills

Configure Azure API Management as an AI Gateway for governing AI models, MCP tools, and agents

What is azure-aigateway?

This skill enables coding agents to configure Azure API Management (APIM) as an AI Gateway. It covers adding Azure OpenAI and AI Foundry model backends, applying LLM governance policies (semantic caching, token limits, content safety, load balancing, jailbreak detection), managing MCP tool rate limiting, and testing AI endpoints. It provides CLI commands, policy ordering guidance, and troubleshooting references for common issues.

Add Azure OpenAI and AI Foundry model backends to APIM
Apply semantic caching policies to reduce AI call costs by 60-80%
Enforce token rate limits for AI cost control
Configure content safety and jailbreak detection for agent governance
Set up load balancing across AI model backends
Emit token usage metrics for observability and cost tracking

How to install azure-aigateway

npx skills add https://github.com/microsoft/azure-skills --skill azure-aigateway

Prerequisites

Azure API Management instance (deploy using the azure-prepare skill)
Azure CLI (az) installed and authenticated
Azure OpenAI or AI Foundry model resource provisioned
APIM managed identity granted 'Cognitive Services User' role on AI resources
APIM subscription key for testing endpoints

Claude Code

Cursor

Windsurf

Cline

How to use azure-aigateway

1.Install the skill: npx skills add https://github.com/microsoft/azure-skills --skill azure-aigateway
2.Retrieve your APIM gateway URL and subscription key using the provided az apim commands
3.Discover existing Azure OpenAI resources with az cognitiveservices account list
4.Create an AI backend in APIM pointing to your Azure OpenAI endpoint
5.Grant APIM managed identity the 'Cognitive Services User' role on the AI resource
6.Apply inbound policies in recommended order: authentication, semantic cache lookup, token limits, content safety, backend selection, metrics
7.Test the AI endpoint using the provided curl command template
8.Consult references/policies.md and references/troubleshooting.md for advanced configuration and issue resolution

Use cases

Good for

Govern multiple Azure OpenAI deployments behind a single gateway with token limits and load balancing
Reduce LLM costs by enabling semantic caching for repeated or similar prompts
Protect MCP tools and APIs with rate limiting and content safety filters
Track token consumption per subscription for cost allocation and reporting
Convert existing OpenAPI-defined APIs into MCP tools via the gateway

Who it's for

Platform engineers managing AI infrastructure on Azure
Developers building agents or LLM-powered applications on Azure OpenAI
Security and compliance teams enforcing content safety policies on AI usage
FinOps practitioners controlling and monitoring AI token spend
API teams exposing AI models or MCP tools to internal consumers

azure-aigateway FAQ

Do I need to deploy APIM separately before using this skill?

Yes. APIM must already exist. Use the azure-prepare skill or follow the APIM deployment guide linked in the skill.

What Azure CLI version or permissions are required?

The skill requires the Azure CLI (az) to be installed and authenticated with permissions to manage APIM, create role assignments, and list Cognitive Services accounts.

How do I fix 401 errors when APIM calls my Azure OpenAI backend?

Grant the APIM managed identity the 'Cognitive Services User' role on the Azure OpenAI resource using az role assignment create.

Why are there no semantic cache hits?

Lower the score-threshold parameter to 0.7 to allow less-exact matches to be served from cache.

Can this skill help convert a REST API into an MCP tool?

Yes. The skill covers importing OpenAPI definitions into the gateway and converting APIs to MCP tools as described in the configuration patterns reference.

Full instructions (SKILL.md)

Source of truth, from microsoft/azure-skills.

name: azure-aigateway description: "Configure Azure API Management as an AI Gateway for AI models, MCP tools, and agents. WHEN: semantic caching, token limit, content safety, load balancing, AI model governance, MCP rate limiting, jailbreak detection, add Azure OpenAI backend, add AI Foundry model, test AI gateway, LLM policies, configure AI backend, token metrics, AI cost control, convert API to MCP, import OpenAPI to gateway." license: MIT metadata: author: Microsoft version: "3.1.1" compatibility: Requires Azure CLI (az) for configuration and testing

Azure AI Gateway

Configure Azure API Management (APIM) as an AI Gateway for governing AI models, MCP tools, and agents.

To deploy APIM, use the azure-prepare skill. See APIM deployment guide.

When to Use This Skill

Category	Triggers
Model Governance	"semantic caching", "token limits", "load balance AI", "track token usage"
Tool Governance	"rate limit MCP", "protect my tools", "configure my tool", "convert API to MCP"
Agent Governance	"content safety", "jailbreak detection", "filter harmful content"
Configuration	"add Azure OpenAI backend", "configure my model", "add AI Foundry model"
Testing	"test AI gateway", "call OpenAI through gateway"

Quick Reference

Policy	Purpose	Details
`azure-openai-token-limit`	Cost control	Model Policies
`azure-openai-semantic-cache-lookup/store`	60-80% cost savings	Model Policies
`azure-openai-emit-token-metric`	Observability	Model Policies
`llm-content-safety`	Safety & compliance	Agent Policies
`rate-limit-by-key`	MCP/tool protection	Tool Policies

Get Gateway Details

# Get gateway URL
az apim show --name <apim-name> --resource-group <rg> --query "gatewayUrl" -o tsv

# List backends (AI models)
az apim backend list --service-name <apim-name> --resource-group <rg> \
  --query "[].{id:name, url:url}" -o table

# Get subscription key
az apim subscription keys list \
  --service-name <apim-name> --resource-group <rg> --subscription-id <sub-id>

Test AI Endpoint

GATEWAY_URL=$(az apim show --name <apim-name> --resource-group <rg> --query "gatewayUrl" -o tsv)

curl -X POST "${GATEWAY_URL}/openai/deployments/<deployment>/chat/completions?api-version=2024-02-01" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: <key>" \
  -d '{"messages": [{"role": "user", "content": "Hello"}], "max_tokens": 100}'

Common Tasks

Add AI Backend

See references/patterns.md for full steps.

# Discover AI resources
az cognitiveservices account list --query "[?kind=='OpenAI']" -o table

# Create backend
az apim backend create --service-name <apim> --resource-group <rg> \
  --backend-id openai-backend --protocol http --url "https://<aoai>.openai.azure.com/openai"

# Grant access (managed identity)
az role assignment create --assignee <apim-principal-id> \
  --role "Cognitive Services User" --scope <aoai-resource-id>

Apply AI Governance Policy

Recommended policy order in <inbound>:

Authentication - Managed identity to backend
Semantic Cache Lookup - Check cache before calling AI
Token Limits - Cost control
Content Safety - Filter harmful content
Backend Selection - Load balancing
Metrics - Token usage tracking

See references/policies.md for complete example.

Troubleshooting

Issue	Solution
Token limit 429	Increase `tokens-per-minute` or add load balancing
No cache hits	Lower `score-threshold` to 0.7
Content false positives	Increase category thresholds (5-6)
Backend auth 401	Grant APIM "Cognitive Services User" role

See references/troubleshooting.md for details.

References

Detailed Policies - Full policy examples
Configuration Patterns - Step-by-step patterns
Troubleshooting - Common issues
AI-Gateway Samples
GenAI Gateway Docs

SDK Quick References

Content Safety: Python | TypeScript
API Management: Python | .NET

Azure Storage skill: Blob, File Shares, Queue, Table, and Data Lake with access tier guidance and lifecycle management

420k installsAudited