Azure AI Gateway Labs
Documentation Open portal
NewAzure AI Gateway is generally available

Azure AI Gateway labs

Learn AI Gateway by building with it

Hands-on labs to govern every model, tool, and agent from one gateway. Publish models from any provider, federate MCP tools, enforce limits and budgets, go keyless, observe every token, and govern agents.

Labs
35
Learning paths
5
Hands-on time
18 h
Tracks per lab
4

Start here · 5 minutes

Your first model call in five minutes

In the AI Gateway portal, with a few Azure CLI commands in Cloud Shell, or with one azd up, you create a gateway, publish a Microsoft Foundry model behind an alias, and create a runtime key. Then you make your first call through the gateway, the way an app does: with the alias and the key.

  1. 1Understand the building blocks
  2. 2Create a gateway in the portal, Azure CLI, or azd
  3. 3Call the model through the gateway
⏳ Gateway aigw-540780 is provisioning in the background✨ Model deployment gpt-5-mini is ready🚀 Gateway aigw-540780 is ready🔖 Alias gpt-5-mini is ready🔑 API key app-first-call is ready🌐 Runtime URL: https://aigw-54078-q2mv7x4kz9hpt.eastus2-01.ai.gateway.azure.com$ curl $AI_GATEWAY_URL/…/chat/completions -H "Authorization: Bearer …"🤖 An AI gateway sits between applications and AI models, routing requests while managing access, security, and usage.
Condensed from a real run of the Azure CLI track.

How you learn

Your tools, your pace

Every lab offers the tracks that fit the task. Pick one and the site remembers it across labs.

Portal

Click-by-click guides in the AI Gateway portal, with exact labels and screenshots.

Azure CLI

Repeatable az aigateway and az deployment commands you can paste into Bash or PowerShell.

Bicep & Terraform

Infrastructure as code: deploy a lab with azd up or terraform apply, and remove it with one command.

Code & REST

Python, TypeScript, and .NET clients, agent frameworks, and REST calls.

  • Checkpoints after every task
  • Your values fill every command
  • Interactive simulators for limits, budgets, and tools
  • Clean-up and troubleshooting for every lab

Learning paths

Follow a path built for your role

Each path strings labs together in order. Your progress is saved in this browser.

Use cases

From the essentials to what's emerging

Start with the controls every AI platform needs, then explore agent-era governance.

Emerging use cases

Auto model selectionLet the gateway send each prompt to a lower-cost or a higher-quality model behind one alias.Lab 28 · Auto model selection Typed decisions with JevGet yes/no probabilities, choices, and rubric scores from decision models behind a governed alias.Lab 31 · Jev decisions Agent frameworks & hosted agentsRoute every model and tool call an agent makes through one control point.Lab 16 · Foundry hosted agent Gateway models in Foundry projectsGive Foundry projects the platform team's models through one gateway connection, with no deployments or keys.Lab 32 · Foundry gateway connection Tool allow and block listsExpose only approved tools with exact lists and patterns.Lab 05 · Tool allow & block lists Chargeback with token claimsAttribute tokens and cost to tenants, apps, and cost centers.Lab 14 · OpenTelemetry chargeback Tool threat protectionDefender and Purview evaluate tool calls for injection and data risk.Lab 19 · Tool threat protection Agent hooksRun your own allow-or-deny rules on every MCP tool call and result, in an Azure function.Lab 30 · Agent hooks Copilot tools as the signed-in userLet Microsoft 365 Copilot call MCP tools as each signed-in user, with Microsoft Entra on-behalf-of at the gateway.Lab 33 · Copilot on-behalf-of Agent 365 governanceInventory and block MCP servers and tools from the Microsoft 365 admin center.Lab 20 · Agent 365 governance Coding-agent pluginLet Copilot, Claude Code, Cursor, or Gemini build on your gateway, and migrate AI assets from API Management.Lab 17 · Coding-agent plugin GitHub Copilot on your models and toolsRun Copilot in VS Code, the CLI, the SDK, and the app on models and MCP tools your gateway governs.Lab 24 · GitHub Copilot BYOK Claude Code on your models and toolsRun Claude Code on Claude models from Foundry, with MCP tools, token limits, and budgets your gateway governs.Lab 25 · Claude Code Streaming with accurate usageStream replies token by token while limits, budgets, and monitoring count every token.Lab 23 · Streaming responses

Catalog

Explore by topic

Popular labs

See all labs
02
Foundations

Publish a Foundry model and make your first call

Publish a Microsoft Foundry model deployment through your gateway with its managed identity, create a runtime API key, try the model in the Catalog playground, and call it from curl, PowerShell, Python, TypeScript, and C#.

Beginner 25 min
04
MCP & tools

Federate MCP tools behind one endpoint

Register a remote MCP server in Azure AI Gateway, add a second backend under its own namespace, and connect curl, VS Code, and Python to one governed MCP endpoint.

Beginner 30 min
06
Governance & cost

Throttle tokens per caller with token limits

Cap how many tokens each app, agent, or user can consume per minute, hour, or day, and watch the gateway answer with 429 and Retry-After before your backend capacity runs out.

Beginner 25 min
07
Governance & cost

Enforce cost budgets with per-caller overrides

Give every app, agent, and user a dollar budget per hour, day, or month, raise or lower it for specific API keys and Microsoft Entra identities, and watch the gateway answer 403 LlmCostQuotaExceeded once a caller's estimated spend runs out.

Intermediate 30 min
11
Security & identity

Go keyless with Microsoft Entra ID and RBAC

Replace shared gateway API keys with Microsoft Entra ID tokens. Grant users, groups, apps, and managed identities an AI Gateway runtime role on all assets, a model alias, or an MCP server, call models from the playground, curl, Python, TypeScript, and C# with no secret in code, and grant management access separately with the control-plane roles.

Intermediate 45 min
16
Agents

Deploy a Foundry hosted agent behind AI Gateway

Deploy your own Microsoft Agent Framework agent to Foundry Hosted Agents with azd. The agent has no model deployment, no direct tool access, and no keys. It calls its model through AI Gateway with its own Microsoft Entra Agent ID, and reaches the Microsoft Learn MCP server through a Foundry toolbox that signs in with the project's managed identity. Run it locally, invoke it in Foundry, and cap its tokens without changing its code.

Intermediate 45 min

Inside every lab

Built for doing, not just reading

  • 1
    Scenario and diagram. Who has the problem, and how the gateway solves it.
  • 2
    How it works. The concept in two minutes, often with a live simulator.
  • 3
    Step-by-step tracks. Portal, CLI, REST, Bicep, or code. Mark each step done.
  • 4
    Verify and clean up. Checkpoints prove it works, then remove what you created.
See an example lab