GitHub Copilot can run on a model that you bring yourself: give it an OpenAI-compatible endpoint and a key, and it
sends every chat and agent request there. Make that endpoint your gateway, and Copilot's traffic gets the same
controls as your apps: a key that you can suspend, a token limit for each caller, and usage in Monitoring. Copilot
never sees a Foundry credential, because the gateway calls Foundry with its managed identity. In this lab you publish
gpt-6.1-sol for Copilot, then connect four Copilot surfaces to it: VS Code, the Copilot CLI, the Copilot SDK, and
the GitHub Copilot app. Then you publish the Microsoft Learn MCP server through the same gateway and give those
surfaces its tools, with the same key, so Copilot's tool calls get the same controls as its model calls.
Before you begin
One-time setupThe Setup guide tasks that this lab uses. Mark each one done once, and the labs stop listing it.
- Choose where to run commandsEvery track except the portal
- Sign in to AzureOn your own machine. Cloud Shell is already signed in.
- Install the
aigatewayextensionThe Azure CLI tracks and the Verify steps - Clone the labs repoThe Bicep + azd and Terraform tracks, the notebooks, and the code samples
You've done the one-time setup that this lab uses.
On the Bicep + azd and Terraform tracks, azd up or terraform apply creates its own gateway, Foundry
account, gpt-6.1-sol alias, key, and learn MCP server, and the track sets the variables, so you can skip lab 02
and the variables below. You need the one-time setup above, plus quota for the model, a Copilot surface, and the
practice project.
Complete Publish a Foundry model and make your first call. You need a gateway with a Foundry provider, and permission to change it, for example Contributor on the resource group.
Quota for
gpt-6.1-sol(version2026-09-29) in the Foundry account behind your gateway. This lab deploys it with 100,000 tokens per minute (TPM), because coding agents send large prompts. Model inference is billed per use.At least one Copilot surface. You don't need all four:
Surface Version tested Needs VS Code with GitHub Copilot 1.143 Nothing else. Chat and agent mode work with your own model without a GitHub sign-in. GitHub Copilot CLI 1.0.112 Nothing else. A GitHub sign-in is optional with your own model. GitHub Copilot SDK 1.0.34 (TypeScript), 1.0.31 (Python) Node.js 22.18 or later, or Python 3.11 or later, and a clone of this repository. GitHub Copilot app Public preview A GitHub sign-in. A Copilot plan isn't required for your own models. Run the scripts and samples from the lab's folder,
~/aigateway/labs/24-github-copilot-byok.
On Copilot Business or Copilot Enterprise, an administrator must allow custom models before VS Code and the Copilot app offer them. See Enable custom models for your enterprise.
Set these variables once. Every track and the Verify section reuse them.
# Name your gateway, the Foundry account behind it, and what this lab publishes on the gateway
export RG="<resource-group>"
export GATEWAY="<gateway>"
export FOUNDRY_RG="<foundry-resource-group>" # resource group of the Foundry account behind the gateway
export FOUNDRY_ACCOUNT="<foundry-account-name>" # the account name, not a project or deployment name
export PROVIDER="foundry-models" # the gateway's Foundry provider from lab 02
export MODEL="gpt-6.1-sol" # the deployment, the backend model, and the alias
export KEY_NAME="github-copilot" # the runtime key that Copilot uses
# Read the gateway's resource ID and runtime URL
export GATEWAY_ID="$(az aigateway show -g "$RG" -n "$GATEWAY" --query id -o tsv)"
export AI_GATEWAY_URL="https://$(az aigateway show -g "$RG" -n "$GATEWAY" --query properties.frontend.defaultHostname -o tsv)"
export AI_GATEWAY_MODEL="$MODEL"
echo "📝 Gateway $GATEWAY in $RG, with Foundry account $FOUNDRY_ACCOUNT in $FOUNDRY_RG"
echo "🌐 Runtime URL: $AI_GATEWAY_URL"
echo "🔖 Model alias: $AI_GATEWAY_MODEL"# Name your gateway, the Foundry account behind it, and what this lab publishes on the gateway
$RG = "<resource-group>"
$GATEWAY = "<gateway>"
$FOUNDRY_RG = "<foundry-resource-group>" # resource group of the Foundry account behind the gateway
$FOUNDRY_ACCOUNT = "<foundry-account-name>" # the account name, not a project or deployment name
$PROVIDER = "foundry-models" # the gateway's Foundry provider from lab 02
$MODEL = "gpt-6.1-sol" # the deployment, the backend model, and the alias
$KEY_NAME = "github-copilot" # the runtime key that Copilot uses
# Read the gateway's resource ID and runtime URL
$GATEWAY_ID = az aigateway show -g $RG -n $GATEWAY --query id -o tsv
$env:AI_GATEWAY_URL = "https://$(az aigateway show -g $RG -n $GATEWAY --query properties.frontend.defaultHostname -o tsv)"
$env:AI_GATEWAY_MODEL = $MODEL
Write-Host "📝 Gateway $GATEWAY in $RG, with Foundry account $FOUNDRY_ACCOUNT in $FOUNDRY_RG"
Write-Host "🌐 Runtime URL: $env:AI_GATEWAY_URL"
Write-Host "🔖 Model alias: $env:AI_GATEWAY_MODEL"If you imported models in the portal in lab 02, your provider has another name. List the providers with
az aigateway model-provider list -g "$RG" --gateway-name "$GATEWAY" --query "[].name" -o tsv and set PROVIDER
to the one for your Foundry account.
Then create a small practice project with two deliberate problems: add subtracts, and divide doesn't guard against
zero. The VS Code and CLI sections ask Copilot to work on it. Create it outside any repository:
# Create the practice project's folder, and write calc.py with its two deliberate problems
mkdir -p ~/contoso-calc
cat > ~/contoso-calc/calc.py <<'EOF'
"""Tiny calculator used to try GitHub Copilot with a model from Azure AI Gateway."""
def add(a: float, b: float) -> float:
return a - b
def divide(a: float, b: float) -> float:
return a / b
if __name__ == "__main__":
print(add(2, 3), divide(10, 2))
EOF
echo "📄 Practice project is ready: ~/contoso-calc/calc.py"# Create the practice project's folder, and write calc.py with its two deliberate problems
New-Item -ItemType Directory -Force -Path ~/contoso-calc | Out-Null
@'
"""Tiny calculator used to try GitHub Copilot with a model from Azure AI Gateway."""
def add(a: float, b: float) -> float:
return a - b
def divide(a: float, b: float) -> float:
return a / b
if __name__ == "__main__":
print(add(2, 3), divide(10, 2))
'@ | Set-Content -Path ~/contoso-calc/calc.py
if ($?) { Write-Host "📄 Practice project is ready: ~/contoso-calc/calc.py" }How it works
Bring your own key (BYOK) replaces the model endpoint behind Copilot. Copilot still runs its agent loop on your machine: it reads files, plans, calls tools, and asks before it edits or runs commands. Each model request goes to the gateway instead of GitHub's model service. Every surface needs the same four settings:
| Setting | Value | Why |
|---|---|---|
| Base URL | https://<gateway-host>/default/models/openai/v1 | The gateway's OpenAI-compatible endpoint. VS Code wants the full URL, with /responses at the end. |
| Model | gpt-6.1-sol | The alias. Copilot sends it in the request's model field, and the gateway routes by alias. When the alias has the model's well-known name, Copilot also applies the prompts and token sizes it uses for that model. |
| API | Responses | Copilot recommends the Responses API for GPT-5 and later models. The gateway serves both /responses and /chat/completions for this model. |
| API key | The github-copilot runtime key | Copilot sends it as Authorization: Bearer, the header the gateway reads keys from. |
Two things differ from an app that calls the gateway:
- You add the model by hand. Clients often call
GET /modelsto discover what an endpoint offers, but the gateway doesn't serve a model list. Each surface lets you type the model name instead. - Agents send big requests. Every request carries Copilot's system prompt, its tool definitions, and the conversation so far. In testing, a one-line question from the Copilot CLI used 14,000 to 38,000 input tokens. That's why this lab gives each caller 100,000 tokens per minute, and why one key per tool or per developer makes usage easy to read.
Tools follow the same pattern. Later in this lab, the gateway also publishes the Microsoft Learn MCP server, and each surface calls its tools with the same key.
Publish gpt-6.1-sol for Copilot
Deploy gpt-6.1-sol in Foundry, publish it through the gateway under the alias gpt-6.1-sol with a token limit of
100,000 tokens per minute for each caller, and create the runtime key github-copilot. Pick a track.
Deploy the model in Foundry
In the Foundry portal, open the Foundry account behind your gateway and deploy gpt-6.1-sol
with the deployment name gpt-6.1-sol. Or paste the command from the Azure CLI track's first step into
Azure Cloud Shell.
Import the deployment
- Open the AI Gateway portal and select your gateway in the top bar.
- Select ModelsAddModels from Microsoft Foundry.
- In Subscriptions and Resource groups, select those of your Foundry account. Keep Managed identity as the Authentication method.
- In Models, select only the
gpt-6.1-soldeployment: the page can preselect other deployments of the account. - Under Aliases, keep Create an alias for each model selected, then select Add models.
Publish the gpt-6.1-sol alias
The import names its alias after the provider and the deployment, for example <foundry-account-name>/gpt-6.1-sol.
Copilot needs the plain model name, so add an alias called gpt-6.1-sol:
- Select ModelsAddAlias for existing models.
- On Basics, set Alias name to
gpt-6.1-sol. Select Next. - On Select models, select the
gpt-6.1-solbackend model in the grid. Select Next. - Keep the defaults on Auto model selection (preview), Session affinity, Priorities and weights, and Failure handling, selecting Next on each, then select Create on Review.
Add the token limit
- Select PoliciesAdd policy. On the Type step, under Cost and rate limits, select Token rate limit, then Next.
- On the Scope step, select Individual assets, select the
gpt-6.1-solasset of type Alias, then Next. - On the Details step, set Time period to Per minute and Allowed tokens to
100000. Keep Counter dimensions at Identity, so that each key gets its own counter. Select Create.
Create the key for Copilot
- Select AccessAPI keysCreate API key.
- In Key name, enter
github-copilotand select Create. - Copy the value from API key created successfully, for example with Copy & done, and paste it into your shell without echoing it:
# Paste the key without showing it, and export it for the test calls and the Copilot surfaces
printf "AI Gateway API key: " && read -rs AI_GATEWAY_API_KEY && export AI_GATEWAY_API_KEY && echo
echo "🔑 Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"# Paste the key without showing it, and keep it in an environment variable for the test calls and the Copilot surfaces
$env:AI_GATEWAY_API_KEY = Read-Host "AI Gateway API key" -MaskInput
Write-Host "🔑 Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"ModelsAliases lists gpt-6.1-sol, Policies lists a Token rate limit of 100,000 tokens per
minute scoped to it, and AccessAPI keys lists github-copilot.
Deploy the model in Foundry
If the command fails with InsufficientQuota, use --sku-name DataZoneStandard, or deploy in another region.
# Read the Foundry account's resource ID, which the gateway's model points at
export FOUNDRY_ID="$(az cognitiveservices account show -g "$FOUNDRY_RG" -n "$FOUNDRY_ACCOUNT" --query id -o tsv)"
echo "🆔 Foundry account: $FOUNDRY_ID"
# Deploy gpt-6.1-sol with 100,000 tokens per minute of Global Standard capacity, and show its state
echo "✨ Model deployment $MODEL in $FOUNDRY_ACCOUNT:"
az cognitiveservices account deployment create -g "$FOUNDRY_RG" -n "$FOUNDRY_ACCOUNT" \
--deployment-name "$MODEL" --model-name "$MODEL" --model-version 2026-09-29 \
--model-format OpenAI --sku-name GlobalStandard --sku-capacity 100 \
--query "{name:name, state:properties.provisioningState}"# Read the Foundry account's resource ID, which the gateway's model points at
$FOUNDRY_ID = az cognitiveservices account show -g $FOUNDRY_RG -n $FOUNDRY_ACCOUNT --query id -o tsv
Write-Host "🆔 Foundry account: $FOUNDRY_ID"
# Deploy gpt-6.1-sol with 100,000 tokens per minute of Global Standard capacity, and show its state
Write-Host "✨ Model deployment $MODEL in ${FOUNDRY_ACCOUNT}:"
az cognitiveservices account deployment create -g $FOUNDRY_RG -n $FOUNDRY_ACCOUNT `
--deployment-name $MODEL --model-name $MODEL --model-version 2026-09-29 `
--model-format OpenAI --sku-name GlobalStandard --sku-capacity 100 `
--query "{name:name, state:properties.provisioningState}"Register the model with its token limit
Register the deployment under the provider, then give the backend model a token limit of 100,000 tokens per minute
for each caller. az aigateway model policy set-token-limit keeps any other policy that's already on the model. If
you registered gpt-6.1-sol under this provider in another lab, model create fails with
The model already exists: carry on with the token limit, which applies to the existing model.
# Register the deployment as a model under the provider, with the Chat Completions and Responses endpoints
az aigateway model create -g "$RG" --gateway-name "$GATEWAY" --provider-name "$PROVIDER" -n "$MODEL" \
--display-name "$MODEL" --api-format OpenAIChatCompletions \
--supported-endpoints /openai/v1/chat/completions /openai/v1/responses \
--deployment-config "{resourceId:$FOUNDRY_ID/deployments/$MODEL,modelName:$MODEL,modelVersion:2026-09-29}" -o none &&
echo "✨ Model $MODEL is published through $PROVIDER"
# Give each caller 100,000 tokens per minute on the model, and show the model's policies
echo "🔐 Policies on $MODEL:"
az aigateway model policy set-token-limit -g "$RG" --gateway-name "$GATEWAY" --provider-name "$PROVIDER" -n "$MODEL" \
--token-limit 100000# Register the deployment as a model under the provider, with the Chat Completions and Responses endpoints
az aigateway model create -g $RG --gateway-name $GATEWAY --provider-name $PROVIDER -n $MODEL `
--display-name $MODEL --api-format OpenAIChatCompletions `
--supported-endpoints /openai/v1/chat/completions /openai/v1/responses `
--deployment-config "{resourceId:$FOUNDRY_ID/deployments/$MODEL,modelName:$MODEL,modelVersion:2026-09-29}" -o none
if ($?) { Write-Host "✨ Model $MODEL is published through $PROVIDER" }
# Give each caller 100,000 tokens per minute on the model, and show the model's policies
Write-Host "🔐 Policies on ${MODEL}:"
az aigateway model policy set-token-limit -g $RG --gateway-name $GATEWAY --provider-name $PROVIDER -n $MODEL `
--token-limit 100000Publish the gpt-6.1-sol alias
# Publish (or update) the gpt-6.1-sol alias, which Copilot sends in the model field, and show its target model
echo "🔖 Alias $MODEL and its target model:"
az aigateway model-alias set -g "$RG" --gateway-name "$GATEWAY" -n "$MODEL" \
--backend-model resource-id="$GATEWAY_ID/workspaces/default/modelProviders/$PROVIDER/models/$MODEL" \
--query "{alias:properties.aliasName, target:properties.backendModels[0].resourceId}"# Publish (or update) the gpt-6.1-sol alias, which Copilot sends in the model field, and show its target model
Write-Host "🔖 Alias $MODEL and its target model:"
az aigateway model-alias set -g $RG --gateway-name $GATEWAY -n $MODEL `
--backend-model resource-id="$GATEWAY_ID/workspaces/default/modelProviders/$PROVIDER/models/$MODEL" `
--query "{alias:properties.aliasName, target:properties.backendModels[0].resourceId}"az aigateway model-alias set creates the alias, or updates it if it exists, so you can run the step again.
Create the key for Copilot
api-key create returns metadata only. Read the value with list-secrets straight into a variable, so it never
appears on screen.
# Create the runtime key that Copilot uses, and show its state
echo "🔑 API key github-copilot and its state:"
az aigateway api-key create -g "$RG" --gateway-name "$GATEWAY" -n "$KEY_NAME" \
--query "{name:name, state:properties.state}"
# Read the key's value straight into a variable, so that it never shows on screen
AI_GATEWAY_API_KEY="$(az aigateway api-key list-secrets -g "$RG" --gateway-name "$GATEWAY" -n "$KEY_NAME" \
--query primaryKey -o tsv)" && export AI_GATEWAY_API_KEY
echo "🔑 Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"# Create the runtime key that Copilot uses, and show its state
Write-Host "🔑 API key github-copilot and its state:"
az aigateway api-key create -g $RG --gateway-name $GATEWAY -n $KEY_NAME `
--query "{name:name, state:properties.state}"
# Read the key's value straight into an environment variable, so that it never shows on screen
$env:AI_GATEWAY_API_KEY = az aigateway api-key list-secrets -g $RG --gateway-name $GATEWAY -n $KEY_NAME `
--query primaryKey -o tsv
Write-Host "🔑 Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"The model output shows one policy with "type": "tokenLimit" and "count": 100000, the alias output shows your
model's ID as target, and the key output shows github-copilot as active.
What you need: only the one-time setup from Before you begin. This track doesn't use your gateway from lab 02:
azd up creates a new one, so it works on its own.
Review the templates
infra/main.bicep creates the resource group rg-<environment name> and calls the quick start's
resources.bicep for the gateway, a Foundry account with gpt-5-mini, and the
foundry-models provider. Then it calls infra/copilot-model.bicep to publish gpt-6.1-sol for Copilot, and lab
04's tool-server.bicep to publish the Microsoft Learn MCP server
that Publish Microsoft Learn tools for Copilot uses:
// Lab 24 with azd: "azd up" creates the resource group rg-<environment name>, the quick start's gateway, Foundry
// account, and default model, then publishes gpt-6.1-sol for GitHub Copilot with its token limit and the
// github-copilot runtime API key, and registers the Microsoft Learn MCP server as learn. The key value is never an output.
targetScope = 'subscription'
@description('azd environment name. The resource group is rg-<environmentName>.')
@minLength(1)
@maxLength(60)
param environmentName string
@description('Region for every resource. Pick one where AI Gateway and the lab\'s Foundry models are available. List them with az provider show --namespace Microsoft.ApiManagement (Setup guide, Find the available regions).')
@metadata({ azd: { type: 'location' } })
param location string
@description('Model to deploy and publish for Copilot. The deployment, the backend model, and the alias use this name. azd reads it from BYOK_MODEL.')
param byokModelName string = 'gpt-6.1-sol'
@description('Version of that model. azd reads it from BYOK_MODEL_VERSION.')
param byokModelVersion string = '2026-09-29'
@description('Deployment SKU. Use DataZoneStandard if your GlobalStandard quota for the model is used up. azd reads it from BYOK_MODEL_SKU.')
@allowed([
'GlobalStandard'
'DataZoneStandard'
])
param byokModelSku string = 'GlobalStandard'
@description('Deployment capacity in thousands of tokens per minute. azd reads it from BYOK_MODEL_CAPACITY.')
@minValue(1)
param byokModelCapacity int = 100
@description('Tokens per minute that each caller identity can use on the model through the gateway. azd reads it from BYOK_TOKENS_PER_MINUTE.')
@minValue(1000)
param tokensPerMinute int = 100000
var suffix = take(uniqueString(subscription().id, environmentName, location), 6)
var tags = { 'azd-env-name': environmentName }
resource rg 'Microsoft.Resources/resourceGroups@2024-03-01' = {
name: 'rg-${environmentName}'
location: location
tags: tags
}
// The quick start's template: a gateway, a Foundry account with gpt-5-mini, the foundry-models provider, and a key.
module base '../../quickstart/infra/resources.bicep' = {
name: 'aigw-base'
scope: rg
params: {
location: location
tags: tags
gatewayName: 'aigw-${suffix}'
foundryName: 'aigw${suffix}'
}
}
// gpt-6.1-sol in the same Foundry account, under the same provider, with its token limit and the github-copilot key.
module copilot 'copilot-model.bicep' = {
name: 'aigw-copilot-model'
scope: rg
params: {
gatewayName: base.outputs.gatewayName
foundryAccountId: base.outputs.foundryId
providerName: base.outputs.providerName
modelName: byokModelName
modelVersion: byokModelVersion
skuName: byokModelSku
capacity: byokModelCapacity
tokensPerMinute: tokensPerMinute
apiKeyName: 'github-copilot'
}
}
// Lab 04's template: the public Microsoft Learn MCP server, published as learn.
module learn '../../04-federate-mcp-tools/infra/tool-server.bicep' = {
name: 'aigw-learn-mcp'
scope: rg
params: {
gatewayName: base.outputs.gatewayName
serverName: 'learn'
namespace: 'learn'
}
}
output AZURE_RESOURCE_GROUP string = rg.name
output AI_GATEWAY_NAME string = base.outputs.gatewayName
output AI_GATEWAY_ID string = base.outputs.gatewayId
output AI_GATEWAY_URL string = base.outputs.gatewayUrl
output AI_GATEWAY_PROVIDER string = base.outputs.providerName
output AI_GATEWAY_BACKEND_MODEL string = byokModelName
output AI_GATEWAY_MODEL string = copilot.outputs.aliasName
output AI_GATEWAY_KEY_NAME string = copilot.outputs.apiKeyName
output AI_GATEWAY_MODEL_ENDPOINT string = copilot.outputs.modelEndpoint
output AI_GATEWAY_MCP_URL string = learn.outputs.mcpEndpoint
output FOUNDRY_ACCOUNT_NAME string = base.outputs.foundryNameinfra/copilot-model.bicep deploys gpt-6.1-sol in the Foundry account with infra/deployment.bicep, registers it
under the provider with a limit of 100,000 tokens per minute for each caller, publishes the gpt-6.1-sol alias, and
creates the github-copilot key. It doesn't assign a role: the quick start's template already gave the gateway's
identity the Foundry User role on the account, which covers the new deployment. You can also deploy it on its own
to your gateway from lab 02.
// Publishes gpt-6.1-sol through an existing AI Gateway so GitHub Copilot can use it as a bring-your-own-key model.
// main.bicep calls it after the quick start's template, and you can also deploy it on its own to a gateway you already
// have, such as the one from lab 02. It adds a gpt-6.1-sol deployment to the Foundry account the gateway already uses,
// registers it under the gateway's existing Foundry provider with a per-caller token limit, publishes the gpt-6.1-sol
// alias, and creates the github-copilot runtime API key. The key value is never an output.
// The gateway's identity already has the Foundry User role on the account (from lab 02 or the quick start), and that
// role covers the new deployment, so this template doesn't assign it again.
targetScope = 'resourceGroup'
@description('Name of the existing AI Gateway (Microsoft.ApiManagement/aigateways) in this resource group.')
param gatewayName string
@description('Resource ID of the Foundry (Azure AI Services) account that the gateway uses. It can be in another resource group.')
param foundryAccountId string
@description('Model to deploy and publish. The deployment and the alias both use this name.')
param modelName string = 'gpt-6.1-sol'
@description('Version of the model to deploy.')
param modelVersion string = '2026-09-29'
@description('Deployment SKU. Use DataZoneStandard if your GlobalStandard quota for the model is used up.')
@allowed([
'GlobalStandard'
'DataZoneStandard'
])
param skuName string = 'GlobalStandard'
@description('Deployment capacity in thousands of tokens per minute. Coding agents send large prompts, so give them room.')
@minValue(1)
param capacity int = 100
@description('Tokens per minute that each caller identity can use on the model through the gateway.')
@minValue(1000)
param tokensPerMinute int = 100000
@description('Name of the existing Foundry provider in the gateway, for example foundry-models from lab 02 or the quick start.')
param providerName string = 'foundry-models'
@description('Name of the runtime API key that GitHub Copilot uses.')
param apiKeyName string = 'github-copilot'
var foundrySubscriptionId = split(foundryAccountId, '/')[2]
var foundryResourceGroup = split(foundryAccountId, '/')[4]
module deployment 'deployment.bicep' = {
name: take('deploy-${modelName}', 64)
scope: resourceGroup(foundrySubscriptionId, foundryResourceGroup)
params: {
accountName: last(split(foundryAccountId, '/'))
modelName: modelName
modelVersion: modelVersion
skuName: skuName
capacity: capacity
}
}
#disable-next-line BCP081
resource aiGateway 'Microsoft.ApiManagement/aigateways@2026-11-01' existing = {
name: gatewayName
}
#disable-next-line BCP081
resource defaultWorkspace 'Microsoft.ApiManagement/aigateways/workspaces@2026-11-01' existing = {
parent: aiGateway
name: 'default'
}
#disable-next-line BCP081
resource provider 'Microsoft.ApiManagement/aigateways/workspaces/modelProviders@2026-11-01' existing = {
parent: defaultWorkspace
name: providerName
}
#disable-next-line BCP081
resource model 'Microsoft.ApiManagement/aigateways/workspaces/modelProviders/models@2026-11-01' = {
parent: provider
name: modelName
properties: {
displayName: modelName
description: 'Foundry deployment ${modelName} published through AI Gateway for GitHub Copilot.'
supportedEndpoints: [
'/openai/v1/chat/completions'
'/openai/v1/responses'
]
deployment: {
resourceId: '${foundryAccountId}/deployments/${deployment.outputs.deploymentName}'
modelName: modelName
modelVersion: modelVersion
}
policies: [
{
type: 'tokenLimit'
period: 'minute'
count: tokensPerMinute
counterKey: [
'identity'
]
}
]
}
}
#disable-next-line BCP081
resource alias 'Microsoft.ApiManagement/aigateways/workspaces/aliases@2026-11-01' = {
parent: defaultWorkspace
name: modelName
properties: {
backendModels: [
{ resourceId: model.id }
]
}
}
#disable-next-line BCP081
resource apiKey 'Microsoft.ApiManagement/aigateways/apiKeys@2026-11-01' = {
parent: aiGateway
name: apiKeyName
properties: {
displayName: 'GitHub Copilot'
}
}
output aliasName string = alias.name
output apiKeyName string = apiKey.name
output modelEndpoint string = 'https://${aiGateway.properties.frontend.defaultHostname}/default/models/openai/v1'// Adds one model deployment to an existing Foundry (Azure AI Services) account.
targetScope = 'resourceGroup'
param accountName string
param modelName string
param modelVersion string
param skuName string
param capacity int
resource account 'Microsoft.CognitiveServices/accounts@2025-04-01-preview' existing = {
name: accountName
}
resource deployment 'Microsoft.CognitiveServices/accounts/deployments@2025-04-01-preview' = {
parent: account
name: modelName
sku: {
name: skuName
capacity: capacity
}
properties: {
model: {
name: modelName
format: 'OpenAI'
version: modelVersion
}
}
}
output deploymentName string = deployment.nameDeploy with azd up
Move into the lab's folder, create an azd environment named aigw-lab24 in your current subscription, then provision
everything. It takes two to four minutes.
# Move into the lab's folder, which holds the azd project
cd ~/aigateway/labs/24-github-copilot-byok &&
echo "📂 Lab folder: $(pwd)"
# Create an azd environment in your current subscription, so that azd doesn't prompt you
azd env new aigw-lab24 --location eastus2 --subscription "$(az account show --query id --output tsv)" &&
echo "📝 azd environment aigw-lab24 deploys to eastus2"
# Provision the gateway, Foundry with both models, the alias, the key, and the learn MCP server
azd up &&
echo "🚀 Gateway deployed: $(azd env get-value AI_GATEWAY_URL)"# Move into the lab's folder, which holds the azd project
Set-Location ~/aigateway/labs/24-github-copilot-byok
if ($?) { Write-Host "📂 Lab folder: $(Get-Location)" }
# Create an azd environment in your current subscription, so that azd doesn't prompt you
azd env new aigw-lab24 --location eastus2 --subscription (az account show --query id --output tsv)
if ($?) { Write-Host "📝 azd environment aigw-lab24 deploys to eastus2" }
# Provision the gateway, Foundry with both models, the alias, the key, and the learn MCP server
azd up
if ($?) { Write-Host "🚀 Gateway deployed: $(azd env get-value AI_GATEWAY_URL)" }For another region, pick one where AI Gateway and the gpt-5-mini and gpt-6.1-sol models are available, as in Find
the available regions. If the Foundry deployment fails
with InsufficientQuota, deploy gpt-6.1-sol with the Data Zone Standard SKU instead, and provision again:
# Deploy gpt-6.1-sol with the Data Zone Standard SKU instead of Global Standard
azd env set BYOK_MODEL_SKU DataZoneStandard &&
echo "📝 BYOK_MODEL_SKU is DataZoneStandard"
# Provision again, with the new SKU
azd provision &&
echo "🚀 Provisioning is done, with gpt-6.1-sol on Data Zone Standard"# Deploy gpt-6.1-sol with the Data Zone Standard SKU instead of Global Standard
azd env set BYOK_MODEL_SKU DataZoneStandard
if ($?) { Write-Host "📝 BYOK_MODEL_SKU is DataZoneStandard" }
# Provision again, with the new SKU
azd provision
if ($?) { Write-Host "🚀 Provisioning is done, with gpt-6.1-sol on Data Zone Standard" }Read the outputs and the key
Set the variables that the rest of the lab uses from azd's environment values, and read the github-copilot key from
the gateway, so that it never shows on screen.
# Read the names of what azd created, the model, and the key from azd's environment values
export RG="$(azd env get-value AZURE_RESOURCE_GROUP)"
export GATEWAY="$(azd env get-value AI_GATEWAY_NAME)"
export PROVIDER="$(azd env get-value AI_GATEWAY_PROVIDER)"
export MODEL="$(azd env get-value AI_GATEWAY_BACKEND_MODEL)"
export KEY_NAME="$(azd env get-value AI_GATEWAY_KEY_NAME)"
# Read the gateway's resource ID, runtime URL, and alias
export GATEWAY_ID="$(azd env get-value AI_GATEWAY_ID)"
export AI_GATEWAY_URL="$(azd env get-value AI_GATEWAY_URL)"
export AI_GATEWAY_MODEL="$(azd env get-value AI_GATEWAY_MODEL)"
# Read the github-copilot key from the gateway, so that it never lands in a file or a deployment log
export AI_GATEWAY_API_KEY="$(az aigateway api-key list-secrets --ids "$GATEWAY_ID/apiKeys/$KEY_NAME" \
--query primaryKey --output tsv)"
echo "📝 Gateway $GATEWAY in $RG, with provider $PROVIDER and model $MODEL"
echo "🌐 Runtime URL: $AI_GATEWAY_URL"
echo "🔖 Model alias: $AI_GATEWAY_MODEL"
echo "🔑 Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"
# Print the base URL that Copilot needs
echo "🌐 Base URL for Copilot:"
azd env get-value AI_GATEWAY_MODEL_ENDPOINT# Read the names of what azd created, the model, and the key from azd's environment values
$RG = azd env get-value AZURE_RESOURCE_GROUP
$GATEWAY = azd env get-value AI_GATEWAY_NAME
$PROVIDER = azd env get-value AI_GATEWAY_PROVIDER
$MODEL = azd env get-value AI_GATEWAY_BACKEND_MODEL
$KEY_NAME = azd env get-value AI_GATEWAY_KEY_NAME
# Read the gateway's resource ID, runtime URL, and alias
$GATEWAY_ID = azd env get-value AI_GATEWAY_ID
$env:AI_GATEWAY_URL = azd env get-value AI_GATEWAY_URL
$env:AI_GATEWAY_MODEL = azd env get-value AI_GATEWAY_MODEL
# Read the github-copilot key from the gateway, so that it never lands in a file or a deployment log
$env:AI_GATEWAY_API_KEY = az aigateway api-key list-secrets --ids "$GATEWAY_ID/apiKeys/$KEY_NAME" `
--query primaryKey --output tsv
Write-Host "📝 Gateway $GATEWAY in $RG, with provider $PROVIDER and model $MODEL"
Write-Host "🌐 Runtime URL: $env:AI_GATEWAY_URL"
Write-Host "🔖 Model alias: $env:AI_GATEWAY_MODEL"
Write-Host "🔑 Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"
# Print the base URL that Copilot needs
Write-Host "🌐 Base URL for Copilot:"
azd env get-value AI_GATEWAY_MODEL_ENDPOINTazd up ended with SUCCESS, and the last command printed the base URL that Copilot needs, under
🌐 Base URL for Copilot:, ending in /default/models/openai/v1. In the portal, ModelsAliases lists
gpt-6.1-sol.
What you need: only the one-time setup from Before you begin, plus Terraform 1.9 or later, as in
Deploy a lab with Terraform. This track doesn't use your gateway from
lab 02: terraform apply creates a new one, so it works on its own.
Review the configuration
terraform/main.tf creates the resource group rg-<environment_name> and calls the quick start's
resources module for the gateway, a Foundry account with gpt-5-mini, and the
foundry-models provider:
# Lab 24 with Terraform: creates the resource group rg-<environment_name>, the quick start's gateway, Foundry model,
# default alias, and runtime API key, then publishes gpt-6.1-sol for GitHub Copilot with its token limit and the
# github-copilot runtime API key (copilot-model.tf), and registers the Microsoft Learn MCP server as learn
# (tool-server.tf). No key value is ever an output.
data "azapi_client_config" "current" {}
locals {
suffix = substr(sha1("${data.azapi_client_config.current.subscription_id}/${var.environment_name}/${var.location}"), 0, 6)
tags = { "environment-name" = var.environment_name }
}
resource "azurerm_resource_group" "rg" {
name = "rg-${var.environment_name}"
location = var.location
tags = local.tags
}
# The quick start's module: a gateway, gpt-5-mini behind the default alias, and the app-first-call key.
module "base" {
source = "../../quickstart/terraform/resources"
subscription_id = data.azapi_client_config.current.subscription_id
resource_group_name = azurerm_resource_group.rg.name
resource_group_id = azurerm_resource_group.rg.id
location = var.location
tags = local.tags
gateway_name = "aigw-${local.suffix}"
foundry_name = "aigw${local.suffix}"
}terraform/copilot-model.tf deploys gpt-6.1-sol in the same Foundry account, then uses the azapi provider, which
sends the AI Gateway API version, 2026-11-01, as is, to register the deployment as a model with its token limit,
publish the gpt-6.1-sol alias, and create the github-copilot key:
# Publishes gpt-6.1-sol for GitHub Copilot: a deployment in the quick start's Foundry account, a backend model under
# the quick start's Foundry provider with a per-caller token limit, the gpt-6.1-sol alias, and the github-copilot
# runtime API key. The gateway's Foundry User role on the account already covers the new deployment.
resource "azurerm_cognitive_deployment" "copilot" {
name = var.model_name
cognitive_account_id = module.base.foundry_id
sku {
name = var.model_sku
capacity = var.model_capacity
}
model {
format = "OpenAI"
name = var.model_name
version = var.model_version
}
}
resource "azapi_resource" "copilot_model" {
type = "Microsoft.ApiManagement/aigateways/workspaces/modelProviders/models@2026-11-01"
name = azurerm_cognitive_deployment.copilot.name
parent_id = module.base.provider_id
body = {
properties = {
displayName = var.model_name
description = "Foundry deployment ${var.model_name} published through AI Gateway for GitHub Copilot."
supportedEndpoints = [
"/openai/v1/chat/completions",
"/openai/v1/responses",
]
deployment = {
resourceId = azurerm_cognitive_deployment.copilot.id
modelName = var.model_name
modelVersion = var.model_version
}
# Each caller identity, here each API key, gets this many tokens per minute.
policies = [
{
type = "tokenLimit"
period = "minute"
count = var.tokens_per_minute
counterKey = ["identity"]
},
]
}
}
schema_validation_enabled = false
}
resource "azapi_resource" "copilot_alias" {
type = "Microsoft.ApiManagement/aigateways/workspaces/aliases@2026-11-01"
name = var.model_name
parent_id = module.base.workspace_id
body = {
properties = {
backendModels = [
{ resourceId = azapi_resource.copilot_model.id },
]
}
}
schema_validation_enabled = false
}
# The key that GitHub Copilot sends. Read its value with az aigateway api-key list-secrets.
resource "azapi_resource" "copilot_key" {
type = "Microsoft.ApiManagement/aigateways/apiKeys@2026-11-01"
name = "github-copilot"
parent_id = module.base.gateway_id
body = {
properties = {
displayName = "GitHub Copilot"
}
}
schema_validation_enabled = false
}terraform/tool-server.tf registers the Microsoft Learn MCP server as learn, the same toolServers resource as
lab 04's tool-server.bicep, for
Publish Microsoft Learn tools for Copilot:
# Registers the public Microsoft Learn MCP server as the federated MCP server learn, as lab 04 does. Clients call
# <gateway-url>/default/toolservers/learn/mcp, and the gateway publishes the backend's tools as learn_<tool>. The
# backend is required (mode failClosed), and the public server needs no credentials.
resource "azapi_resource" "learn" {
type = "Microsoft.ApiManagement/aigateways/workspaces/toolServers@2026-11-01"
name = "learn"
parent_id = module.base.workspace_id
body = {
properties = {
displayName = "Microsoft Learn"
description = "Search and fetch official Microsoft documentation and code samples."
toolServerType = "mcp"
endpoints = [
{
namespace = "learn"
kind = "mcp"
mode = "failClosed"
mcp = {
endpoint = { url = "https://learn.microsoft.com/api/mcp" }
transport = "streamableHttp"
}
},
]
}
}
schema_validation_enabled = false
}Deploy with terraform apply
Move into the lab's Terraform folder, select your current subscription, then plan and apply the configuration. It takes about three minutes.
# Move into the lab's Terraform folder
cd ~/aigateway/labs/24-github-copilot-byok/terraform &&
echo "📂 Terraform folder: $(pwd)"
# Deploy to the Azure CLI's current subscription
export ARM_SUBSCRIPTION_ID="$(az account show --query id --output tsv)" &&
echo "📍 Subscription: $ARM_SUBSCRIPTION_ID"
# Download the providers, then plan and apply the gateway, Foundry with both models, the alias, the key, and the
# learn MCP server
terraform init &&
terraform plan -out tfplan &&
terraform apply tfplan &&
echo "🚀 Gateway deployed: $(terraform output -raw ai_gateway_url)"# Move into the lab's Terraform folder
Set-Location ~/aigateway/labs/24-github-copilot-byok/terraform
if ($?) { Write-Host "📂 Terraform folder: $(Get-Location)" }
# Deploy to the Azure CLI's current subscription
$env:ARM_SUBSCRIPTION_ID = az account show --query id --output tsv
if ($?) { Write-Host "📍 Subscription: $env:ARM_SUBSCRIPTION_ID" }
# Download the providers, then plan and apply the gateway, Foundry with both models, the alias, the key, and the
# learn MCP server
terraform init
if ($?) { terraform plan -out tfplan }
if ($?) { terraform apply tfplan }
if ($?) { Write-Host "🚀 Gateway deployed: $(terraform output -raw ai_gateway_url)" }The configuration deploys to eastus2. For another region where AI Gateway and the gpt-5-mini and gpt-6.1-sol
models are available, as in Find the available regions, run
export TF_VAR_location=<region> (PowerShell: $env:TF_VAR_location = "<region>") before terraform plan. If the
Foundry deployment fails with InsufficientQuota, deploy gpt-6.1-sol with the Data Zone Standard SKU instead, and
apply again:
# Deploy gpt-6.1-sol with the Data Zone Standard SKU instead of Global Standard
export TF_VAR_model_sku=DataZoneStandard &&
echo "📝 TF_VAR_model_sku is DataZoneStandard"
# Plan and apply again, with the new SKU
terraform plan -out tfplan &&
terraform apply tfplan &&
echo "🚀 Apply is done, with gpt-6.1-sol on Data Zone Standard"# Deploy gpt-6.1-sol with the Data Zone Standard SKU instead of Global Standard
$env:TF_VAR_model_sku = "DataZoneStandard"
if ($?) { Write-Host "📝 TF_VAR_model_sku is DataZoneStandard" }
# Plan and apply again, with the new SKU
terraform plan -out tfplan
if ($?) { terraform apply tfplan }
if ($?) { Write-Host "🚀 Apply is done, with gpt-6.1-sol on Data Zone Standard" }Keep TF_VAR_model_sku set for later plans: without it, the next plan moves the deployment back to Global Standard.
Read the outputs and the key
Set the variables that the rest of the lab uses from the Terraform outputs, read the github-copilot key from the
gateway, so that it never shows on screen or lands in the Terraform state, then move back to the lab folder.
# Read the names of what Terraform created, the model, and the key from the outputs
export RG="$(terraform output -raw azure_resource_group)"
export GATEWAY="$(terraform output -raw ai_gateway_name)"
export PROVIDER="$(terraform output -raw ai_gateway_provider)"
export MODEL="$(terraform output -raw ai_gateway_backend_model)"
export KEY_NAME="$(terraform output -raw ai_gateway_key_name)"
# Read the gateway's resource ID, runtime URL, and alias
export GATEWAY_ID="$(terraform output -raw ai_gateway_id)"
export AI_GATEWAY_URL="$(terraform output -raw ai_gateway_url)"
export AI_GATEWAY_MODEL="$(terraform output -raw ai_gateway_model)"
# Read the github-copilot key from the gateway, so that it never lands in a file or the Terraform state
export AI_GATEWAY_API_KEY="$(az aigateway api-key list-secrets --ids "$GATEWAY_ID/apiKeys/$KEY_NAME" \
--query primaryKey --output tsv)"
echo "📝 Gateway $GATEWAY in $RG, with provider $PROVIDER and model $MODEL"
echo "🌐 Runtime URL: $AI_GATEWAY_URL"
echo "🔖 Model alias: $AI_GATEWAY_MODEL"
echo "🔑 Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"
# Print the base URL that Copilot needs, then move back to the lab folder
echo "🌐 Base URL for Copilot:"
terraform output -raw ai_gateway_model_endpoint && echo && cd ..# Read the names of what Terraform created, the model, and the key from the outputs
$RG = terraform output -raw azure_resource_group
$GATEWAY = terraform output -raw ai_gateway_name
$PROVIDER = terraform output -raw ai_gateway_provider
$MODEL = terraform output -raw ai_gateway_backend_model
$KEY_NAME = terraform output -raw ai_gateway_key_name
# Read the gateway's resource ID, runtime URL, and alias
$GATEWAY_ID = terraform output -raw ai_gateway_id
$env:AI_GATEWAY_URL = terraform output -raw ai_gateway_url
$env:AI_GATEWAY_MODEL = terraform output -raw ai_gateway_model
# Read the github-copilot key from the gateway, so that it never lands in a file or the Terraform state
$env:AI_GATEWAY_API_KEY = az aigateway api-key list-secrets --ids "$GATEWAY_ID/apiKeys/$KEY_NAME" `
--query primaryKey --output tsv
Write-Host "📝 Gateway $GATEWAY in $RG, with provider $PROVIDER and model $MODEL"
Write-Host "🌐 Runtime URL: $env:AI_GATEWAY_URL"
Write-Host "🔖 Model alias: $env:AI_GATEWAY_MODEL"
Write-Host "🔑 Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"
# Print the base URL that Copilot needs, then move back to the lab folder
Write-Host "🌐 Base URL for Copilot:"
terraform output -raw ai_gateway_model_endpoint
if ($?) { Write-Host ""; Set-Location .. }terraform apply ended with Apply complete! Resources: 14 added, 0 changed, 0 destroyed., and the last command
printed the base URL that Copilot needs, under 🌐 Base URL for Copilot:, ending in /default/models/openai/v1.
In the portal, ModelsAliases lists gpt-6.1-sol.
Test the endpoint
Before you configure Copilot, call the alias the way Copilot does: the Responses API with a bearer token.
# Call the alias the way Copilot does: the Responses API, with the key as a bearer token
curl -sS "${AI_GATEWAY_URL%/}/default/models/openai/v1/responses" \
-H "Authorization: Bearer $AI_GATEWAY_API_KEY" -H "Content-Type: application/json" \
-d "{\"model\":\"$AI_GATEWAY_MODEL\",\"input\":\"In one sentence, what is a code review for?\"}" \
| jq -r 'if .output then "✨ Model: \(.model)",
"🤖 \([.output[] | select(.type == "message") | .content[] | select(.type == "output_text") | .text] | join(""))"
else "🚨 \(.error.message // .)" end'# Build the request: the alias in model, and one input
$body = @{ model = $env:AI_GATEWAY_MODEL; input = "In one sentence, what is a code review for?" } | ConvertTo-Json
# Call the alias the way Copilot does: the Responses API, with the key as a bearer token
$reply = Invoke-RestMethod -Method Post `
-Uri "$($env:AI_GATEWAY_URL.TrimEnd('/'))/default/models/openai/v1/responses" `
-Headers @{ Authorization = "Bearer $env:AI_GATEWAY_API_KEY" } -ContentType "application/json" -Body $body
if ($?) { Write-Host "✨ Model: $($reply.model)" }
if ($?) { Write-Host "🤖 $(($reply.output | Where-Object type -eq 'message').content.text -join '')" }Expected output (your text differs):
✨ Model: gpt-6.1-sol
🤖 A code review checks changes for bugs, clarity, and consistency before they're merged.A new alias, policy, or key can take a minute to apply. If the call returns 401 or 404, wait a minute and try
again.
Connect VS Code
VS Code adds your own models through a Custom Endpoint model group. It stores the key in its secret storage and
the rest in chatLanguageModels.json.
Add the gateway as a custom endpoint
Open the practice project in VS Code, for example with
code ~/contoso-calc.Open the Command Palette (Ctrl+Shift+P, or Cmd+Shift+P on macOS) and run Chat: Manage Language Models. The Language Models editor opens.
Chat: Manage Language Models opens the Language Models editor. Add Models starts the custom endpoint setup. Select Add ModelsCustom Endpoint, and enter
AI Gatewayas the group name.Paste your
github-copilotkey into AI Gateway: API Key and press Enter. To copy it from the shell without printing it, runprintf %s "$AI_GATEWAY_API_KEY" | pbcopyon macOS, orSet-Clipboard $env:AI_GATEWAY_API_KEYin PowerShell.VS Code masks the key and keeps it in its secret storage, not in a settings file. In AI Gateway: API Type, select Responses.
Pick Responses. It becomes the default for every model in the group.
Add gpt-6.1-sol to the group
VS Code opens chatLanguageModels.json with the new group. The gateway has no model list to discover, so add the
model to models yourself. Print the URL to paste:
# Print the full Responses URL on your gateway, to paste into chatLanguageModels.json
echo "🌐 Responses URL: ${AI_GATEWAY_URL%/}/default/models/openai/v1/responses"Then make the group look like this. Keep the apiKey value that VS Code wrote: it points at the secret, not the key
itself.
[
{
"name": "AI Gateway",
"vendor": "customendpoint",
"apiKey": "${input:chat.lm.secret.<id>}",
"apiType": "responses",
"models": [
{
"id": "gpt-6.1-sol",
"name": "GPT-6.1 Sol (AI Gateway)",
"url": "https://<gateway-host>/default/models/openai/v1/responses",
"toolCalling": true,
"vision": true,
"maxInputTokens": 128000,
"maxOutputTokens": 16000
}
]
}
]| Field | What it does |
|---|---|
id | The alias, sent as model in each request. |
name | The label in the model picker. Copilot already offers a built-in GPT-6.1 Sol, so a distinct name tells them apart. |
url | The full Responses URL on your gateway. |
toolCalling | Tells VS Code that the model can call tools, which agent mode needs. |
maxInputTokens, maxOutputTokens | How much context VS Code sends and how long a reply it asks for. |
Save the file.
Pick the model and run an agent task
Open the Chat view (Ctrl+Alt+I, or Ctrl+Cmd+I on macOS) and select Agent.
Open the model picker, select the AI Gateway tab, and select GPT-6.1 Sol (AI Gateway). If the model isn't listed, run Developer: Reload Window.
Models from the custom endpoint get their own tab in the model picker. Send this prompt:
TextFix the bug in calc.py and add a guard for division by zero
Copilot reads the file, changes add to return a + b, makes divide raise ZeroDivisionError when b is zero,
and checks its work. Review the diff and select Keep.
The chat input shows GPT-6.1 Sol (AI Gateway), and calc.py now adds correctly and refuses to divide by zero.
Without a GitHub sign-in, VS Code asks you to pick utility models for chat titles, commit messages, and pull
request descriptions. Set chat.utilityModel and chat.utilitySmallModel to your gateway model. Inline
suggestions still need a GitHub sign-in.
Connect the Copilot CLI
The Copilot CLI reads its provider from environment variables, so you can switch between the gateway and GitHub's models per terminal.
Point the CLI at the gateway
| Variable | Value |
|---|---|
COPILOT_PROVIDER_BASE_URL | https://<gateway-host>/default/models/openai/v1. Setting it turns on BYOK. |
COPILOT_PROVIDER_WIRE_API | responses. The default is completions. |
COPILOT_PROVIDER_API_KEY | Your github-copilot key, sent as a bearer token. |
COPILOT_MODEL | gpt-6.1-sol, the alias. |
COPILOT_OFFLINE | Optional. true also turns off the GitHub sign-in, telemetry, web tools, and the GitHub MCP server. |
# Point the Copilot CLI at the gateway's OpenAI-compatible base URL, over the Responses API
export COPILOT_PROVIDER_BASE_URL="${AI_GATEWAY_URL%/}/default/models/openai/v1"
export COPILOT_PROVIDER_WIRE_API="responses"
# Give the CLI the github-copilot key, which it sends as a bearer token, and the alias as its model
export COPILOT_PROVIDER_API_KEY="$AI_GATEWAY_API_KEY"
export COPILOT_MODEL="$AI_GATEWAY_MODEL"
echo "📝 Copilot CLI: $COPILOT_MODEL over the $COPILOT_PROVIDER_WIRE_API API"
echo "🌐 Base URL: $COPILOT_PROVIDER_BASE_URL"
echo "🔑 Key: in COPILOT_PROVIDER_API_KEY (${#COPILOT_PROVIDER_API_KEY} characters, not shown)"# Point the Copilot CLI at the gateway's OpenAI-compatible base URL, over the Responses API
$env:COPILOT_PROVIDER_BASE_URL = "$($env:AI_GATEWAY_URL.TrimEnd('/'))/default/models/openai/v1"
$env:COPILOT_PROVIDER_WIRE_API = "responses"
# Give the CLI the github-copilot key, which it sends as a bearer token, and the alias as its model
$env:COPILOT_PROVIDER_API_KEY = $env:AI_GATEWAY_API_KEY
$env:COPILOT_MODEL = $env:AI_GATEWAY_MODEL
Write-Host "📝 Copilot CLI: $env:COPILOT_MODEL over the $env:COPILOT_PROVIDER_WIRE_API API"
Write-Host "🌐 Base URL: $env:COPILOT_PROVIDER_BASE_URL"
Write-Host "🔑 Key: in COPILOT_PROVIDER_API_KEY ($($env:COPILOT_PROVIDER_API_KEY.Length) characters, not shown)"These variables last for the current terminal. Run copilot help environment for the full list.
Ask a quick question
copilot -p runs one prompt and exits:
# Move into the practice project
cd ~/contoso-calc &&
echo "📂 Practice project: ~/contoso-calc"
# Run one prompt on the gateway's model, then exit
echo "🤖 Copilot CLI answer:"
copilot -p "Which model are you? Answer in one short sentence."Expected output (your numbers differ):
📂 Practice project: ~/contoso-calc
🤖 Copilot CLI answer:
I'm powered by gpt-6.1-sol (model ID: gpt-6.1-sol).
Changes +0 -0
Duration 6s
Tokens ↑ 14.4k (14.4k written) • ↓ 24
Resume copilot --resume=<session-id>The Tokens line shows how much context even a short question carries. Resume reopens the session in interactive mode.
Run an agent task
Start an interactive session in the project, and select Yes when the CLI asks whether you trust the folder:
# Start an interactive Copilot CLI session in the practice project, on the gateway's model
echo "🚀 Starting the Copilot CLI on $COPILOT_MODEL (type /exit to leave)"
copilotSend this prompt:
Add a multiply function to calc.py and unittest tests in test_calc.py, then run themCopilot plans the change and asks before it edits a file or runs a command. Select Yes to approve each step, or Yes, and don't ask again to approve that kind of step for this folder.
The status bar shows gpt-6.1-sol, and the tests pass. If you skipped the VS Code section, Copilot may also fix
add when the first test run fails. Type /exit to leave the session.
Connect the Copilot SDK
The GitHub Copilot SDK runs the same agent as the CLI inside your own app.
Pass a provider when you create a session, and the session sends its model calls to the gateway. The SDK packages
bring the Copilot runtime with them, so you don't need to install the CLI. No GitHub sign-in is needed.
Review the samples
The samples read AI_GATEWAY_URL, AI_GATEWAY_API_KEY, and, optionally, AI_GATEWAY_MODEL from the environment,
then ask the agent which model it is and to list the files in the current folder. They also read
AI_GATEWAY_MCP_URL, which you set later in Add the Learn tools to the Copilot SDK. approveAll lets the agent run
tools without asking, which suits a sample. In an app, decide which tools to allow in onPermissionRequest.
// Runs a GitHub Copilot SDK agent session on gpt-6.1-sol published by Azure AI Gateway (bring your own key).
// Set AI_GATEWAY_URL and AI_GATEWAY_API_KEY first. No GitHub sign-in is needed: every model call goes to the gateway.
// Set AI_GATEWAY_MCP_URL too, and the agent also gets the tools of an MCP server that the gateway publishes.
import { CopilotClient, approveAll, type MCPServerConfig } from "@github/copilot-sdk";
const gatewayUrl = process.env.AI_GATEWAY_URL?.replace(/\/$/, "");
const apiKey = process.env.AI_GATEWAY_API_KEY;
const model = process.env.AI_GATEWAY_MODEL ?? "gpt-6.1-sol";
const mcpUrl = process.env.AI_GATEWAY_MCP_URL;
if (!gatewayUrl || !apiKey) {
throw new Error("Set AI_GATEWAY_URL and AI_GATEWAY_API_KEY first.");
}
// The MCP server gets the key as a bearer token, like the model calls.
const mcpServers: Record<string, MCPServerConfig> = mcpUrl
? { "ai-gateway-learn": { type: "http", url: mcpUrl, headers: { Authorization: `Bearer ${apiKey}` }, tools: ["*"] } }
: {};
const client = new CopilotClient();
try {
const session = await client.createSession({
model,
provider: {
type: "openai",
baseUrl: `${gatewayUrl}/default/models/openai/v1`,
apiKey,
wireApi: "responses",
},
mcpServers,
onPermissionRequest: approveAll,
});
const prompt = process.argv.slice(2).join(" ") || "Which model are you? Then list the files in this folder.";
const reply = await session.sendAndWait({ prompt });
console.log(reply?.data.content);
await session.disconnect();
} finally {
await client.stop();
}"""Runs a GitHub Copilot SDK agent session on gpt-6.1-sol published by Azure AI Gateway (bring your own key).
Set AI_GATEWAY_URL and AI_GATEWAY_API_KEY first. No GitHub sign-in is needed: every model call goes to the gateway.
Set AI_GATEWAY_MCP_URL too, and the agent also gets the tools of an MCP server that the gateway publishes.
"""
import asyncio
import os
import sys
from copilot import CopilotClient, PermissionHandler
async def main() -> None:
gateway_url = os.environ["AI_GATEWAY_URL"].rstrip("/")
api_key = os.environ["AI_GATEWAY_API_KEY"]
model = os.environ.get("AI_GATEWAY_MODEL", "gpt-6.1-sol")
mcp_url = os.environ.get("AI_GATEWAY_MCP_URL")
# The MCP server gets the key as a bearer token, like the model calls.
headers = {"Authorization": f"Bearer {api_key}"}
mcp_servers = (
{"ai-gateway-learn": {"type": "http", "url": mcp_url, "headers": headers, "tools": ["*"]}}
if mcp_url
else {}
)
client = CopilotClient()
await client.start()
try:
session = await client.create_session(
model=model,
provider={
"type": "openai",
"base_url": f"{gateway_url}/default/models/openai/v1",
"api_key": api_key,
"wire_api": "responses",
},
mcp_servers=mcp_servers,
on_permission_request=PermissionHandler.approve_all,
)
prompt = " ".join(sys.argv[1:]) or "Which model are you? Then list the files in this folder."
reply = await session.send_and_wait(prompt, timeout=180)
print(reply.data.content if reply else "(no reply)")
await session.disconnect()
finally:
await client.stop()
if __name__ == "__main__":
asyncio.run(main())Run a sample
Run the commands from the lab folder (labs/24-github-copilot-byok).
# Install the samples' dependencies in the infra folder: the Copilot SDK, which brings the Copilot runtime with it
cd infra
npm install # @github/copilot-sdk
echo "📦 The Copilot SDK for TypeScript is installed"
# Run the sample: the agent says which model it is, and lists the files in the folder
echo "🤖 Agent reply:"
npm start # runs copilot-sdk.ts on Node.js 22.18 or later# Install the samples' dependencies in the infra folder: the Copilot SDK, which brings the Copilot runtime with it
cd infra
pip install -r requirements.txt # github-copilot-sdk
echo "📦 The Copilot SDK for Python is installed"
# Run the sample: the agent says which model it is, and lists the files in the folder
echo "🤖 Agent reply:"
python copilot_sdk.pyExpected output (your text differs):
🤖 Agent reply:
I'm powered by gpt-6.1-sol (model ID: gpt-6.1-sol).
Files in this folder:
- copilot-model.bicep
- copilot-sdk.ts
- copilot_sdk.py
- deployment.bicep
- main.bicep
- main.parameters.json
- package.json
- requirements.txtThe samples print the agent's last message. If the agent answers in two messages, you see only the file list.
To send your own prompt, pass it as an argument, for example npm start -- "Summarize package.json" or
python copilot_sdk.py "Summarize requirements.txt".
The sample names gpt-6.1-sol and lists the folder's files.
Connect the GitHub Copilot app
The GitHub Copilot app is a desktop app for running Copilot agent sessions across your projects. It adds your own models as model providers and keeps their keys in the system credential store.
The GitHub Copilot app is in public preview, and its screens change often. These steps follow Use BYOK models in the GitHub Copilot app. The picture below is an illustration, not a screenshot, so labels in your version can differ.
Add the gateway as a model provider
Open the GitHub Copilot app and sign in with your GitHub account.
Open the app settings and select Model providersAdd provider.
Select Any OpenAI-compatible HTTP endpoint. Don't pick Azure OpenAI or Microsoft Foundry: they expect those services' own URLs and keys.
Enter the provider details:
Field Value Display name AI GatewayBase URL https://<gateway-host>/default/models/openai/v1API key Your github-copilotkeyWire API, if shown Responses The gateway doesn't serve a
/modelslist, so the app can't discover its models. Add the model by hand with the model IDgpt-6.1-sol.Select Add provider.
Start a session on gpt-6.1-sol
The provider's models appear in the model picker next to GitHub's. Start a session on the contoso-calc folder,
select gpt-6.1-sol from the AI Gateway provider, and ask a question, for example
Which model are you, and what does calc.py do?.
The reply names gpt-6.1-sol, and the request shows up in the gateway's Monitoring under the github-copilot key.
Publish Microsoft Learn tools for Copilot
Copilot's agents call tools as well as models. Publish an MCP server through the same gateway, and Copilot's tool
calls get the same controls as its model calls: one key that you can suspend, one endpoint per tool server, and one
place to decide which tools agents see. Here, the gateway publishes the public Microsoft Learn MCP server as learn,
so Copilot can look up current Microsoft documentation while it codes on gpt-6.1-sol.
Each Copilot surface then has two connections to the gateway:
| Model | MCP server | |
|---|---|---|
| URL | https://<gateway-host>/default/models/openai/v1 | https://<gateway-host>/default/toolservers/learn/mcp |
| How the key is sent | Authorization: Bearer <key> | The same Authorization: Bearer <key> header, which you set yourself |
| Key | github-copilot | The same github-copilot key. It needs no extra setup. |
Learn results are large: one search returns 25 to 50 KB of text. Copilot keeps big results out of the prompt where it can, but tasks that use the tools still send more tokens. In testing, a one-shot question that used one search sent about 51,000 input tokens, and the agent task in the CLI section sent about 150,000 over seven minutes, within the 100,000 tokens-per-minute limit.
If you did Federate MCP tools behind one endpoint, your gateway already
has learn. Skip to Test the MCP endpoint.
Create the learn server with one backend, https://learn.microsoft.com/api/mcp, under the namespace learn. The
Learn server is public, so the backend needs no credentials. Pick a track.
Register the Learn server
- Open the AI Gateway portal, select your gateway, and select MCP serversAdd MCP server.
- On Basic info, set Name to
learn, Display name toMicrosoft Learn, and Description toSearch and fetch official Microsoft documentation and code samples.In Supported MCP versions, select2025-06-18, the version that the Learn server reports. Select Next. - On Backends, select Add backendMCP server. Set Endpoint URL to
https://learn.microsoft.com/api/mcp, keep Authentication at None, and set Namespace tolearn. Select Add, then Next, which saves the server and opens Tools. - On Tools, keep Allow all tools, and select Create.
Register the Learn MCP server in lab 04 explains each field.
Copy the endpoint
When the server is ready, copy the Endpoint URL from its details page. It ends in
/default/toolservers/learn/mcp.
MCP servers lists learn with one backend in the namespace learn.
Register the Learn server
az aigateway mcp create registers the MCP server. --endpoints takes the backends as a JSON array.
# Register the public Microsoft Learn MCP server as learn, with one backend in the learn namespace and no credentials
MCP_ENDPOINT="$(az aigateway mcp create -g "$RG" --gateway-name "$GATEWAY" -n learn \
--display-name "Microsoft Learn" \
--description "Search and fetch official Microsoft documentation and code samples." \
--endpoints '[{"kind": "mcp", "namespace": "learn", "required": true,
"mcp": {"url": "https://learn.microsoft.com/api/mcp", "transport": "streamableHttp"}}]' \
--query "properties.gatewayEndpoints[0].url" -o tsv)" &&
echo "🔌 MCP server learn is ready: $MCP_ENDPOINT"# Write the backend to a file: the public Microsoft Learn MCP server, in the learn namespace, with no credentials
ConvertTo-Json -Depth 10 -Compress -InputObject @(
@{ kind = 'mcp'; namespace = 'learn'; required = $true
mcp = @{ transport = 'streamableHttp'; url = 'https://learn.microsoft.com/api/mcp' } }
) | Set-Content -Path endpoints.json
# Register the MCP server as learn with that backend, then remove the file
$MCP_ENDPOINT = az aigateway mcp create -g $RG --gateway-name $GATEWAY -n learn `
--display-name "Microsoft Learn" `
--description "Search and fetch official Microsoft documentation and code samples." `
--endpoints "@endpoints.json" `
--query "properties.gatewayEndpoints[0].url" -o tsv
if ($?) { Write-Host "🔌 MCP server learn is ready: $MCP_ENDPOINT" }
Remove-Item endpoints.jsonIf learn already exists, for example from lab 04, mcp create fails with the error
This MCP registration already exists; use mcp update. In that case, skip this step and print the existing endpoint
with az aigateway mcp show -g "$RG" --gateway-name "$GATEWAY" -n learn --query "properties.gatewayEndpoints[0].url" -o tsv.
The command prints 🔌 MCP server learn is ready: and the endpoint, ending in /default/toolservers/learn/mcp.
Check the Learn server
azd up already deployed it: infra/main.bicep calls lab 04's
tool-server.bicep, which references your gateway and declares
one toolServers resource, learn. Print its endpoint from the lab folder (aigateway/labs/24-github-copilot-byok):
# Print the endpoint of the learn MCP server that azd up deployed
echo "🔌 Endpoint of the learn MCP server:"
azd env get-value AI_GATEWAY_MCP_URL# Print the endpoint of the learn MCP server that azd up deployed
Write-Host "🔌 Endpoint of the learn MCP server:"
azd env get-value AI_GATEWAY_MCP_URLazd provision replaces the whole MCP server, including backends and tool rules that you added in the portal.
The commands print 🔌 Endpoint of the learn MCP server: and the endpoint, ending in
/default/toolservers/learn/mcp.
Check the Learn server
terraform apply already deployed it: terraform/tool-server.tf declares one toolServers resource, learn, on
your gateway. Print its endpoint from the lab folder (aigateway/labs/24-github-copilot-byok); -chdir=terraform
reads the outputs of the lab's Terraform folder:
# Print the endpoint of the learn MCP server that terraform apply deployed
echo "🔌 Endpoint of the learn MCP server:"
terraform -chdir=terraform output -raw ai_gateway_mcp_url && echo# Print the endpoint of the learn MCP server that terraform apply deployed
Write-Host "🔌 Endpoint of the learn MCP server:"
terraform -chdir=terraform output -raw ai_gateway_mcp_url
if ($?) { Write-Host "" }terraform apply replaces the whole MCP server, including backends and tool rules that you added in the portal.
The commands print 🔌 Endpoint of the learn MCP server: and the endpoint, ending in
/default/toolservers/learn/mcp.
Test the MCP endpoint
Save the endpoint, then list its tools the way Copilot does: a JSON-RPC tools/list request with the key as a
bearer token.
# Save the endpoint of the learn MCP server on your gateway
export AI_GATEWAY_MCP_URL="${AI_GATEWAY_URL%/}/default/toolservers/learn/mcp"
echo "🔌 MCP endpoint: $AI_GATEWAY_MCP_URL"
# List the server's tools the way Copilot does: a JSON-RPC tools/list request, with the key as a bearer token
echo "🔧 Tools on the learn MCP server:"
curl -sS "$AI_GATEWAY_MCP_URL" \
-H "Authorization: Bearer $AI_GATEWAY_API_KEY" -H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq -r '.result.tools[].name'# Save the endpoint of the learn MCP server on your gateway
$env:AI_GATEWAY_MCP_URL = "$($env:AI_GATEWAY_URL.TrimEnd('/'))/default/toolservers/learn/mcp"
Write-Host "🔌 MCP endpoint: $env:AI_GATEWAY_MCP_URL"
# List the server's tools the way Copilot does: a JSON-RPC tools/list request, with the key as a bearer token
Write-Host "🔧 Tools on the learn MCP server:"
$reply = Invoke-RestMethod -Method Post -Uri $env:AI_GATEWAY_MCP_URL `
-Headers @{ Authorization = "Bearer $env:AI_GATEWAY_API_KEY"; Accept = "application/json, text/event-stream" } `
-ContentType "application/json" -Body '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
$reply.result.tools.nameExpected output:
🔌 MCP endpoint: https://<gateway-host>/default/toolservers/learn/mcp
🔧 Tools on the learn MCP server:
learn_microsoft_docs_search
learn_microsoft_code_sample_search
learn_microsoft_docs_fetchEach name starts with the backend's namespace, learn. The Learn server can add tools over time, and Allow all
tools publishes them too.
Add the Learn tools to VS Code
VS Code reads MCP servers from .vscode/mcp.json in the workspace. An inputs entry makes VS Code ask for the key
once and keep it in its secret storage, so the file holds no secret.
Add the server to the project
Print the endpoint to paste:
# Print the endpoint of the learn MCP server, to paste into .vscode/mcp.json
echo "🔌 MCP endpoint: $AI_GATEWAY_MCP_URL"In VS Code, create .vscode/mcp.json in contoso-calc with this content, and replace the URL with yours:
{
"inputs": [
{
"type": "promptString",
"id": "aigw-key",
"description": "AI Gateway key (github-copilot)",
"password": true
}
],
"servers": {
"ai-gateway-learn": {
"type": "http",
"url": "https://<gateway-host>/default/toolservers/learn/mcp",
"headers": {
"Authorization": "Bearer ${input:aigw-key}"
}
}
}
}Start the server
Select Start above
ai-gateway-learninmcp.json.Paste your
github-copilotkey into the AI Gateway key (github-copilot) prompt, and press Enter.VS Code asks for the key the first time the server starts, masks it, and keeps it in its secret storage. The line above the server changes to Running with 3 tools.
The server is connected through the gateway and offers three tools. mcp.json shows the key only as a reference to the input.
Check the tools
Open the Chat view, select Agent and GPT-6.1 Sol (AI Gateway), and select Configure Tools (the tools
icon in the chat input). ai-gateway-learn lists the three Learn tools. VS Code shows the name that the gateway
reports for itself, Azure API Management, next to the server name.
Run a task with the tools
Send this prompt:
Use the Microsoft Learn tools to look up the Azure Functions Python v2 programming model, then add function_app.py that exposes add() from calc.py as an HTTP-triggered function. Cite the Learn page you used.VS Code asks before each tool call and shows the tool's input. Select Allow in this Session to trust the Learn tools for the rest of this chat.
Copilot searches Learn, fetches the page it needs, writes function_app.py with the v2 decorators, and cites the
page. Review the diff and select Keep.
function_app.py exposes add as an HTTP function, and the chat answer links to a Microsoft Learn page.
Add the Learn tools to the Copilot CLI
The Copilot CLI keeps MCP servers in ~/.copilot/mcp-config.json, and the GitHub Copilot app reads the same file.
Header values can refer to environment variables, so the file doesn't need to hold the key.
Add the server
Keep the single quotes around the header. They stop the shell from expanding ${AI_GATEWAY_API_KEY}, so the file
stores the reference, and the CLI reads the key from its environment each time it connects.
# Add the gateway's learn MCP server to the Copilot CLI, with a header that reads the key from the environment
copilot mcp add --transport http --header 'Authorization: Bearer ${AI_GATEWAY_API_KEY}' ai-gateway-learn \
"$AI_GATEWAY_MCP_URL" &&
echo "🔌 MCP server ai-gateway-learn is ready in the Copilot CLI"
# List the MCP servers that the Copilot CLI uses
echo "🔌 MCP servers in the Copilot CLI:"
copilot mcp list# Add the gateway's learn MCP server to the Copilot CLI, with a header that reads the key from the environment
copilot mcp add --transport http --header 'Authorization: Bearer ${AI_GATEWAY_API_KEY}' ai-gateway-learn `
$env:AI_GATEWAY_MCP_URL
if ($?) { Write-Host "🔌 MCP server ai-gateway-learn is ready in the Copilot CLI" }
# List the MCP servers that the Copilot CLI uses
Write-Host "🔌 MCP servers in the Copilot CLI:"
copilot mcp listExpected output (your built-in servers can differ):
Added server "ai-gateway-learn"
ai-gateway-learn
Type: http
URL: https://<gateway-host>/default/toolservers/learn/mcp
Headers:
Authorization: ***
Tools: * (all)
Source: User
🔌 MCP server ai-gateway-learn is ready in the Copilot CLI
🔌 MCP servers in the Copilot CLI:
User servers:
ai-gateway-learn (http)
Builtin servers:
computer-use (local)
github-mcp-server (http)The file now holds the reference, not the key:
{
"mcpServers": {
"ai-gateway-learn": {
"tools": ["*"],
"type": "http",
"url": "https://<gateway-host>/default/toolservers/learn/mcp",
"headers": {
"Authorization": "Bearer ${AI_GATEWAY_API_KEY}"
}
}
}
}Check the tools in a session
The copilot session needs the BYOK variables from Connect the Copilot CLI and
AI_GATEWAY_API_KEY. If you did the VS Code section, remove its result first, so the CLI starts from the same
files:
# Move into the practice project, and remove the files that the VS Code section added, if any
cd ~/contoso-calc && rm -f function_app.py host.json requirements.txt &&
echo "📂 Practice project is ready: ~/contoso-calc"
# Start an interactive Copilot CLI session, on the gateway's model and with the gateway's Learn tools
echo "🚀 Starting the Copilot CLI with the Learn tools (type /exit to leave)"
copilotThe CLI reports MCP Servers reloaded: 1 server connected. Run /mcp show ai-gateway-learn to list the tools,
then press Esc twice to close the list.
Run a task with the tools
Send the same prompt as in VS Code:
Use the Microsoft Learn tools to look up the Azure Functions Python v2 programming model, then add function_app.py that exposes add() from calc.py as an HTTP-triggered function. Cite the Learn page you used.The CLI asks before it uses each tool. Select Yes, and don't ask again for the Learn tools that you trust. The tool lines show (MCP: ai-gateway-learn).
Copilot writes function_app.py, and may add requirements.txt and host.json, then summarizes the change and
cites the Learn page.
Type /exit to leave the session.
Use the tools in one-shot mode
copilot -p can't ask for approval, so allow the server's tools up front with --allow-tool:
# Run one prompt that needs the Learn tools, and allow the server's tools up front, because -p can't ask
echo "🤖 Copilot CLI answer, with the Learn tools:"
copilot -p "Search Microsoft Learn: how do I run a Python function app locally with Azure Functions Core Tools? Answer in two sentences with a link." --allow-tool='ai-gateway-learn'Expected output (shortened, your text differs):
🤖 Copilot CLI answer, with the Learn tools:
● learn_microsoft_docs_search (MCP: ai-gateway-learn) · run Python Azure Functions app locally Core…
└ Output too large to read at once (52.0 KB). Saved to: /var/folders/…
Install Azure Functions Core Tools v4 and a supported Python version, activate your project's virtual environment,
and install dependencies with `pip install -r requirements.txt`. From the project root, run `func start`, then open
the HTTP function URL printed in the terminal; see [Microsoft Learn](https://learn.microsoft.com/azure/azure-functions/functions-run-local#start-the-functions-runtime).
Changes +0 -0
Duration 18s
Tokens ↑ 50.8k (30.4k cached, 20.4k written) • ↓ 204
Resume copilot --resume=<session-id>Compare the Tokens line with the 14,400 tokens of the plain question in Ask a quick question: the search result made up most of the difference.
/mcp show lists three tools, the tool lines show (MCP: ai-gateway-learn), and the answer cites a Learn page.
COPILOT_OFFLINE=true turns off the built-in GitHub MCP server, but not the servers you add: the Learn tools keep
working.
Add the Learn tools to the Copilot SDK
The samples already handle MCP. When AI_GATEWAY_MCP_URL is set, they add the server to the session as
ai-gateway-learn, with the key as a bearer token in the Authorization header and tools: ["*"] to offer every tool:
const mcpServers: Record<string, MCPServerConfig> = mcpUrl
? { "ai-gateway-learn": { type: "http", url: mcpUrl, headers: { Authorization: `Bearer ${apiKey}` }, tools: ["*"] } }
: {};The session gets them with mcpServers in TypeScript and mcp_servers= in Python. approveAll lets the agent call
the tools without asking.
Run a sample with the tools
Run the commands from labs/24-github-copilot-byok/infra, in the shell where you set AI_GATEWAY_MCP_URL.
# Run copilot-sdk.ts with a prompt that asks the agent to use the gateway's Learn tools
echo "🤖 Agent reply, with the Learn tools:"
npm start -- "Use the Microsoft Learn tools to answer: how do I run a Python function app locally with Azure Functions Core Tools? Answer in two sentences and cite the Learn page."# Run copilot_sdk.py with a prompt that asks the agent to use the gateway's Learn tools
echo "🤖 Agent reply, with the Learn tools:"
python copilot_sdk.py "Use the Microsoft Learn tools to answer: how do I run a Python function app locally with Azure Functions Core Tools? Answer in two sentences and cite the Learn page."Expected output (your text differs):
🤖 Agent reply, with the Learn tools:
Install Azure Functions Core Tools, activate your Python virtual environment, install your app's dependencies, and
run `func start` from the project root, as described in [Microsoft Learn](https://learn.microsoft.com/en-us/azure/azure-functions/functions-run-local?pivots=programming-language-python#start-the-functions-runtime).
For an HTTP-triggered function, open the localhost URL printed in the terminal (usually on port 7071) or call it
with an HTTP client.The answer cites a learn.microsoft.com page that the agent found through the gateway.
Add the Learn tools to the GitHub Copilot app
The GitHub Copilot app loads the MCP servers that you configured for the Copilot CLI. If you did the CLI section,
ai-gateway-learn is already there.
Give the app the key
The server's header reads ${AI_GATEWAY_API_KEY} from the app's environment, not from your terminal. Make the
variable available to the app, then quit and reopen it. For example, export it in your shell profile on macOS or
Linux, or set it as a user environment variable on Windows. Prefer a command that reads the key from a secret store
over the key itself in plain text.
If you'd rather not set a variable, replace ${AI_GATEWAY_API_KEY} in ~/.copilot/mcp-config.json with the key. The
file then holds the key in plain text, so keep it private.
Check the server
Select Customize in the app sidebar, then MCPInstalled. The list includes ai-gateway-learn. If you
skipped the CLI section, run its copilot mcp add command, or add a custom server here with the endpoint URL and an
Authorization header set to Bearer <key>.
Run a task with the tools
Sessions load MCP servers when they start, so start a new session on the contoso-calc folder. Select
gpt-6.1-sol from the AI Gateway provider, and send:
Use the Microsoft Learn tools to find how to run calc.py as an Azure Functions app locally, and summarize the steps with a link.The session's agent sees each tool with the server name in front, such as
ai-gateway-learn-learn_microsoft_docs_search.
The reply cites a Microsoft Learn page, and the session shows calls to ai-gateway-learn tools.
The GitHub Copilot app is in public preview, and its screens change often. These steps follow Customizing the GitHub Copilot app.
Verify
Every surface you connected sends its requests with the github-copilot key. Use it to see the traffic and to switch
Copilot off.
See Copilot's usage by key
If you set up Monitoring in Monitor usage, cost, and traces, open MonitoringModels in the AI Gateway portal. gpt-6.1-sol lists the calls and the input and output tokens from your Copilot
sessions, and Model usage by caller identity shows them under the github-copilot key. The input tokens are far
higher than the output tokens: that's the context that the agent sends with every request.
Cut Copilot off by suspending the key
Suspend the key, then run the CLI again. The settings are unchanged, but the gateway now rejects the key.
# Suspend the github-copilot key: calls with it get 401 until you set it back to active
STATE="$(az aigateway api-key update -g "$RG" --gateway-name "$GATEWAY" -n "$KEY_NAME" --state suspended \
--query properties.state -o tsv)" &&
echo "🔑 API key github-copilot is $STATE"
# Give the gateway time to apply the change
echo "⏳ Waiting 30 seconds for the key change to apply"
sleep 30
# Ask the Copilot CLI again, with the same settings: the gateway now rejects the key
echo "🚦 Expect HTTP 401 from the gateway, after two retries:"
cd ~/contoso-calc && copilot -p "Say hi"# Suspend the github-copilot key: calls with it get 401 until you set it back to active
$STATE = az aigateway api-key update -g $RG --gateway-name $GATEWAY -n $KEY_NAME --state suspended `
--query properties.state -o tsv
if ($?) { Write-Host "🔑 API key github-copilot is $STATE" }
# Give the gateway time to apply the change
Write-Host "⏳ Waiting 30 seconds for the key change to apply"
Start-Sleep 30
# Ask the Copilot CLI again, with the same settings: the gateway now rejects the key
Write-Host "🚦 Expect HTTP 401 from the gateway, after two retries:"
Set-Location ~/contoso-calc; copilot -p "Say hi"Expected output, after the CLI retries twice:
🔑 API key github-copilot is suspended
⏳ Waiting 30 seconds for the key change to apply
🚦 Expect HTTP 401 from the gateway, after two retries:
Request failed due to a transient API error. Retrying...
Request failed due to a transient API error. Retrying...
Authentication failed with provider at https://<gateway-host>/default/models/openai/v1 (HTTP 401).
Check your COPILOT_PROVIDER_API_KEY, COPILOT_PROVIDER_API_KEY_COMMAND, or COPILOT_PROVIDER_BEARER_TOKEN.VS Code, the SDK, and the app get the same 401. One key change cuts off every Copilot surface that uses the key, on
every machine, without touching their settings.
The key guards the tools too. While it's suspended, the MCP endpoint also answers 401 Unauthorized: run the request
from Test the MCP endpoint without | jq … to see it, and the Learn tools fail to connect
in every surface.
Turn Copilot back on
# Turn the github-copilot key back on
STATE="$(az aigateway api-key update -g "$RG" --gateway-name "$GATEWAY" -n "$KEY_NAME" --state active \
--query properties.state -o tsv)" &&
echo "🔑 API key github-copilot is $STATE"
# Give the gateway time to apply the change
echo "⏳ Waiting 30 seconds for the key change to apply"
sleep 30
# Ask the Copilot CLI again: it answers through the gateway
echo "🤖 Copilot CLI answer:"
copilot -p "Say hi in three words"# Turn the github-copilot key back on
$STATE = az aigateway api-key update -g $RG --gateway-name $GATEWAY -n $KEY_NAME --state active `
--query properties.state -o tsv
if ($?) { Write-Host "🔑 API key github-copilot is $STATE" }
# Give the gateway time to apply the change
Write-Host "⏳ Waiting 30 seconds for the key change to apply"
Start-Sleep 30
# Ask the Copilot CLI again: it answers through the gateway
Write-Host "🤖 Copilot CLI answer:"
copilot -p "Say hi in three words"The CLI failed with HTTP 401 while the key was suspended, and answered again after
🔑 API key github-copilot is active.
Go further
- Choose which Learn tools Copilot sees. Publish only
learn_microsoft_docs_search, block a tool, or cap tool calls per caller in Control which tools agents can call. Copilot picks up the change the next time it lists tools, with no change on the clients. - Give Copilot more tools from one endpoint. Add more backends to the server, such as an OpenAPI spec or a Connector Namespace server imported from Azure, as in Federate MCP tools behind one endpoint. Each backend's namespace keeps the tool names apart.
- Sign in with Microsoft Entra ID instead of a key. If the gateway accepts Entra tokens, as in
Authorize callers with Microsoft Entra ID, set
COPILOT_PROVIDER_BEARER_TOKENfor the CLI, or pass a bearer token in the SDK'sprovidersettings. Tokens expire, so refresh them for long sessions. - Fetch the key when it's needed.
COPILOT_PROVIDER_API_KEY_COMMANDruns a command for each request and uses its output as the key, for exampleaz keyvault secret show --vault-name <vault> -n github-copilot --query value -o tsv. The key then never sits in your shell profile, and a rotated key takes effect right away. - Give each developer or tool its own key. Keys are cheap, and per-key usage in Monitoring shows who uses how much. Rotate or revoke them with Manage runtime API keys.
- Route Copilot across models. Point the
gpt-6.1-solalias at several backend models, as in Route by priority and weight. VS Code chains Responses API turns withprevious_response_idby default; if the backends don't share state, set"statefulResponses": falseon the model inchatLanguageModels.json. - Offer more models. Publish more aliases and add each one to
modelsin VS Code, or to the provider in the app. For the CLI, setCOPILOT_MODELto a different alias. If an alias doesn't have a well-known model name, setCOPILOT_PROVIDER_MODEL_IDto the model it serves, so the CLI picks the right prompts and token sizes.
Clean up
Remove the gateway from each Copilot surface you configured, and delete the practice project:
- VS Code: delete the AI Gateway group from
chatLanguageModels.json, or remove it in the Language Models editor. Delete.vscode/mcp.jsonfromcontoso-calc. - Copilot CLI: run
copilot mcp remove ai-gateway-learn. Then close the terminal, or rununset COPILOT_PROVIDER_BASE_URL COPILOT_PROVIDER_WIRE_API COPILOT_PROVIDER_API_KEY COPILOT_MODEL(Bash) orRemove-Item Env:COPILOT_PROVIDER_*, Env:COPILOT_MODEL(PowerShell). - GitHub Copilot app: remove the AI Gateway provider in Model providers.
copilot mcp removealso removesai-gateway-learnfrom the app. RemoveAI_GATEWAY_API_KEYfrom your profile or environment if you set it for the app. - Practice project: run
rm -rf ~/contoso-calc(Bash) orRemove-Item -Recurse -Force ~/contoso-calc(PowerShell).
Then delete what you created on the gateway. Pick a track.
Delete the key, the model, and the Learn server
- Delete
github-copilotin AccessAPI keys. - If you don't need
gpt-6.1-solany more, delete its alias and its backend model in Models, then its deployment in Foundry. If you imported the model in the portal, also delete its<foundry-account-name>/gpt-6.1-solalias. Keep the gateway and the provider: the other labs reuse them. - Keep the
learnMCP server if you continue with Control which tools agents can call, which builds on it. Otherwise, delete it in MCP servers.
Delete the key, the model, and the Learn server
Delete the key:
# Delete the github-copilot key: every Copilot surface that still uses it stops working
az aigateway api-key delete -g "$RG" --gateway-name "$GATEWAY" -n "$KEY_NAME" --yes &&
echo "🚮 API key github-copilot is deleted"# Delete the github-copilot key: every Copilot surface that still uses it stops working
az aigateway api-key delete -g $RG --gateway-name $GATEWAY -n $KEY_NAME --yes
if ($?) { Write-Host "🚮 API key github-copilot is deleted" }If you don't need gpt-6.1-sol any more, also delete the alias, the backend model, and the Foundry deployment:
# Delete the gpt-6.1-sol alias first, so that nothing points at the model
az aigateway model-alias delete -g "$RG" --gateway-name "$GATEWAY" -n "$MODEL" --yes &&
echo "🚮 Alias $MODEL is deleted"
# Delete the backend model from the provider
az aigateway model delete -g "$RG" --gateway-name "$GATEWAY" --provider-name "$PROVIDER" -n "$MODEL" --yes &&
echo "🚮 Model $MODEL is deleted from $PROVIDER"
# Delete the gpt-6.1-sol deployment from the Foundry account
az cognitiveservices account deployment delete -g "$FOUNDRY_RG" -n "$FOUNDRY_ACCOUNT" --deployment-name "$MODEL" &&
echo "🚮 Model deployment $MODEL is deleted from $FOUNDRY_ACCOUNT"# Delete the gpt-6.1-sol alias first, so that nothing points at the model
az aigateway model-alias delete -g $RG --gateway-name $GATEWAY -n $MODEL --yes
if ($?) { Write-Host "🚮 Alias $MODEL is deleted" }
# Delete the backend model from the provider
az aigateway model delete -g $RG --gateway-name $GATEWAY --provider-name $PROVIDER -n $MODEL --yes
if ($?) { Write-Host "🚮 Model $MODEL is deleted from $PROVIDER" }
# Delete the gpt-6.1-sol deployment from the Foundry account
az cognitiveservices account deployment delete -g $FOUNDRY_RG -n $FOUNDRY_ACCOUNT --deployment-name $MODEL
if ($?) { Write-Host "🚮 Model deployment $MODEL is deleted from $FOUNDRY_ACCOUNT" }Keep the gateway and the provider: the other labs reuse them. Keep the learn MCP server if you continue with
Control which tools agents can call, which builds on it. Otherwise, delete it:
# Delete the learn MCP server from the gateway
az aigateway mcp delete -g "$RG" --gateway-name "$GATEWAY" -n learn --yes &&
echo "🚮 MCP server learn is deleted"# Delete the learn MCP server from the gateway
az aigateway mcp delete -g $RG --gateway-name $GATEWAY -n learn --yes
if ($?) { Write-Host "🚮 MCP server learn is deleted" }Delete everything azd created
In the aigateway/labs/24-github-copilot-byok folder, delete the resource group with the gateway, the gpt-6.1-sol
alias, the github-copilot key, the learn MCP server, and the Foundry account with its two deployments.
--purge also purges the soft-deleted Foundry account. It takes about three
minutes.
# Delete everything that azd up created, and purge the Foundry account
azd down --purge --force &&
echo "🚮 Everything that azd up created is deleted"Delete everything Terraform created
Move back into the lab's terraform folder, and delete the resource group with the gateway, the
gpt-6.1-sol alias, the github-copilot key, the learn MCP server, and the Foundry account with its two
deployments. The azurerm provider also purges the soft-deleted Foundry
account. It takes one to two minutes.
# Delete everything that terraform apply created, and purge the soft-deleted Foundry account
cd ~/aigateway/labs/24-github-copilot-byok/terraform &&
terraform destroy -auto-approve &&
echo "🚮 Everything that terraform apply created is deleted"azd down and terraform destroy don't touch the gateway, provider, and key from lab 02, because the Bicep + azd
and Terraform tracks created their own gateways.
Next steps
- Manage runtime API keys: rotate, suspend, and revoke the keys that tools use.
- Throttle tokens per caller with token limits: tune the limit for agent traffic.
- Monitor usage, cost, and traces: see Copilot's usage by key next to your apps.
- Federate MCP tools behind one endpoint and Control which tools agents can call: grow and govern the tools that Copilot calls.
- Build on your gateway with coding agents: let a coding agent write the client code for your gateway.
- Use BYOK models in the GitHub Copilot CLI, the Copilot SDK, and VS Code.
- Add MCP servers to the Copilot CLI and VS Code.