Allow and block lists decide which tools an agent can call, but not what it can do with them. Your rules are often about the call itself: no customer email addresses in a search, no refund above a limit, no secret in a result that goes back to the model. In this lab you write those rules in a small Azure function, and an agent hooks policy on your MCP server asks it for a verdict before each tool runs and again before each result reaches the agent.
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, the learn
MCP server, the decision service, the agent hooks policy, and a key, so you can skip this section. You need only
the one-time setup above and permission to register applications in Microsoft Entra ID.
- Complete Federate MCP tools behind one endpoint. This lab governs the
learnMCP server from that lab. Any MCP server in your gateway works. - Permission to manage policies on the gateway and to create resources, for example Contributor on a subscription or resource group.
- Permission to register applications in Microsoft Entra ID. The decision service trusts only tokens issued for its own app registration.
- A region with the Azure Functions Flex Consumption plan. The lab deploys the function app in the gateway's region;
az functionapp list-flexconsumption-locations --query "[].name" -o tsvlists the regions that have it. - Your gateway's system-assigned managed identity, which every gateway has. The hook uses it to authenticate.
- Run the scripts from the lab's folder,
~/aigateway/labs/30-agent-hooks.
Agent hooks are an emerging capability of Azure AI Gateway. Labels and behavior can change; see the release note.
Set these variables once. The steps and the Verify section reuse them.
# Set your resource group and gateway, and the MCP server that you govern
export RG="<resource-group>"
export GATEWAY="<gateway>"
export MCP_SERVER="learn" # the MCP server you govern in this lab
echo "๐ Gateway $GATEWAY in $RG, MCP server $MCP_SERVER"
# Read the gateway's resource ID and its 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)"
echo "๐ Gateway ID: $GATEWAY_ID"
echo "๐ Runtime URL: $AI_GATEWAY_URL"
# Paste a runtime key from Access โบ API keys without showing it: the test script calls tools with it
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)"# Set your resource group and gateway, and the MCP server that you govern
$RG = "<resource-group>"
$GATEWAY = "<gateway>"
$MCP_SERVER = "learn" # the MCP server you govern in this lab
Write-Host "๐ Gateway $GATEWAY in $RG, MCP server $MCP_SERVER"
# Read the gateway's resource ID and its 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)"
Write-Host "๐ Gateway ID: $GATEWAY_ID"
Write-Host "๐ Runtime URL: $env:AI_GATEWAY_URL"
# Paste a runtime key from Access โบ API keys without showing it: the test script calls tools with it
$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)"How it works
An agent hooks policy on an MCP server sends each tools/call to a decision service that you run, and enforces
its verdict. The gateway is the host of the Agent Hooks control contract:
it posts an AgentContext JSON document to your HTTPS endpoint, and the service answers HTTP 200 with
{"decision": "allow"} or {"decision": "deny", "reason": "โฆ"}. Discovery and session traffic, such as
initialize and tools/list, isn't sent.
The gateway authenticates to the service with its managed identity (a Microsoft Entra token for the audience that
you set), with an API key header, or anonymously, and adds the literal headers that you configure. The mode
decides what happens when the service fails or doesn't answer in time: failClosed, the default, blocks the call;
failOpen lets it through. Settings at the policy level apply to both hooks, and each hook can override them.
| Intervention point | Policy key | interception_point | The service gets | Effect of a deny |
|---|---|---|---|---|
| Before tool call | preToolCall | pre_tool_call | The tool name and arguments | The tool never runs |
| After tool call | postToolCall | post_tool_call | The tool name, arguments, and result | The result is withheld, but the tool already ran |
Verdicts can only allow or deny: transforms, warnings, and approvals aren't supported.
Review the decision service
The decision service is one Python function, tool-hook, in infra/hook/function_app.py.
It answers both intervention points:
| Point | Rule | Reason in the verdict |
|---|---|---|
| Before tool call | The tool name matches a pattern in the BLOCKED_TOOLS app setting, *code_sample* by default | blocked_tool:<pattern> |
| Before tool call | The arguments contain an email address | personal_data:email_address |
| Before tool call | The arguments contain a secret, such as a storage account key, a SAS signature, a private key, or a JWT | secret_in_arguments:<kind> |
| After tool call | The result contains a secret | secret_in_result:<kind> |
| Either | Nothing matches | policy_satisfied, with allow |
"""Agent hooks decision service for Azure AI Gateway (lab 30).
The gateway posts an Agent Hooks AgentContext to /api/tool-hook before a tool runs (interception_point
pre_tool_call) and after the tool returns (post_tool_call). The function answers HTTP 200 with
{"decision": "allow" | "deny", "reason": "..."}.
App Service Authentication (Easy Auth) in front of the app rejects every request that doesn't carry a Microsoft Entra
token for this app from the gateway's managed identity, so the function itself allows anonymous calls.
Rules:
- BLOCKED_TOOLS (app setting): comma-separated tool name patterns that never run, for example *code_sample*
- Tool arguments that contain an email address or a secret-looking string are denied before the call.
- Tool results that contain a secret-looking string are withheld after the call.
The decision log has the tool name, the decision, the reason, and the gateway's request ID. It never has tool
arguments, results, or tokens.
"""
import fnmatch
import json
import logging
import os
import re
import azure.functions as func
app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)
BLOCKED_TOOLS = [p.strip().lower() for p in os.environ.get("BLOCKED_TOOLS", "*code_sample*").split(",") if p.strip()]
EMAIL = re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")
SECRETS = {
"storage_account_key": re.compile(r"AccountKey=[A-Za-z0-9+/]{40,}={0,2}"),
"sas_signature": re.compile(r"[?&]sig=[A-Za-z0-9%+/]{30,}"),
"private_key": re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----"),
"openai_style_key": re.compile(r"\bsk-[A-Za-z0-9_-]{20,}"),
"jwt": re.compile(r"\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}"),
}
def find_secret(text: str) -> str | None:
"""Return the name of the first secret pattern that matches the text, or None."""
return next((name for name, pattern in SECRETS.items() if pattern.search(text)), None)
def before_call(context: dict) -> tuple[str, str]:
"""Decide whether the tool may run, from its name and arguments."""
tool_call = context["tool_call"]
name = str(tool_call.get("name", "")).lower()
for pattern in BLOCKED_TOOLS:
if fnmatch.fnmatchcase(name, pattern):
return "deny", f"blocked_tool:{pattern}"
args = json.dumps(tool_call.get("args") or {})
if EMAIL.search(args):
return "deny", "personal_data:email_address"
secret = find_secret(args)
if secret:
return "deny", f"secret_in_arguments:{secret}"
return "allow", "policy_satisfied"
def after_call(context: dict) -> tuple[str, str]:
"""Decide whether the caller may see the tool result."""
# The gateway sends the MCP tool result in target; the Agent Hooks spec also defines tool_result.
result = json.dumps([context.get("target"), context.get("tool_result")])
secret = find_secret(result)
if secret:
return "deny", f"secret_in_result:{secret}"
return "allow", "policy_satisfied"
@app.route(route="tool-hook", methods=["POST"])
def tool_hook(req: func.HttpRequest) -> func.HttpResponse:
try:
context = req.get_json()
except ValueError:
context = None
if not isinstance(context, dict) or not isinstance(context.get("tool_call"), dict):
context = {}
decision, reason = "deny", "invalid_context"
elif context.get("interception_point") == "pre_tool_call":
decision, reason = before_call(context)
elif context.get("interception_point") == "post_tool_call":
decision, reason = after_call(context)
else:
decision, reason = "deny", "unsupported_interception_point"
logging.info(
"agent-hook point=%s tool=%s decision=%s reason=%s request_id=%s caller=%s policy=%s",
context.get("interception_point"), (context.get("tool_call") or {}).get("name"), decision, reason,
context.get("request_id"), req.headers.get("x-ms-client-principal-id", "none"),
req.headers.get("x-hook-policy", "none"),
)
return func.HttpResponse(json.dumps({"decision": decision, "reason": reason}),
status_code=200, mimetype="application/json")On GitHub, open infra/hook/function_app.py.
Before a call, the gateway posts the tool call. This is a real request for the docs search tool, with the IDs shortened:
{
"spec": "agent-hooks/0.1",
"interception_point": "pre_tool_call",
"timestamp": "2026-11-16T02:47:51.711Z",
"sequence": 0,
"agent": { "framework": "microsoft.azure.aigateway" },
"tool_call": {
"id": "2",
"name": "learn_microsoft_docs_search",
"args": { "query": "What is Azure Functions?" }
},
"target": { "query": "What is Azure Functions?" },
"request_id": "7c73b7ce-โฆ",
"trace": { "trace_id": "524b7585โฆ", "span_id": "ea417be7โฆ" }
}After the call, the request has "interception_point": "post_tool_call", the same tool_call and request_id,
and the MCP tool result in target:
"target": {
"isError": false,
"content": [ { "type": "text", "text": "{\"results\":[{\"title\":\"Azure Functions overview\", โฆ}]}" } ]
}The policy reference also shows a tool_result object,
which the gateway doesn't send yet, so the function reads both. It treats any request it can't parse as a deny.
The function allows anonymous calls because App Service Authentication stands in front of it: the platform
rejects every request with HTTP 401 unless it carries a Microsoft Entra token issued for the hook's app
registration to the gateway's managed identity. Each request also carries the policy's custom headers, here
x-hook-policy: lab30, which the decision log records with the caller's object ID.
Keep the decision service fast and available. The gateway waits about 30 seconds for a verdict, and every tool call waits for it. Don't log tool arguments, results, or tokens: this function logs only the tool name, the decision, the reason, and the request ID.
Deploy the decision service
The AI Gateway portal doesn't create function apps or app registrations, so on the Portal track, follow the Azure CLI steps here, then attach the hook in the portal.
Register an app for the hook
The gateway asks Microsoft Entra ID for a token whose audience is the hook's application ID URI. Register an app
with that URI and create its service principal, so that the gateway's managed identity can get tokens for it. The
function app name is func- plus the first part of your gateway's host name, which is unique.
# Name the decision service's resource group and function app, in the gateway's region
export HOOK_RG="rg-aigw-lab30-hook"
export HOOK_APP="func-$(echo "$AI_GATEWAY_URL" | cut -d/ -f3 | cut -d. -f1)"
export LOCATION="$(az aigateway show -g "$RG" -n "$GATEWAY" --query location -o tsv)"
echo "๐ Function app $HOOK_APP in $HOOK_RG, in $LOCATION"
# Register an app for the decision service: the gateway asks Microsoft Entra ID for tokens issued to it
export HOOK_CLIENT_ID="$(az ad app create --display-name "$HOOK_APP" --sign-in-audience AzureADMyOrg --query appId -o tsv)"
echo "๐ App registration $HOOK_APP: $HOOK_CLIENT_ID"
# Give it an application ID URI: the token audience that the policy asks for
export HOOK_AUDIENCE="api://$HOOK_CLIENT_ID"
az ad app update --id "$HOOK_CLIENT_ID" --identifier-uris "$HOOK_AUDIENCE" &&
echo "๐ค Token audience: $HOOK_AUDIENCE"
# Create its service principal, so that managed identities in your tenant can get tokens for it
az ad sp create --id "$HOOK_CLIENT_ID" -o none &&
echo "๐ค Service principal for $HOOK_APP is ready"# Name the decision service's resource group and function app, in the gateway's region
$HOOK_RG = "rg-aigw-lab30-hook"
$HOOK_APP = "func-" + ([uri]$env:AI_GATEWAY_URL).Host.Split('.')[0]
$LOCATION = az aigateway show -g $RG -n $GATEWAY --query location -o tsv
Write-Host "๐ Function app $HOOK_APP in $HOOK_RG, in $LOCATION"
# Register an app for the decision service: the gateway asks Microsoft Entra ID for tokens issued to it
$HOOK_CLIENT_ID = az ad app create --display-name $HOOK_APP --sign-in-audience AzureADMyOrg --query appId -o tsv
Write-Host "๐ App registration ${HOOK_APP}: $HOOK_CLIENT_ID"
# Give it an application ID URI: the token audience that the policy asks for
$HOOK_AUDIENCE = "api://$HOOK_CLIENT_ID"
az ad app update --id $HOOK_CLIENT_ID --identifier-uris $HOOK_AUDIENCE
if ($?) { Write-Host "๐ค Token audience: $HOOK_AUDIENCE" }
# Create its service principal, so that managed identities in your tenant can get tokens for it
az ad sp create --id $HOOK_CLIENT_ID -o none
if ($?) { Write-Host "๐ค Service principal for $HOOK_APP is ready" }Deploy the function app
infra/hook.bicep creates a Python function app on the Flex Consumption plan, with App Service
Authentication that lets in only the gateway's identity, a private storage account that the app reaches with its
managed identity, and Application Insights for the decision log. It takes three to five minutes.
# Read the object ID of the gateway's managed identity: the only caller that the decision service lets in
export GATEWAY_PRINCIPAL_ID="$(az aigateway show -g "$RG" -n "$GATEWAY" --query identity.principalId -o tsv)"
echo "๐ค Gateway identity: $GATEWAY_PRINCIPAL_ID"
# Create a resource group for the decision service
az group create -n "$HOOK_RG" -l "$LOCATION" -o none &&
echo "๐ฆ Resource group $HOOK_RG is ready in $LOCATION"
# Deploy the function app, its network, storage, and logs, without code yet
az deployment group create -g "$HOOK_RG" -n lab30-hook -f infra/hook.bicep -o none \
-p appName="$HOOK_APP" hookClientId="$HOOK_CLIENT_ID" hookAudience="$HOOK_AUDIENCE" \
gatewayPrincipalId="$GATEWAY_PRINCIPAL_ID" &&
echo "๐ Function app $HOOK_APP is deployed"
# Read the hook's URL and the Log Analytics workspace ID from the deployment's outputs
export HOOK_URL="$(az deployment group show -g "$HOOK_RG" -n lab30-hook --query properties.outputs.hookUrl.value -o tsv)"
export HOOK_LOG_WORKSPACE_ID="$(az deployment group show -g "$HOOK_RG" -n lab30-hook --query properties.outputs.logWorkspaceId.value -o tsv)"
echo "๐ Hook URL: $HOOK_URL"
echo "๐ Log Analytics workspace ID: $HOOK_LOG_WORKSPACE_ID"# Read the object ID of the gateway's managed identity: the only caller that the decision service lets in
$GATEWAY_PRINCIPAL_ID = az aigateway show -g $RG -n $GATEWAY --query identity.principalId -o tsv
Write-Host "๐ค Gateway identity: $GATEWAY_PRINCIPAL_ID"
# Create a resource group for the decision service
az group create -n $HOOK_RG -l $LOCATION -o none
if ($?) { Write-Host "๐ฆ Resource group $HOOK_RG is ready in $LOCATION" }
# Deploy the function app, its network, storage, and logs, without code yet
az deployment group create -g $HOOK_RG -n lab30-hook -f infra/hook.bicep -o none `
-p appName=$HOOK_APP hookClientId=$HOOK_CLIENT_ID hookAudience=$HOOK_AUDIENCE `
gatewayPrincipalId=$GATEWAY_PRINCIPAL_ID
if ($?) { Write-Host "๐ Function app $HOOK_APP is deployed" }
# Read the hook's URL and the Log Analytics workspace ID from the deployment's outputs
$HOOK_URL = az deployment group show -g $HOOK_RG -n lab30-hook --query properties.outputs.hookUrl.value -o tsv
$HOOK_LOG_WORKSPACE_ID = az deployment group show -g $HOOK_RG -n lab30-hook --query properties.outputs.logWorkspaceId.value -o tsv
Write-Host "๐ Hook URL: $HOOK_URL"
Write-Host "๐ Log Analytics workspace ID: $HOOK_LOG_WORKSPACE_ID"Deploy the code
Restart the new app once, so that it reaches its private storage, then zip the function's three files in
infra/hook and upload them. Zip only those files, so that local files such as local.settings.json stay on your
machine. Flex Consumption builds the app from requirements.txt.
# Restart the new app once: its first upload can fail until it reaches its private storage
az functionapp restart -g "$HOOK_RG" -n "$HOOK_APP" &&
echo "โณ $HOOK_APP restarted"
# Zip the function's three files from inside its folder
(cd infra/hook && zip -q ../../hook.zip function_app.py host.json requirements.txt) &&
echo "๐ hook.zip is ready"
# Upload the code and build it remotely, then delete the zip file
az functionapp deployment source config-zip -g "$HOOK_RG" -n "$HOOK_APP" --src hook.zip --build-remote true -o none &&
echo "๐ The decision service is deployed to $HOOK_APP"
rm hook.zip
# Call the hook without a token: App Service Authentication answers 401 before the function runs
echo "๐ Anonymous call to the hook: HTTP $(curl -s -o /dev/null -w '%{http_code}' -X POST "$HOOK_URL" -H 'Content-Type: application/json' -d '{}')"# Restart the new app once: its first upload can fail until it reaches its private storage
az functionapp restart -g $HOOK_RG -n $HOOK_APP
if ($?) { Write-Host "โณ $HOOK_APP restarted" }
# Zip the function's three files
Compress-Archive -Path infra/hook/function_app.py, infra/hook/host.json, infra/hook/requirements.txt -DestinationPath hook.zip -Force
if ($?) { Write-Host "๐ hook.zip is ready" }
# Upload the code and build it remotely, then delete the zip file
az functionapp deployment source config-zip -g $HOOK_RG -n $HOOK_APP --src hook.zip --build-remote true -o none
if ($?) { Write-Host "๐ The decision service is deployed to $HOOK_APP" }
Remove-Item hook.zip
# Call the hook without a token: App Service Authentication answers 401 before the function runs
$anonymous = Invoke-WebRequest -Method Post -Uri $HOOK_URL -ContentType 'application/json' -Body '{}' -SkipHttpErrorCheck
Write-Host "๐ Anonymous call to the hook: HTTP $($anonymous.StatusCode)"The upload ends with ๐ The decision service is deployed, and the anonymous call prints
๐ Anonymous call to the hook: HTTP 401. Keep the values of HOOK_URL and HOOK_AUDIENCE: the portal asks for
them.
What you need: only the one-time setup from Before you begin, and permission to register applications in
Microsoft Entra ID. This track doesn't use your gateway or learn server from lab 04: azd up creates a new gateway
with its own learn server, the decision service, and the policy, so it works on its own.
Review the templates
infra/main.bicep creates the resource group rg-<environment name>, registers the hook's app in Microsoft Entra
ID with the Microsoft Graph Bicep extension, and calls lab 01's
gateway.bicep for a gateway with no model. Then it deploys the
decision service and the governed MCP server. azd fills two parameters from environment values:
| Parameter | azd environment value | Default |
|---|---|---|
hookMode | HOOK_MODE | failClosed |
blockedTools | HOOK_BLOCKED_TOOLS | *code_sample* |
// Lab 30 with azd: "azd up" registers the decision service in Microsoft Entra ID, creates the resource group
// rg-<environment name>, a gateway with lab 01's template, the decision service (hook.bicep), then the learn MCP
// server with the agent hooks policy and the runtime API key app-first-call. azd then deploys the function code from
// infra/hook. The runtime API key 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 Flex Consumption are available. List them with az provider show --namespace Microsoft.ApiManagement and az functionapp list-flexconsumption-locations.')
@metadata({ azd: { type: 'location' } })
param location string
@description('What the gateway does when the decision service can\'t answer. azd reads it from HOOK_MODE.')
@allowed([ 'failClosed', 'failOpen' ])
param hookMode string = 'failClosed'
@description('Comma-separated tool name patterns that the decision service denies. azd reads it from HOOK_BLOCKED_TOOLS.')
param blockedTools string = '*code_sample*'
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
}
// Microsoft Graph objects don't belong to the resource group: the deployment only runs there.
module registration 'hook-registration.bicep' = {
name: 'aigw-hook-registration'
scope: rg
params: {
uniqueName: 'aigw-lab30-hook-${suffix}'
}
}
// Lab 01's template: the gateway, with no model.
module gateway '../../01-provision-gateway/infra/gateway.bicep' = {
name: 'aigw-gateway'
scope: rg
params: {
gatewayName: 'aigw-${suffix}'
location: location
tags: tags
}
}
module hook 'hook.bicep' = {
name: 'aigw-hook'
scope: rg
params: {
appName: 'func-aigw-hook-${suffix}'
location: location
hookClientId: registration.outputs.clientId
hookAudience: registration.outputs.audience
gatewayPrincipalId: gateway.outputs.principalId
blockedTools: blockedTools
tags: tags
}
}
module toolServer 'guarded-tool-server.bicep' = {
name: 'aigw-guarded-tool-server'
scope: rg
params: {
gatewayName: gateway.outputs.gatewayName
serverName: 'learn'
hookUrl: hook.outputs.hookUrl
hookAudience: registration.outputs.audience
hookMode: hookMode
apiKeyName: 'app-first-call'
}
}
output AZURE_RESOURCE_GROUP string = rg.name
output AI_GATEWAY_NAME string = gateway.outputs.gatewayName
output AI_GATEWAY_ID string = gateway.outputs.gatewayId
output AI_GATEWAY_URL string = gateway.outputs.gatewayUrl
output MCP_SERVER string = 'learn'
output MCP_ENDPOINT string = toolServer.outputs.mcpEndpoint
output HOOK_APP_NAME string = hook.outputs.appName
output HOOK_URL string = hook.outputs.hookUrl
output HOOK_CLIENT_ID string = registration.outputs.clientId
output HOOK_AUDIENCE string = registration.outputs.audience
output HOOK_LOG_WORKSPACE_ID string = hook.outputs.logWorkspaceIdinfra/hook-registration.bicep registers the app and its service principal, with an application ID URI that
the policy uses as the token audience.
// Registers the decision service in Microsoft Entra ID with the Microsoft Graph Bicep extension (bicepconfig.json):
// an application whose Application ID URI is the token audience that the gateway asks for, and its service principal,
// without which Microsoft Entra ID can't issue tokens for that audience. The registration has no secret: the gateway
// signs in with its managed identity, and App Service Authentication only validates the tokens.
// Microsoft Graph objects don't belong to a resource group: delete the application when you're done
// (az ad app delete --id <client ID>). The lab's azd template does it after "azd down".
extension microsoftGraphV1
@description('Unique name of the application in the tenant. A new name creates a new application.')
param uniqueName string
@description('Display name of the application.')
param displayName string = uniqueName
resource app 'Microsoft.Graph/applications@v1.0' = {
uniqueName: uniqueName
displayName: displayName
signInAudience: 'AzureADMyOrg'
// api://<tenant ID>/<name> passes the tenant's identifier URI policy without a verified domain.
identifierUris: [ 'api://${tenant().tenantId}/${uniqueName}' ]
}
resource principal 'Microsoft.Graph/servicePrincipals@v1.0' = {
appId: app.appId
}
output clientId string = app.appId
output audience string = app.identifierUris[0]infra/hook.bicep is the function app that the Azure CLI track deploys too: Flex Consumption, App Service
Authentication that lets in only the gateway's identity, a private storage account, and Application Insights.
// Lab 30: the agent hooks decision service. A Python function app on the Flex Consumption plan, with:
// - App Service Authentication (Easy Auth), which accepts only Microsoft Entra tokens for the hook's app registration
// from the gateway's managed identity, and answers 401 to every other request.
// - A private storage account (no public network access, no shared keys) that the app reaches through a virtual
// network and a private endpoint, with its managed identity. That works in subscriptions that block public storage.
// - Application Insights with Microsoft Entra authentication, for the decision log.
// The code is deployed separately: az functionapp deployment source config-zip, or azd deploy.
@description('Name of the function app. It must be globally unique: the host name is <name>.azurewebsites.net.')
@minLength(2)
@maxLength(32)
param appName string
@description('Region of the function app. Pick one where Flex Consumption is available (az functionapp list-flexconsumption-locations).')
param location string = resourceGroup().location
@description('Application (client) ID of the hook\'s app registration. Easy Auth accepts tokens issued for it.')
param hookClientId string
@description('Application ID URI of the hook\'s app registration. The gateway asks for tokens with this audience.')
param hookAudience string
@description('Object (principal) ID of the gateway\'s system-assigned managed identity: the only caller Easy Auth lets in.')
param gatewayPrincipalId string
@description('Comma-separated tool name patterns that the hook always denies before the call.')
param blockedTools string = '*code_sample*'
@description('Tags for every resource.')
param tags object = {}
var suffix = uniqueString(resourceGroup().id, appName)
var storageName = take('sthook${suffix}', 24)
var deploymentContainer = 'app-package-${take(toLower(appName), 32)}'
var blobPrivateDnsZone = 'privatelink.blob.${environment().suffixes.storage}'
// Role definitions: Storage Blob Data Owner (host storage and deployment package) and Monitoring Metrics Publisher
// (Application Insights with Microsoft Entra authentication).
var blobDataOwnerRoleId = 'b7e6dc6d-f1e8-4753-8033-0f276bb0955b'
var metricsPublisherRoleId = '3913510d-42f4-4e42-8a64-420c390055eb'
resource vnet 'Microsoft.Network/virtualNetworks@2024-05-01' = {
name: 'vnet-${appName}'
location: location
tags: tags
properties: {
addressSpace: { addressPrefixes: [ '10.30.0.0/16' ] }
subnets: [
{
// Flex Consumption joins this subnet for outbound traffic, so the app reaches the private storage account.
name: 'app'
properties: {
addressPrefix: '10.30.1.0/24'
delegations: [ { name: 'flex', properties: { serviceName: 'Microsoft.App/environments' } } ]
}
}
{
name: 'private-endpoints'
properties: {
addressPrefix: '10.30.2.0/24'
privateEndpointNetworkPolicies: 'Disabled'
}
}
]
}
}
resource storage 'Microsoft.Storage/storageAccounts@2024-01-01' = {
name: storageName
location: location
tags: tags
kind: 'StorageV2'
sku: { name: 'Standard_LRS' }
properties: {
allowBlobPublicAccess: false
allowSharedKeyAccess: false
publicNetworkAccess: 'Disabled'
minimumTlsVersion: 'TLS1_2'
networkAcls: { defaultAction: 'Deny', bypass: 'AzureServices' }
}
resource blobService 'blobServices' = {
name: 'default'
resource packages 'containers' = {
name: deploymentContainer
}
}
}
resource dnsZone 'Microsoft.Network/privateDnsZones@2024-06-01' = {
name: blobPrivateDnsZone
location: 'global'
tags: tags
resource link 'virtualNetworkLinks' = {
name: 'link-${vnet.name}'
location: 'global'
properties: {
registrationEnabled: false
virtualNetwork: { id: vnet.id }
}
}
}
resource blobEndpoint 'Microsoft.Network/privateEndpoints@2024-05-01' = {
name: 'pe-${storage.name}-blob'
location: location
tags: tags
properties: {
subnet: { id: vnet.properties.subnets[1].id }
privateLinkServiceConnections: [
{
name: 'blob'
properties: { privateLinkServiceId: storage.id, groupIds: [ 'blob' ] }
}
]
}
resource zoneGroup 'privateDnsZoneGroups' = {
name: 'default'
properties: {
privateDnsZoneConfigs: [ { name: 'blob', properties: { privateDnsZoneId: dnsZone.id } } ]
}
}
}
resource logs 'Microsoft.OperationalInsights/workspaces@2023-09-01' = {
name: 'log-${appName}'
location: location
tags: tags
properties: {
sku: { name: 'PerGB2018' }
retentionInDays: 30
}
}
resource appInsights 'Microsoft.Insights/components@2020-02-02' = {
name: 'appi-${appName}'
location: location
tags: tags
kind: 'web'
properties: {
Application_Type: 'web'
WorkspaceResourceId: logs.id
DisableLocalAuth: true
}
}
resource plan 'Microsoft.Web/serverfarms@2024-04-01' = {
name: 'plan-${appName}'
location: location
tags: tags
kind: 'functionapp'
sku: { tier: 'FlexConsumption', name: 'FC1' }
properties: { reserved: true }
}
resource app 'Microsoft.Web/sites@2024-04-01' = {
name: appName
location: location
// azd deploys the hook service's code to the app with this tag.
tags: union(tags, { 'azd-service-name': 'hook' })
kind: 'functionapp,linux'
identity: { type: 'SystemAssigned' }
properties: {
serverFarmId: plan.id
httpsOnly: true
virtualNetworkSubnetId: vnet.properties.subnets[0].id
siteConfig: { minTlsVersion: '1.2' }
functionAppConfig: {
deployment: {
storage: {
type: 'blobContainer'
value: '${storage.properties.primaryEndpoints.blob}${deploymentContainer}'
authentication: { type: 'SystemAssignedIdentity' }
}
}
scaleAndConcurrency: { maximumInstanceCount: 40, instanceMemoryMB: 2048 }
runtime: { name: 'python', version: '3.12' }
}
}
dependsOn: [ blobEndpoint::zoneGroup, dnsZone::link ]
resource settings 'config' = {
name: 'appsettings'
properties: {
AzureWebJobsStorage__accountName: storage.name
AzureWebJobsStorage__credential: 'managedidentity'
APPLICATIONINSIGHTS_CONNECTION_STRING: appInsights.properties.ConnectionString
APPLICATIONINSIGHTS_AUTHENTICATION_STRING: 'Authorization=AAD'
BLOCKED_TOOLS: blockedTools
}
}
// Easy Auth: validate the bearer token, its audience, and its caller before any function runs.
resource auth 'config' = {
name: 'authsettingsV2'
properties: {
platform: { enabled: true }
globalValidation: { requireAuthentication: true, unauthenticatedClientAction: 'Return401' }
identityProviders: {
azureActiveDirectory: {
enabled: true
registration: {
clientId: hookClientId
openIdIssuer: 'https://sts.windows.net/${tenant().tenantId}/v2.0'
}
validation: {
allowedAudiences: [ hookAudience, hookClientId ]
defaultAuthorizationPolicy: {
allowedPrincipals: { identities: [ gatewayPrincipalId ] }
}
}
}
}
login: { tokenStore: { enabled: false } }
}
}
}
resource blobOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
name: guid(storage.id, app.id, blobDataOwnerRoleId)
scope: storage
properties: {
principalId: app.identity.principalId
principalType: 'ServicePrincipal'
roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', blobDataOwnerRoleId)
}
}
resource metricsPublisher 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
name: guid(appInsights.id, app.id, metricsPublisherRoleId)
scope: appInsights
properties: {
principalId: app.identity.principalId
principalType: 'ServicePrincipal'
roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', metricsPublisherRoleId)
}
}
output appName string = app.name
output hookHost string = app.properties.defaultHostName
output hookUrl string = 'https://${app.properties.defaultHostName}/api/tool-hook'
output appInsightsName string = appInsights.name
output logWorkspaceName string = logs.name
output logWorkspaceId string = logs.properties.customerIdinfra/guarded-tool-server.bicep declares the learn server of lab 04 with an agentHooks policy that calls the
decision service before and after each tool call, and creates the app-first-call key.
// Declares the learn MCP server of lab 04 with an agent hooks policy: before each tool call and after each tool
// result, the gateway sends the call to the decision service and follows its allow or deny decision. The gateway signs
// in to the decision service with its system-assigned managed identity. The template also creates a runtime API key,
// which is never an output.
// A deployment sends a PUT, which replaces the whole MCP server, so keep this template as its only source of truth.
@description('Name of the existing AI Gateway (Microsoft.ApiManagement/aigateways).')
param gatewayName string
@description('MCP server name. It becomes part of the endpoint URL and cannot be changed after creation.')
param serverName string = 'learn'
@description('HTTPS endpoint of the decision service. Both intervention points share it.')
param hookUrl string
@description('Token audience: the Application ID URI of the decision service\'s app registration.')
param hookAudience string
@description('What the gateway does when the decision service can\'t answer: failClosed blocks the call, failOpen lets it through.')
@allowed([ 'failClosed', 'failOpen' ])
param hookMode string = 'failClosed'
@description('Runtime API key to create for the test calls.')
param apiKeyName string = 'app-first-call'
#disable-next-line BCP081
resource gateway 'Microsoft.ApiManagement/aigateways@2026-11-01' existing = {
name: gatewayName
}
#disable-next-line BCP081
resource workspace 'Microsoft.ApiManagement/aigateways/workspaces@2026-11-01' existing = {
parent: gateway
name: 'default'
}
#disable-next-line BCP081
resource toolServer 'Microsoft.ApiManagement/aigateways/workspaces/toolServers@2026-11-01' = {
parent: workspace
name: serverName
properties: {
toolServerType: 'mcp'
displayName: 'Microsoft Learn'
description: 'Search and fetch official Microsoft documentation and code samples.'
endpoints: [
{
namespace: 'learn'
kind: 'mcp'
mode: 'failClosed'
mcp: {
endpoint: { url: 'https://learn.microsoft.com/api/mcp' }
transport: 'streamableHttp'
}
}
]
policies: [
{
id: 'tool-guard'
type: 'agentHooks'
scope: 'resource'
mode: hookMode
endpoint: { url: hookUrl }
authentication: { managedIdentity: { resource: hookAudience } }
// Literal, non-secret headers. The gateway sends them with every hook request, and GET returns them.
headers: [ { name: 'x-hook-policy', value: 'lab30' } ]
// Both points inherit the endpoint, mode, authentication, and headers above. A point can override them.
hooks: {
preToolCall: {}
postToolCall: {}
}
}
]
}
}
#disable-next-line BCP081
resource apiKey 'Microsoft.ApiManagement/aigateways/apiKeys@2026-11-01' = {
parent: gateway
name: apiKeyName
properties: {
displayName: apiKeyName
}
}
output toolServerId string = toolServer.id
output mcpEndpoint string = 'https://${gateway.properties.frontend.defaultHostname}/default/toolservers/${serverName}/mcp'azure.yaml deploys the infra/hook folder to the function app. Its hooks restart the new app before the first
upload, and delete the app registration before azd down deletes the resource group, because the registration
lives in Microsoft Entra ID.
# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
# Lab 30: "azd up" registers the hook's Microsoft Entra application, creates a gateway, the decision service (a Python
# function app on Flex Consumption behind App Service Authentication), the learn MCP server with an agent hooks
# policy that calls the decision service before and after each tool call, and a runtime API key. Then it deploys the
# function code. The lab clones the repo's main branch from GitHub and runs azd up in this folder.
name: aigw-lab30
metadata:
template: aigw-lab30@1.0.0
infra:
provider: bicep
path: infra
services:
hook:
project: ./infra/hook
language: python
host: function
hooks:
# A new Flex Consumption app that reaches its storage through a private endpoint can fail the first code upload
# with "BlobUploadFailedException ... Resource temporarily unavailable" until it restarts once. Restart it before
# azd deploys the code.
postprovision:
posix:
shell: sh
run: az functionapp restart --resource-group "$AZURE_RESOURCE_GROUP" --name "$HOOK_APP_NAME"
windows:
shell: pwsh
run: az functionapp restart --resource-group $env:AZURE_RESOURCE_GROUP --name $env:HOOK_APP_NAME
# The app registration lives in Microsoft Entra ID, not in the resource group, so deleting the resource group
# doesn't delete it. Before "azd down" deletes the resource group (and the outputs saved in the azd environment),
# this hook deletes the registration with the client ID that the deployment saved, then removes it from the deleted
# items so that the next "azd up" can register it again.
predown:
continueOnError: true
posix:
shell: sh
run: >-
if [ -n "$HOOK_CLIENT_ID" ]; then
id=$(az ad app show --id "$HOOK_CLIENT_ID" --query id --output tsv) &&
az ad app delete --id "$HOOK_CLIENT_ID" &&
az rest --method delete --url "https://graph.microsoft.com/v1.0/directory/deletedItems/$id" &&
echo "Deleted the app registration $HOOK_CLIENT_ID";
fi
windows:
shell: pwsh
run: >-
if ($env:HOOK_CLIENT_ID) {
$id = az ad app show --id $env:HOOK_CLIENT_ID --query id --output tsv;
if ($id) {
az ad app delete --id $env:HOOK_CLIENT_ID;
az rest --method delete --url "https://graph.microsoft.com/v1.0/directory/deletedItems/$id";
"Deleted the app registration $env:HOOK_CLIENT_ID" } }A Bicep deployment sends a PUT, which replaces the whole MCP server, including backends and policies that you
added in the portal. Keep the template as the only source of truth for this server, and change it with
azd provision.
Deploy with azd up
Move into the lab's folder, create an azd environment named aigw-lab30 in your current subscription, then provision
everything and deploy the function's code. It takes four to eight minutes.
# Move into the lab's folder, which holds the azd project
cd ~/aigateway/labs/30-agent-hooks &&
echo "๐ Lab folder: $(pwd)"
# Create an azd environment in your current subscription, so that azd doesn't prompt you
azd env new aigw-lab30 --location eastus2 --subscription "$(az account show --query id --output tsv)" &&
echo "๐ azd environment aigw-lab30 deploys to eastus2"
# Provision the app registration, the gateway, the decision service, and the governed MCP server, then deploy the code
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/30-agent-hooks
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-lab30 --location eastus2 --subscription (az account show --query id --output tsv)
if ($?) { Write-Host "๐ azd environment aigw-lab30 deploys to eastus2" }
# Provision the app registration, the gateway, the decision service, and the governed MCP server, then deploy the code
azd up
if ($?) { Write-Host "๐ Gateway deployed: $(azd env get-value AI_GATEWAY_URL)" }For another region, use one that has both AI Gateway and Flex Consumption, from Find the available regions.
Read the outputs and the key
Set the variables that the next steps, Verify, and Clean up use from azd's environment values, and read the key from the gateway, so that it never shows on screen.
# Read azd's outputs: the resource group, the gateway, the MCP server, and the gateway's ID and runtime URL
export RG="$(azd env get-value AZURE_RESOURCE_GROUP)"
export GATEWAY="$(azd env get-value AI_GATEWAY_NAME)"
export MCP_SERVER="$(azd env get-value MCP_SERVER)"
export GATEWAY_ID="$(azd env get-value AI_GATEWAY_ID)"
export AI_GATEWAY_URL="$(azd env get-value AI_GATEWAY_URL)"
echo "๐ Gateway $GATEWAY in $RG, MCP server $MCP_SERVER"
echo "๐ Runtime URL: $AI_GATEWAY_URL"
# Read the decision service's outputs: the function app, its URL, its token audience, and its log workspace
export HOOK_RG="$RG"
export HOOK_APP="$(azd env get-value HOOK_APP_NAME)"
export HOOK_URL="$(azd env get-value HOOK_URL)"
export HOOK_AUDIENCE="$(azd env get-value HOOK_AUDIENCE)"
export HOOK_LOG_WORKSPACE_ID="$(azd env get-value HOOK_LOG_WORKSPACE_ID)"
echo "๐ Hook URL: $HOOK_URL"
echo "๐ค Token audience: $HOOK_AUDIENCE"
# Read the app-first-call key from the gateway, so that it never shows on screen
export AI_GATEWAY_API_KEY="$(az aigateway api-key list-secrets --ids "$GATEWAY_ID/apiKeys/app-first-call" \
--query primaryKey --output tsv)"
echo "๐ Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"# Read azd's outputs: the resource group, the gateway, the MCP server, and the gateway's ID and runtime URL
$RG = azd env get-value AZURE_RESOURCE_GROUP
$GATEWAY = azd env get-value AI_GATEWAY_NAME
$MCP_SERVER = azd env get-value MCP_SERVER
$GATEWAY_ID = azd env get-value AI_GATEWAY_ID
$env:AI_GATEWAY_URL = azd env get-value AI_GATEWAY_URL
Write-Host "๐ Gateway $GATEWAY in $RG, MCP server $MCP_SERVER"
Write-Host "๐ Runtime URL: $env:AI_GATEWAY_URL"
# Read the decision service's outputs: the function app, its URL, its token audience, and its log workspace
$HOOK_RG = $RG
$HOOK_APP = azd env get-value HOOK_APP_NAME
$HOOK_URL = azd env get-value HOOK_URL
$HOOK_AUDIENCE = azd env get-value HOOK_AUDIENCE
$HOOK_LOG_WORKSPACE_ID = azd env get-value HOOK_LOG_WORKSPACE_ID
Write-Host "๐ Hook URL: $HOOK_URL"
Write-Host "๐ค Token audience: $HOOK_AUDIENCE"
# Read the app-first-call key from the gateway, so that it never shows on screen
$env:AI_GATEWAY_API_KEY = az aigateway api-key list-secrets --ids "$GATEWAY_ID/apiKeys/app-first-call" `
--query primaryKey --output tsv
Write-Host "๐ Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"azd up ended with SUCCESS, the hook URL ends with /api/tool-hook, and the token audience starts with
api://.
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, and permission to register applications in
Microsoft Entra ID. This track doesn't use your gateway or learn server from lab 04: terraform apply creates a
new gateway with its own learn server, the decision service, and the policy, so it works on its own.
Review the configuration
The configuration deploys the same resources as the Bicep templates. terraform/main.tf creates the resource group
rg-<environment_name> and calls lab 01's gateway module for a gateway
with no model. terraform/variables.tf declares the two settings of the Bicep track, with the same defaults:
| Variable | Bicep parameter | Default |
|---|---|---|
hook_mode | hookMode | failClosed |
blocked_tools | blockedTools | *code_sample* |
# Lab 30 with Terraform: registers the decision service in Microsoft Entra ID (hook-registration.tf), creates the
# resource group rg-<environment_name>, a gateway with lab 01's module, the decision service (hook.tf), deploys its
# code (hook-code.tf), then the learn MCP server with the agent hooks policy and the runtime API key app-first-call
# (guarded-tool-server.tf). The runtime API key is never 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
}
# Lab 01's module: the gateway, with no model.
module "gateway" {
source = "../../01-provision-gateway/terraform/gateway"
gateway_name = "aigw-${local.suffix}"
resource_group_id = azurerm_resource_group.rg.id
location = var.location
tags = local.tags
}terraform/hook-registration.tf registers the app and its service principal with the azuread provider, which
signs in to Microsoft Entra ID with your Azure CLI session. The application ID URI is the token audience.
# Registers the decision service in Microsoft Entra ID: an application whose Application ID URI is the token audience
# that the gateway asks for, and its service principal, without which Microsoft Entra ID can't issue tokens for that
# audience. The registration has no secret: the gateway signs in with its managed identity, and App Service
# Authentication only validates the tokens. terraform destroy deletes the application, which then stays in the
# tenant's deleted items for 30 days: the lab's Clean up purges it.
locals {
hook_registration_name = "aigw-lab30-hook-${local.suffix}"
# The token audience that the gateway asks for, and that Easy Auth accepts.
hook_audience = one(azuread_application.hook.identifier_uris)
}
resource "azuread_application" "hook" {
display_name = local.hook_registration_name
sign_in_audience = "AzureADMyOrg"
# api://<tenant ID>/<name> passes the tenant's identifier URI policy without a verified domain.
identifier_uris = ["api://${data.azapi_client_config.current.tenant_id}/${local.hook_registration_name}"]
}
resource "azuread_service_principal" "hook" {
client_id = azuread_application.hook.client_id
}terraform/hook.tf is the function app of infra/hook.bicep: Flex Consumption, App Service Authentication that
lets in only the gateway's identity, a private storage account, and Application Insights. The network, storage, logs,
plan, and role assignments use azurerm. The function app and its App Service Authentication settings use azapi,
because azurerm_function_app_flex_consumption always writes an AzureWebJobsStorage connection string with an
account key, which a storage account without shared keys rejects.
# The agent hooks decision service: a Python function app on the Flex Consumption plan, with:
# - App Service Authentication (Easy Auth), which accepts only Microsoft Entra tokens for the hook's app registration
# from the gateway's managed identity, and answers 401 to every other request.
# - A private storage account (no public network access, no shared keys) that the app reaches through a virtual
# network and a private endpoint, with its managed identity. That works in subscriptions that block public storage.
# - Application Insights with Microsoft Entra authentication, for the decision log.
# The function app and its Easy Auth settings use azapi: azurerm_function_app_flex_consumption always writes an
# AzureWebJobsStorage connection string with an account key, which a storage account without shared keys rejects.
locals {
hook_app_name = "func-aigw-hook-${local.suffix}"
hook_storage_name = "sthook${substr(sha1("${azurerm_resource_group.rg.id}/${local.hook_app_name}"), 0, 13)}"
deployment_container = "app-package-${local.hook_app_name}"
# Storage Blob Data Owner (host storage and deployment package) and Monitoring Metrics Publisher (Application
# Insights with Microsoft Entra authentication).
blob_data_owner_role_id = "b7e6dc6d-f1e8-4753-8033-0f276bb0955b"
metrics_publisher_role_id = "3913510d-42f4-4e42-8a64-420c390055eb"
}
resource "azurerm_virtual_network" "hook" {
name = "vnet-${local.hook_app_name}"
resource_group_name = azurerm_resource_group.rg.name
location = var.location
address_space = ["10.30.0.0/16"]
tags = local.tags
}
# Flex Consumption joins this subnet for outbound traffic, so the app reaches the private storage account.
resource "azurerm_subnet" "app" {
name = "app"
resource_group_name = azurerm_resource_group.rg.name
virtual_network_name = azurerm_virtual_network.hook.name
address_prefixes = ["10.30.1.0/24"]
delegation {
name = "flex"
service_delegation {
name = "Microsoft.App/environments"
actions = ["Microsoft.Network/virtualNetworks/subnets/join/action"]
}
}
}
resource "azurerm_subnet" "private_endpoints" {
name = "private-endpoints"
resource_group_name = azurerm_resource_group.rg.name
virtual_network_name = azurerm_virtual_network.hook.name
address_prefixes = ["10.30.2.0/24"]
private_endpoint_network_policies = "Disabled"
}
resource "azurerm_storage_account" "hook" {
name = local.hook_storage_name
resource_group_name = azurerm_resource_group.rg.name
location = var.location
account_kind = "StorageV2"
account_tier = "Standard"
account_replication_type = "LRS"
allow_nested_items_to_be_public = false
shared_access_key_enabled = false
public_network_access = "Disabled"
min_tls_version = "TLS1_2"
tags = local.tags
network_rules {
default_action = "Deny"
bypass = ["AzureServices"]
}
}
resource "azurerm_storage_container" "packages" {
name = local.deployment_container
storage_account_id = azurerm_storage_account.hook.id
}
resource "azurerm_private_dns_zone" "blob" {
name = "privatelink.blob.core.windows.net"
resource_group_name = azurerm_resource_group.rg.name
tags = local.tags
}
resource "azurerm_private_dns_zone_virtual_network_link" "hook" {
name = "link-${azurerm_virtual_network.hook.name}"
private_dns_zone_id = azurerm_private_dns_zone.blob.id
virtual_network_id = azurerm_virtual_network.hook.id
registration_enabled = false
tags = local.tags
}
resource "azurerm_private_endpoint" "blob" {
name = "pe-${azurerm_storage_account.hook.name}-blob"
resource_group_name = azurerm_resource_group.rg.name
location = var.location
subnet_id = azurerm_subnet.private_endpoints.id
tags = local.tags
private_service_connection {
name = "blob"
private_connection_resource_id = azurerm_storage_account.hook.id
subresource_names = ["blob"]
is_manual_connection = false
}
private_dns_zone_group {
name = "default"
private_dns_zone_ids = [azurerm_private_dns_zone.blob.id]
}
}
resource "azurerm_log_analytics_workspace" "hook" {
name = "log-${local.hook_app_name}"
resource_group_name = azurerm_resource_group.rg.name
location = var.location
sku = "PerGB2018"
retention_in_days = 30
tags = local.tags
}
resource "azurerm_application_insights" "hook" {
name = "appi-${local.hook_app_name}"
resource_group_name = azurerm_resource_group.rg.name
location = var.location
application_type = "web"
workspace_id = azurerm_log_analytics_workspace.hook.id
local_authentication_enabled = false
tags = local.tags
}
resource "azurerm_service_plan" "hook" {
name = "plan-${local.hook_app_name}"
resource_group_name = azurerm_resource_group.rg.name
location = var.location
os_type = "Linux"
sku_name = "FC1"
tags = local.tags
}
resource "azapi_resource" "hook_app" {
type = "Microsoft.Web/sites@2024-04-01"
name = local.hook_app_name
parent_id = azurerm_resource_group.rg.id
location = var.location
tags = local.tags
identity {
type = "SystemAssigned"
}
body = {
kind = "functionapp,linux"
properties = {
serverFarmId = azurerm_service_plan.hook.id
httpsOnly = true
virtualNetworkSubnetId = azurerm_subnet.app.id
siteConfig = {
minTlsVersion = "1.2"
appSettings = [
{ name = "AzureWebJobsStorage__accountName", value = azurerm_storage_account.hook.name },
{ name = "AzureWebJobsStorage__credential", value = "managedidentity" },
{ name = "APPLICATIONINSIGHTS_CONNECTION_STRING", value = azurerm_application_insights.hook.connection_string },
{ name = "APPLICATIONINSIGHTS_AUTHENTICATION_STRING", value = "Authorization=AAD" },
{ name = "BLOCKED_TOOLS", value = var.blocked_tools },
]
}
functionAppConfig = {
deployment = {
storage = {
type = "blobContainer"
value = "${azurerm_storage_account.hook.primary_blob_endpoint}${azurerm_storage_container.packages.name}"
authentication = { type = "SystemAssignedIdentity" }
}
}
scaleAndConcurrency = { maximumInstanceCount = 40, instanceMemoryMB = 2048 }
runtime = { name = "python", version = "3.12" }
}
}
}
response_export_values = ["properties.defaultHostName"]
# GET returns serverFarmId with .../serverfarms/..., and azurerm's plan ID has .../serverFarms/...
ignore_casing = true
depends_on = [azurerm_private_endpoint.blob, azurerm_private_dns_zone_virtual_network_link.hook]
}
# Easy Auth: validate the bearer token, its audience, and its caller before any function runs. An update, because a
# site's configuration can't be deleted: it goes with the app.
resource "azapi_update_resource" "hook_auth" {
type = "Microsoft.Web/sites/config@2024-04-01"
name = "authsettingsV2"
parent_id = azapi_resource.hook_app.id
body = {
properties = {
platform = { enabled = true }
globalValidation = { requireAuthentication = true, unauthenticatedClientAction = "Return401" }
identityProviders = {
azureActiveDirectory = {
enabled = true
registration = {
clientId = azuread_application.hook.client_id
openIdIssuer = "https://sts.windows.net/${data.azapi_client_config.current.tenant_id}/v2.0"
}
validation = {
allowedAudiences = [local.hook_audience, azuread_application.hook.client_id]
defaultAuthorizationPolicy = {
allowedPrincipals = { identities = [module.gateway.principal_id] }
}
}
}
}
login = { tokenStore = { enabled = false } }
}
}
}
resource "azurerm_role_assignment" "blob_owner" {
name = uuidv5("url", "${azurerm_storage_account.hook.id}/${azapi_resource.hook_app.id}/${local.blob_data_owner_role_id}")
scope = azurerm_storage_account.hook.id
role_definition_id = "/subscriptions/${data.azapi_client_config.current.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/${local.blob_data_owner_role_id}"
principal_id = azapi_resource.hook_app.identity[0].principal_id
principal_type = "ServicePrincipal"
skip_service_principal_aad_check = true
}
resource "azurerm_role_assignment" "metrics_publisher" {
name = uuidv5("url", "${azurerm_application_insights.hook.id}/${azapi_resource.hook_app.id}/${local.metrics_publisher_role_id}")
scope = azurerm_application_insights.hook.id
role_definition_id = "/subscriptions/${data.azapi_client_config.current.subscription_id}/providers/Microsoft.Authorization/roleDefinitions/${local.metrics_publisher_role_id}"
principal_id = azapi_resource.hook_app.identity[0].principal_id
principal_type = "ServicePrincipal"
skip_service_principal_aad_check = true
}terraform/hook-code.tf deploys the function in infra/hook, like azd deploy. The archive provider zips only its
three files, so local files such as local.settings.json stay on your machine. Then the Azure CLI on your machine
restarts the new app once and uploads the zip with a remote build. Terraform runs the upload again when the code
changes.
# Deploys the function code in infra/hook, like azd deploy. The archive provider zips only the function's three files,
# so local files such as local.settings.json, .venv, and __pycache__ stay on your machine, as .funcignore keeps them
# out of azd deploy. Then the Azure CLI restarts the new app once (a new Flex Consumption app that reaches its storage
# through a private endpoint can fail its first code upload until it restarts) and uploads the zip with a remote
# build, which installs requirements.txt. The deployment runs again when the code or the app changes.
data "archive_file" "hook_code" {
type = "zip"
output_path = "${path.module}/.terraform/hook.zip"
dynamic "source" {
for_each = ["function_app.py", "host.json", "requirements.txt"]
content {
content = file("${path.module}/../infra/hook/${source.value}")
filename = source.value
}
}
}
resource "terraform_data" "hook_code" {
triggers_replace = [azapi_resource.hook_app.id, data.archive_file.hook_code.output_sha256]
provisioner "local-exec" {
command = "az functionapp restart --resource-group ${azurerm_resource_group.rg.name} --name ${azapi_resource.hook_app.name} && az functionapp deployment source config-zip --resource-group ${azurerm_resource_group.rg.name} --name ${azapi_resource.hook_app.name} --src \"${abspath(data.archive_file.hook_code.output_path)}\" --build-remote true --output none"
}
# The app reads its package and writes its logs with its managed identity.
depends_on = [azurerm_role_assignment.blob_owner, azurerm_role_assignment.metrics_publisher, azapi_update_resource.hook_auth]
}terraform/guarded-tool-server.tf declares the learn server of lab 04 with the agent hooks policy, and creates the
app-first-call key, like infra/guarded-tool-server.bicep. terraform/providers.tf
adds the azuread and archive providers to the quick start's.
# Declares the learn MCP server of lab 04 with an agent hooks policy: before each tool call and after each tool
# result, the gateway sends the call to the decision service and follows its allow or deny decision. The gateway signs
# in to the decision service with its system-assigned managed identity. The file also creates a runtime API key,
# which is never an output. Terraform sends a PUT, which replaces the whole MCP server, so keep this file as its only
# source of truth.
locals {
hook_url = "https://${azapi_resource.hook_app.output.properties.defaultHostName}/api/tool-hook"
}
resource "azapi_resource" "tool_server" {
type = "Microsoft.ApiManagement/aigateways/workspaces/toolServers@2026-11-01"
name = "learn"
parent_id = "${module.gateway.gateway_id}/workspaces/default"
body = {
properties = {
toolServerType = "mcp"
displayName = "Microsoft Learn"
description = "Search and fetch official Microsoft documentation and code samples."
endpoints = [
{
namespace = "learn"
kind = "mcp"
mode = "failClosed"
mcp = {
endpoint = { url = "https://learn.microsoft.com/api/mcp" }
transport = "streamableHttp"
}
}
]
policies = [
{
id = "tool-guard"
type = "agentHooks"
scope = "resource"
mode = var.hook_mode
endpoint = { url = local.hook_url }
authentication = { managedIdentity = { resource = local.hook_audience } }
# Literal, non-secret headers. The gateway sends them with every hook request, and GET returns them.
headers = [{ name = "x-hook-policy", value = "lab30" }]
# Both points inherit the endpoint, mode, authentication, and headers above. A point can override them.
hooks = {
preToolCall = {}
postToolCall = {}
}
}
]
}
}
schema_validation_enabled = false
}
# A runtime API key for the test calls. Read its value with az aigateway api-key list-secrets.
resource "azapi_resource" "api_key" {
type = "Microsoft.ApiManagement/aigateways/apiKeys@2026-11-01"
name = "app-first-call"
parent_id = module.gateway.gateway_id
body = {
properties = {
displayName = "app-first-call"
}
}
schema_validation_enabled = false
}Terraform sends a PUT, which replaces the whole MCP server, including backends and policies that you added in
the portal. Keep the configuration as the only source of truth for this server, and change it with
terraform apply.
Deploy with terraform apply
Move into the lab's Terraform folder, select your current subscription, then plan and apply the configuration. It
takes about five minutes. While the code uploads, the Azure CLI prints progress lines such as
WARNING: Checking the health of the function app.
# Move into the lab's Terraform folder
cd ~/aigateway/labs/30-agent-hooks/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 app registration, the gateway, the decision service and its code,
# and the governed 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/30-agent-hooks/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 app registration, the gateway, the decision service and its code,
# and the governed 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 that has both AI Gateway and Flex Consumption, from
Find the available regions, run export TF_VAR_location=<region>
(PowerShell: $env:TF_VAR_location = "<region>") before terraform plan.
Read the outputs and the key
Set the variables that the next steps, Verify, and Clean up use from the Terraform outputs, and read the key from the gateway, so that it never shows on screen or lands in the Terraform state.
# Read the configuration's outputs: the resource group, the gateway, the MCP server, and the gateway's ID and
# runtime URL
export RG="$(terraform output -raw azure_resource_group)"
export GATEWAY="$(terraform output -raw ai_gateway_name)"
export MCP_SERVER="$(terraform output -raw mcp_server)"
export GATEWAY_ID="$(terraform output -raw ai_gateway_id)"
export AI_GATEWAY_URL="$(terraform output -raw ai_gateway_url)"
echo "๐ Gateway $GATEWAY in $RG, MCP server $MCP_SERVER"
echo "๐ Runtime URL: $AI_GATEWAY_URL"
# Read the decision service's outputs: the function app, its URL, its token audience, and its log workspace
export HOOK_RG="$RG"
export HOOK_APP="$(terraform output -raw hook_app_name)"
export HOOK_URL="$(terraform output -raw hook_url)"
export HOOK_AUDIENCE="$(terraform output -raw hook_audience)"
export HOOK_LOG_WORKSPACE_ID="$(terraform output -raw hook_log_workspace_id)"
echo "๐ Hook URL: $HOOK_URL"
echo "๐ค Token audience: $HOOK_AUDIENCE"
# Read the app-first-call 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/app-first-call" \
--query primaryKey --output tsv)"
echo "๐ Key: in AI_GATEWAY_API_KEY (${#AI_GATEWAY_API_KEY} characters, not shown)"# Read the configuration's outputs: the resource group, the gateway, the MCP server, and the gateway's ID and
# runtime URL
$RG = terraform output -raw azure_resource_group
$GATEWAY = terraform output -raw ai_gateway_name
$MCP_SERVER = terraform output -raw mcp_server
$GATEWAY_ID = terraform output -raw ai_gateway_id
$env:AI_GATEWAY_URL = terraform output -raw ai_gateway_url
Write-Host "๐ Gateway $GATEWAY in $RG, MCP server $MCP_SERVER"
Write-Host "๐ Runtime URL: $env:AI_GATEWAY_URL"
# Read the decision service's outputs: the function app, its URL, its token audience, and its log workspace
$HOOK_RG = $RG
$HOOK_APP = terraform output -raw hook_app_name
$HOOK_URL = terraform output -raw hook_url
$HOOK_AUDIENCE = terraform output -raw hook_audience
$HOOK_LOG_WORKSPACE_ID = terraform output -raw hook_log_workspace_id
Write-Host "๐ Hook URL: $HOOK_URL"
Write-Host "๐ค Token audience: $HOOK_AUDIENCE"
# Read the app-first-call 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/app-first-call" `
--query primaryKey --output tsv
Write-Host "๐ Key: in AI_GATEWAY_API_KEY ($($env:AI_GATEWAY_API_KEY.Length) characters, not shown)"terraform apply ended with Apply complete! Resources: 22 added, 0 changed, 0 destroyed., the hook URL ends
with /api/tool-hook, and the token audience starts with api://.
Attach the hook to the MCP server
Add an agent hooks policy to the learn MCP server that calls your decision service as the gateway's managed
identity, and blocks the call when the service fails. The portal configures one intervention point per policy; the
Azure CLI, Bicep + azd, and Terraform tracks configure both.
Choose the policy type
Open the AI Gateway portal and select your gateway from the gateway switcher. Select PoliciesAdd policy. On the Type step, under Security, select Agent hooks. Its card carries the Preview and MCP server badges and reads "Invoke governance controls at MCP tool-call intervention points, with hooks hosted in any service." Select Next.
Select the MCP server
On the Scope step, the wizard notes that this policy applies to individual MCP servers. Check the learn server,
Microsoft Learn in lab 04, then select Next.
Configure the hook
On the Details step, set:
| Field | Value |
|---|---|
| Intervention point | Before tool call |
| Endpoint | The value of HOOK_URL, such as https://func-<name>.azurewebsites.net/api/tool-hook |
| Failure mode | Fail closed |
| Authentication | Managed identity |
| Managed identity | System-assigned managed identity |
| Token audience | The value of HOOK_AUDIENCE, such as api://<client-id> |
| Headers | Select Add header, then enter x-hook-policy as Header name and lab30 as Value |
Then select Create. The hint under Intervention point reads "Only one intervention point is supported in this preview."
Check the policy list
The Policies list shows Before tool calls under Configuration, Agent hooks under Type, and MCP server: Microsoft Learn under Scope.
To add After tool call to the same policy, run the Azure CLI track's steps instead: they replace the portal's policy with one that has both intervention points.
Write the policy
az aigateway mcp update --policies replaces the server's whole policy array. Read the server's policies with
az aigateway mcp show, keep the others, and add the hook.
# Describe the hook: ask the decision service before and after each tool call, as the gateway's managed identity
HOOK_POLICY="$(jq -cn --arg url "$HOOK_URL" --arg aud "$HOOK_AUDIENCE" '{id:"tool-guard",type:"agentHooks",scope:"resource",mode:"failClosed",endpoint:{url:$url},authentication:{managedIdentity:{resource:$aud}},headers:[{name:"x-hook-policy",value:"lab30"}],hooks:{preToolCall:{},postToolCall:{}}}')"
echo "๐ Agent hooks policy tool-guard calls $HOOK_URL"
# Read the server's policies, keep every policy except agent hooks, and add the new one
POLICIES="$(az aigateway mcp show -g "$RG" --gateway-name "$GATEWAY" -n "$MCP_SERVER" -o json |
jq -c --argjson hook "$HOOK_POLICY" '[(.properties.policies // [])[] | select(.type != "agentHooks")] + [$hook]')"
echo "๐ Policies to write: $(jq length <<< "$POLICIES"), including tool-guard"
# Replace the server's whole policies array with the merged one
az aigateway mcp update -g "$RG" --gateway-name "$GATEWAY" -n "$MCP_SERVER" --policies "$POLICIES" -o none &&
echo "๐ Agent hooks policy tool-guard is on the $MCP_SERVER MCP server"# Describe the hook: ask the decision service before and after each tool call, as the gateway's managed identity
$hookPolicy = [pscustomobject]@{
id = 'tool-guard'; type = 'agentHooks'; scope = 'resource'; mode = 'failClosed'
endpoint = @{ url = $HOOK_URL }
authentication = @{ managedIdentity = @{ resource = $HOOK_AUDIENCE } }
headers = @(@{ name = 'x-hook-policy'; value = 'lab30' })
hooks = @{ preToolCall = @{}; postToolCall = @{} }
}
Write-Host "๐ Agent hooks policy tool-guard calls $HOOK_URL"
# Read the server's policies, keep every policy except agent hooks, and add the new one
$current = az aigateway mcp show -g $RG --gateway-name $GATEWAY -n $MCP_SERVER -o json | ConvertFrom-Json
$policies = @($current.properties.policies | Where-Object { $_ -and $_.type -ne 'agentHooks' }) + $hookPolicy
Write-Host "๐ Policies to write: $($policies.Count), including tool-guard"
# Write the policies to a file, which --policies reads with the @ prefix, then replace the whole policies array
ConvertTo-Json -InputObject $policies -Depth 10 -Compress | Set-Content -Path policies.json
az aigateway mcp update -g $RG --gateway-name $GATEWAY -n $MCP_SERVER --policies '@policies.json' -o none
if ($?) { Write-Host "๐ Agent hooks policy tool-guard is on the $MCP_SERVER MCP server" }
Remove-Item policies.jsonRead the policy back
# Read the agent hooks policy on the MCP server
echo "๐ Agent hooks policy on the $MCP_SERVER MCP server:"
az aigateway mcp show -g "$RG" --gateway-name "$GATEWAY" -n "$MCP_SERVER" --query "properties.policies[?type=='agentHooks']"# Read the agent hooks policy on the MCP server
Write-Host "๐ Agent hooks policy on the $MCP_SERVER MCP server:"
az aigateway mcp show -g $RG --gateway-name $GATEWAY -n $MCP_SERVER --query "properties.policies[?type=='agentHooks']"The policy has "type": "agentHooks", "mode": "failClosed", your endpoint.url, managedIdentity.resource,
and both preToolCall and postToolCall under hooks. The CLI masks header values as "***"; the gateway still
sends lab30, which the decision log shows in Verify.
In the AI Gateway portal, Policies lists it as Before and after tool calls, of type Agent hooks. Select it to see both intervention points with their settings.
Read the policy that azd attached
azd up already attached the policy. Read it back.
# Read the agent hooks policy on the MCP server
echo "๐ Agent hooks policy on the $MCP_SERVER MCP server:"
az aigateway mcp show -g "$RG" --gateway-name "$GATEWAY" -n "$MCP_SERVER" --query "properties.policies[?type=='agentHooks']"# Read the agent hooks policy on the MCP server
Write-Host "๐ Agent hooks policy on the $MCP_SERVER MCP server:"
az aigateway mcp show -g $RG --gateway-name $GATEWAY -n $MCP_SERVER --query "properties.policies[?type=='agentHooks']"The policy has "id": "tool-guard", "type": "agentHooks", "mode": "failClosed", the hook URL, the token
audience, and both preToolCall and postToolCall under hooks. The CLI masks header values as "***".
Read the policy that Terraform attached
terraform apply already attached the policy. Read it back, then move back to the lab's folder, where the next
steps run the test script.
# Read the agent hooks policy on the MCP server
echo "๐ Agent hooks policy on the $MCP_SERVER MCP server:"
az aigateway mcp show -g "$RG" --gateway-name "$GATEWAY" -n "$MCP_SERVER" --query "properties.policies[?type=='agentHooks']"
# Move back to the lab's folder, where the next steps run the test script
cd .. &&
echo "๐ Lab folder: $(pwd)"# Read the agent hooks policy on the MCP server
Write-Host "๐ Agent hooks policy on the $MCP_SERVER MCP server:"
az aigateway mcp show -g $RG --gateway-name $GATEWAY -n $MCP_SERVER --query "properties.policies[?type=='agentHooks']"
# Move back to the lab's folder, where the next steps run the test script
Set-Location ..
if ($?) { Write-Host "๐ Lab folder: $(Get-Location)" }The policy has "id": "tool-guard", "type": "agentHooks", "mode": "failClosed", the hook URL, the token
audience, and both preToolCall and postToolCall under hooks. The CLI masks header values as "***".
Don't edit a policy with both intervention points in the portal. Its Edit policy panel reads "This policy has both intervention points. Choose one to continue.", and saving keeps only the point that you choose. Change such a policy with the Azure CLI, Bicep, or Terraform.
Call tools through the hook
infra/call-tool.sh runs the MCP handshake and calls one tool with your runtime key. It
prints isError: false with the start of the result, or isError: true with the gateway's message.
#!/usr/bin/env bash
# Calls one tool on an AI Gateway MCP server with the MCP Streamable HTTP handshake
# (initialize -> notifications/initialized -> tools/call), and prints whether the result came back or the gateway's
# denial: the JSON-RPC error, or isError with the denial details in _meta.
#
# Usage:
# export AI_GATEWAY_URL="<gateway-url>"
# export AI_GATEWAY_API_KEY="<runtime key>" # Access > API keys; never paste it into a file
# ./call-tool.sh <tool-name> '<arguments as JSON>' [server-name]
#
# Example:
# ./call-tool.sh learn_microsoft_docs_search '{"query": "What is Azure Functions?"}'
# Requires curl and jq.
set -euo pipefail
TOOL="${1:?Pass the tool name, for example learn_microsoft_docs_search}"
ARGS="${2:-}"
[ -n "$ARGS" ] || ARGS='{}'
SERVER="${3:-learn}"
: "${AI_GATEWAY_URL:?Set AI_GATEWAY_URL to the gateway runtime URL}"
: "${AI_GATEWAY_API_KEY:?Set AI_GATEWAY_API_KEY to a runtime key from Access > API keys}"
command -v jq >/dev/null || { echo "This script needs jq." >&2; exit 1; }
printf '%s' "$ARGS" | jq -e 'type == "object"' >/dev/null || { echo "The arguments must be a JSON object." >&2; exit 1; }
ENDPOINT="${AI_GATEWAY_URL%/}/default/toolservers/${SERVER}/mcp"
HEADERS=(-H "Authorization: Bearer $AI_GATEWAY_API_KEY" -H "Content-Type: application/json"
-H "Accept: application/json, text/event-stream")
STATUS="" BODY="" SESSION_ID=""
# post <json>: sends one JSON-RPC message and sets STATUS and BODY (and SESSION_ID when the server returns one).
post() {
local raw head sid
raw="$(curl -sS --max-time 120 -D - "$ENDPOINT" "${HEADERS[@]}" --data "$1" | tr -d '\r')"
if [[ "$raw" == *$'\n\n'* ]]; then head="${raw%%$'\n\n'*}"; BODY="${raw#*$'\n\n'}"; else head="$raw"; BODY=""; fi
STATUS="$(printf '%s\n' "$head" | awk 'toupper($1) ~ /^HTTP/ {code=$2} END {print code}')"
sid="$(printf '%s\n' "$head" | awk -F': ' 'tolower($1)=="mcp-session-id" {print $2}')"
if [ -n "$sid" ]; then SESSION_ID="$sid"; fi
}
# response <id>: prints the JSON-RPC response with that id. The body can be JSON or server-sent events.
response() {
if printf '%s\n' "$BODY" | grep -q '^data:'; then
printf '%s\n' "$BODY" | sed -n 's/^data:[[:space:]]*//p'
else
printf '%s\n' "$BODY"
fi | jq -c --argjson id "$1" 'select(type == "object" and .id == $id)' 2>/dev/null || true
}
# require_success <step>: stops with the gateway's answer when the HTTP status isn't 2xx.
require_success() {
case "$STATUS" in
2??) ;;
*) echo "$1 failed with HTTP ${STATUS:-no response}:" >&2; printf '%s\n' "$BODY" >&2; exit 1 ;;
esac
}
post '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"aigateway-labs","version":"1.0"}}}'
require_success "initialize"
PROTOCOL="$(response 1 | jq -r '.result.protocolVersion // empty')"
if [ -z "$PROTOCOL" ]; then echo "initialize returned no result:" >&2; printf '%s\n' "$BODY" >&2; exit 1; fi
HEADERS+=(-H "MCP-Protocol-Version: $PROTOCOL")
if [ -n "$SESSION_ID" ]; then HEADERS+=(-H "Mcp-Session-Id: $SESSION_ID"); fi
post '{"jsonrpc":"2.0","method":"notifications/initialized"}'
require_success "notifications/initialized"
echo "tools/call $TOOL $(printf '%s' "$ARGS" | jq -c .)"
post "$(jq -cn --arg name "$TOOL" --argjson args "$ARGS" \
'{jsonrpc:"2.0",id:2,method:"tools/call",params:{name:$name,arguments:$args}}')"
require_success "tools/call"
CALL="$(response 2)"
if [ -z "$CALL" ]; then echo "tools/call returned no JSON-RPC response:" >&2; printf '%s\n' "$BODY" >&2; exit 1; fi
echo "HTTP status: $STATUS"
if [ "$(printf '%s' "$CALL" | jq 'has("error")')" = "true" ]; then
echo "JSON-RPC error:"; printf '%s' "$CALL" | jq '.error'
elif [ "$(printf '%s' "$CALL" | jq '.result.isError == true')" = "true" ]; then
echo "isError: true"
printf '%s' "$CALL" | jq -r '[.result.content[]? | select(.type == "text") | .text] | join("\n")'
printf '%s' "$CALL" | jq '.result._meta // empty'
else
echo "isError: false (the result was returned)"
printf '%s' "$CALL" | jq -r '[.result.content[]? | select(.type == "text") | .text] | join("\n") | .[0:300]'
echo "..."
fiOn GitHub, open infra/call-tool.sh or infra/call-tool.ps1.
Call an allowed tool
# Make the test script executable, once
chmod +x infra/call-tool.sh &&
echo "๐ infra/call-tool.sh is executable"
# Ask the docs search tool a harmless question: the hook allows the call and the result
echo "๐ง Allowed tool call:"
./infra/call-tool.sh learn_microsoft_docs_search '{"query":"What is Azure Functions Flex Consumption?"}' "$MCP_SERVER"# Ask the docs search tool a harmless question: the hook allows the call and the result
Write-Host "๐ง Allowed tool call:"
./infra/call-tool.ps1 learn_microsoft_docs_search '{"query":"What is Azure Functions Flex Consumption?"}' $MCP_SERVER๐ง Allowed tool call:
tools/call learn_microsoft_docs_search {"query":"What is Azure Functions Flex Consumption?"}
HTTP status: 200
isError: false (the result was returned)
{"results":[{"title":"Azure Functions Flex Consumption plan hosting", โฆ
...Call a blocked tool
# Call the code sample tool, which matches the BLOCKED_TOOLS pattern *code_sample*: the hook denies it before it runs
echo "๐ง Blocked tool call:"
./infra/call-tool.sh learn_microsoft_code_sample_search '{"query":"azure functions python http trigger"}' "$MCP_SERVER"# Call the code sample tool, which matches the BLOCKED_TOOLS pattern *code_sample*: the hook denies it before it runs
Write-Host "๐ง Blocked tool call:"
./infra/call-tool.ps1 learn_microsoft_code_sample_search '{"query":"azure functions python http trigger"}' $MCP_SERVER๐ง Blocked tool call:
tools/call learn_microsoft_code_sample_search {"query":"azure functions python http trigger"}
HTTP status: 200
isError: true
Tool call blocked by a policy before executionSend an email address to a tool
# Put an email address in the arguments of an allowed tool: the hook denies the call before it runs
echo "๐ง Tool call with an email address:"
./infra/call-tool.sh learn_microsoft_docs_search '{"query":"Send the report to megan.bowen@contoso.com"}' "$MCP_SERVER"# Put an email address in the arguments of an allowed tool: the hook denies the call before it runs
Write-Host "๐ง Tool call with an email address:"
./infra/call-tool.ps1 learn_microsoft_docs_search '{"query":"Send the report to megan.bowen@contoso.com"}' $MCP_SERVER๐ง Tool call with an email address:
tools/call learn_microsoft_docs_search {"query":"Send the report to megan.bowen@contoso.com"}
HTTP status: 200
isError: true
Tool call blocked by a policy before executionGet a result that contains a secret
The Azurite storage emulator documents a well-known development account key, so a search for its connection string returns text that looks like a storage account key. The tool runs, and the hook withholds its result. On the Portal track, the policy has only Before tool call, so the result comes back.
# Search for a connection string with an account key: the hook allows the call, then withholds the result
echo "๐ง Tool call whose result contains a key:"
./infra/call-tool.sh learn_microsoft_docs_search '{"query":"Azurite default connection string AccountKey"}' "$MCP_SERVER"# Search for a connection string with an account key: the hook allows the call, then withholds the result
Write-Host "๐ง Tool call whose result contains a key:"
./infra/call-tool.ps1 learn_microsoft_docs_search '{"query":"Azurite default connection string AccountKey"}' $MCP_SERVER๐ง Tool call whose result contains a key:
tools/call learn_microsoft_docs_search {"query":"Azurite default connection string AccountKey"}
HTTP status: 200
isError: true
Tool result blocked by a policy after executionThe harmless search returns results, the code sample tool and the email address are blocked before execution, and the connection string search is blocked after execution. Search results can change; if the last call returns results, they don't contain a key.
Understand verdicts and failures
The gateway answers a denied call the way MCP reports a failed tool: HTTP 200, with isError: true in the
JSON-RPC result. Agents read it as a tool error, not a transport error.
| What happens | Before tool call | After tool call |
|---|---|---|
The service answers allow | The tool runs | The caller gets the result |
The service answers deny | "Tool call blocked by a policy before execution". The tool doesn't run | "Tool result blocked by a policy after execution". The tool already ran |
The service fails: it's stopped, answers 401 or another error, or takes more than about 30 seconds | failClosed: the same as a deny. failOpen: the tool runs | failClosed: the same as a deny. failOpen: the caller gets the result |
The gateway doesn't pass the reason to the caller, and with failClosed a failure looks exactly like a deny. Read
the reason in the decision log, by the gateway's request_id, which is the same for both hooks of one call.
A deny after the call withholds the result, but it can't undo what the tool did. For tools that write, send, or delete, decide before the call, and build agents that don't retry a call whose result was withheld.
Agent hooks complement the gateway's built-in tool controls:
| You need | Use | Lab |
|---|---|---|
| Hide or block tools by name, the same way for every caller | Tool allow and block lists | Lab 05 |
| Microsoft Defender and Microsoft Purview verdicts on prompt injection and sensitive data, for delegated user calls | Agent 365 tool threat protection | Lab 19 |
| Your own rules on tool arguments and results, such as business limits, data that must not leave, or a custom detector | Agent hooks | This lab |
Verify
Read the decision log
The function writes one line for each verdict to Application Insights, which stores it in Log Analytics. Lines arrive two to five minutes after the calls.
# Read the decision service's verdicts of the last hour: tool, decision, reason, request ID, caller, and header
echo "๐ Decisions of the last hour:"
az monitor log-analytics query -w "$HOOK_LOG_WORKSPACE_ID" -o tsv --analytics-query \
"AppTraces | where TimeGenerated > ago(1h) and Message startswith 'agent-hook' | order by TimeGenerated asc | project Message"# Read the decision service's verdicts of the last hour: tool, decision, reason, request ID, caller, and header
Write-Host "๐ Decisions of the last hour:"
az monitor log-analytics query -w $HOOK_LOG_WORKSPACE_ID -o tsv --analytics-query `
"AppTraces | where TimeGenerated > ago(1h) and Message startswith 'agent-hook' | order by TimeGenerated asc | project Message"๐ Decisions of the last hour:
agent-hook point=pre_tool_call tool=learn_microsoft_docs_search decision=allow reason=policy_satisfied request_id=d12fc93f-โฆ caller=2db50daf-โฆ policy=lab30 PrimaryResult
agent-hook point=post_tool_call tool=learn_microsoft_docs_search decision=allow reason=policy_satisfied request_id=d12fc93f-โฆ caller=2db50daf-โฆ policy=lab30 PrimaryResult
agent-hook point=pre_tool_call tool=learn_microsoft_code_sample_search decision=deny reason=blocked_tool:*code_sample* request_id=d8ec2ebf-โฆ caller=2db50daf-โฆ policy=lab30 PrimaryResult
agent-hook point=pre_tool_call tool=learn_microsoft_docs_search decision=deny reason=personal_data:email_address request_id=5760e4b2-โฆ caller=2db50daf-โฆ policy=lab30 PrimaryResult
agent-hook point=pre_tool_call tool=learn_microsoft_docs_search decision=allow reason=policy_satisfied request_id=99895621-โฆ caller=2db50daf-โฆ policy=lab30 PrimaryResult
agent-hook point=post_tool_call tool=learn_microsoft_docs_search decision=deny reason=secret_in_result:storage_account_key request_id=99895621-โฆ caller=2db50daf-โฆ policy=lab30 PrimaryResultcaller is the object ID of the gateway's managed identity, which App Service Authentication validated, and
policy is the header that the policy adds. The portal track has no post_tool_call lines.
See the policy fail closed
Stop the decision service and call the harmless search again. The gateway can't get a verdict, so failClosed
blocks the call. Then start the service again.
# Stop the decision service, so that the gateway can't get a verdict, and give the stop half a minute to apply
az functionapp stop -g "$HOOK_RG" -n "$HOOK_APP" &&
echo "โณ $HOOK_APP is stopping" && sleep 30
# Call the harmless search again: with failClosed, the gateway blocks it
echo "๐ง Allowed tool call while the hook is down:"
./infra/call-tool.sh learn_microsoft_docs_search '{"query":"What is Azure Functions Flex Consumption?"}' "$MCP_SERVER"
# Start the decision service again
az functionapp start -g "$HOOK_RG" -n "$HOOK_APP" &&
echo "๐ $HOOK_APP is running again"# Stop the decision service, so that the gateway can't get a verdict, and give the stop half a minute to apply
az functionapp stop -g $HOOK_RG -n $HOOK_APP
if ($?) { Write-Host "โณ $HOOK_APP is stopping"; Start-Sleep -Seconds 30 }
# Call the harmless search again: with failClosed, the gateway blocks it
Write-Host "๐ง Allowed tool call while the hook is down:"
./infra/call-tool.ps1 learn_microsoft_docs_search '{"query":"What is Azure Functions Flex Consumption?"}' $MCP_SERVER
# Start the decision service again
az functionapp start -g $HOOK_RG -n $HOOK_APP
if ($?) { Write-Host "๐ $HOOK_APP is running again" }โณ <hook-app> is stopping
๐ง Allowed tool call while the hook is down:
tools/call learn_microsoft_docs_search {"query":"What is Azure Functions Flex Consumption?"}
HTTP status: 200
isError: true
Tool call blocked by a policy before execution
๐ <hook-app> is running againThe decision log has an allow or a deny with a reason for each call, and the harmless search is blocked while
the decision service is stopped. The log has no line for that call, because the function never ran.
Go further
- Fail open for low-risk servers. Set
modetofailOpenso that tool calls continue when the service is down, or override it for one point, such as"postToolCall": {"mode": "failOpen"}. On the Bicep + azd track, runazd env set HOOK_MODE failOpenandazd provision. On the Terraform track, runterraform plan -var hook_mode=failOpen -out tfplanandterraform apply tfplanin theterraformfolder. Then repeat the stop test: the search returns results, and so does the code sample search that the service blocks. Fail open lets every call through while the service is down. - Change the rules without a deployment. The blocked tool patterns are an app setting:
az functionapp config appsettings set -g "$HOOK_RG" -n "$HOOK_APP" --settings "BLOCKED_TOOLS=*code_sample*,*fetch*". - Use a key instead of an identity. The product's
pre-tool call hook guide uses a
function key in an
x-functions-keyheader, with API key authentication. The policy stores the key, and the portal asks for it again whenever the server's policies change. A managed identity keeps secrets out of the policy. - Use another identity. Set
managedIdentity.clientIdto the client ID of a user-assigned identity on the gateway, and allow that identity's object ID in App Service Authentication. - Call your own rules engine. The service can call anything that decides quickly: a ticket system that checks for an approved change, a data loss prevention API, or a model that classifies the arguments.
Clean up
Delete the policy
In the AI Gateway portal, select Policies. On the Before tool calls row of type Agent hooks, select More actions (โฏ) โบ Delete. In Delete this policy?, select Delete. Tool calls on the server no longer wait for the hook.
Delete the decision service
The Azure CLI steps of Deploy the decision service created a resource group and an app registration. Delete them with the Azure CLI track's last three commands below.
Remove the policy and the decision service
# Remove the agent hooks policy from the MCP server, and keep its other policies
POLICIES="$(az aigateway mcp show -g "$RG" --gateway-name "$GATEWAY" -n "$MCP_SERVER" -o json |
jq -c '[(.properties.policies // [])[] | select(.type != "agentHooks")]')"
az aigateway mcp update -g "$RG" --gateway-name "$GATEWAY" -n "$MCP_SERVER" --policies "$POLICIES" -o none &&
echo "๐ฎ The agent hooks policy is removed from the $MCP_SERVER MCP server"
# Delete the decision service's resource group: the function app, its network, storage, and logs
az group delete -n "$HOOK_RG" --yes --no-wait &&
echo "โณ Resource group $HOOK_RG is being deleted"
# Read the app registration's object ID, which the purge needs, then delete the app registration
HOOK_OBJECT_ID="$(az ad app show --id "$HOOK_CLIENT_ID" --query id -o tsv)" &&
az ad app delete --id "$HOOK_CLIENT_ID" &&
echo "๐ฎ App registration $HOOK_CLIENT_ID is deleted"
# Purge the app registration from the deleted items
az rest --method delete --url "https://graph.microsoft.com/v1.0/directory/deletedItems/$HOOK_OBJECT_ID" &&
echo "๐ฎ App registration $HOOK_OBJECT_ID is purged"# Remove the agent hooks policy from the MCP server, and keep its other policies
$current = az aigateway mcp show -g $RG --gateway-name $GATEWAY -n $MCP_SERVER -o json | ConvertFrom-Json
$policies = @($current.properties.policies | Where-Object { $_ -and $_.type -ne 'agentHooks' })
ConvertTo-Json -InputObject $policies -Depth 10 -Compress | Set-Content -Path policies.json
az aigateway mcp update -g $RG --gateway-name $GATEWAY -n $MCP_SERVER --policies '@policies.json' -o none
if ($?) { Write-Host "๐ฎ The agent hooks policy is removed from the $MCP_SERVER MCP server" }
Remove-Item policies.json
# Delete the decision service's resource group: the function app, its network, storage, and logs
az group delete -n $HOOK_RG --yes --no-wait
if ($?) { Write-Host "โณ Resource group $HOOK_RG is being deleted" }
# Read the app registration's object ID, which the purge needs, then delete the app registration
$HOOK_OBJECT_ID = az ad app show --id $HOOK_CLIENT_ID --query id -o tsv
az ad app delete --id $HOOK_CLIENT_ID
if ($?) { Write-Host "๐ฎ App registration $HOOK_CLIENT_ID is deleted" }
# Purge the app registration from the deleted items
az rest --method delete --url "https://graph.microsoft.com/v1.0/directory/deletedItems/$HOOK_OBJECT_ID"
if ($?) { Write-Host "๐ฎ App registration $HOOK_OBJECT_ID is purged" }Delete everything azd created
In the aigateway/labs/30-agent-hooks folder, delete the resource group with the gateway, the learn MCP server,
the decision service, and the key. Before that, the predown hook deletes the app registration and purges it.
--purge also purges soft-deleted resources. It takes about ten minutes.
# Delete everything that azd up created, and purge the soft-deleted resources
azd down --purge --force &&
echo "๐ฎ Everything that azd up created is deleted"Delete everything Terraform created
In the lab's Terraform folder, delete the app registration and the resource group with the gateway, the learn MCP
server, the decision service, and the key. Microsoft Entra ID keeps a deleted app registration in its deleted items
for 30 days, so purge it too, like azd down does. Read its object ID first, because terraform destroy removes the
outputs. It takes about four minutes.
# Move into the lab's Terraform folder
cd ~/aigateway/labs/30-agent-hooks/terraform &&
echo "๐ Terraform folder: $(pwd)"
# Read the app registration's object ID, which the purge needs after terraform destroy
HOOK_OBJECT_ID="$(terraform output -raw hook_object_id)" &&
echo "๐ App registration: $HOOK_OBJECT_ID"
# Delete everything that terraform apply created, including the app registration
terraform destroy -auto-approve &&
echo "๐ฎ Everything that terraform apply created is deleted"
# Purge the app registration from the deleted items
az rest --method delete --url "https://graph.microsoft.com/v1.0/directory/deletedItems/$HOOK_OBJECT_ID" &&
echo "๐ฎ App registration $HOOK_OBJECT_ID is purged"# Move into the lab's Terraform folder
Set-Location ~/aigateway/labs/30-agent-hooks/terraform
if ($?) { Write-Host "๐ Terraform folder: $(Get-Location)" }
# Read the app registration's object ID, which the purge needs after terraform destroy
$HOOK_OBJECT_ID = terraform output -raw hook_object_id
if ($?) { Write-Host "๐ App registration: $HOOK_OBJECT_ID" }
# Delete everything that terraform apply created, including the app registration
terraform destroy -auto-approve
if ($?) { Write-Host "๐ฎ Everything that terraform apply created is deleted" }
# Purge the app registration from the deleted items
az rest --method delete --url "https://graph.microsoft.com/v1.0/directory/deletedItems/$HOOK_OBJECT_ID"
if ($?) { Write-Host "๐ฎ App registration $HOOK_OBJECT_ID is purged" }Keep the gateway and the learn MCP server from lab 04: the next labs reuse them. azd down and
terraform destroy don't touch them, because the Bicep + azd and Terraform tracks created their own gateways.