Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
In this quickstart, you use the Agent Controls REST APIs to create a policy through Azure Resource Manager (ARM). Then you evaluate a proposed tool call with Unified Moderate.
The policy permits refunds greater than zero and no greater than 100. Submit a refund of 75 to see an allowed result. Then submit a refund of 150 to see a denied result.
These API calls evaluate the proposed refunds. They don't execute a tool or issue a refund.
For an introduction to policies and intervention points, see What are Agent Controls?
If you don't have an Azure subscription, create one for free.
Prerequisites
- An Azure subscription.
- An Azure AI Content Safety resource enabled for the Agent Controls preview. If you need a resource, create a Content Safety resource in a region enabled for your preview access. Resource creation alone doesn't enable Agent Controls.
- Permission to create policy and Rego resources under that account, such as
Contributorat the account's scope. - The
Cognitive Services Userrole on the account for runtime calls. The setup section shows how an administrator can grant this role. Creating role assignments requires additional permission, such as Role Based Access Control Administrator. - Azure CLI, cURL 7.76 or later, and PowerShell 7 or later.
This walkthrough uses Microsoft Entra authentication and the account's custom-subdomain endpoint. It doesn't require an SDK, Node.js, or OPA.
Note
This example uses ARM API version 2026-11-15-preview, Unified Moderate API version 2026-10-15-preview, and ACS manifest version 0.4.0-alpha.1. Your account and region must support these versions.
Set up your resource and access
Open PowerShell in a working directory for the request files below. Run the commands in the same session.
Sign in and select the subscription that contains your Content Safety resource:
$ErrorActionPreference = 'Stop'
$SubscriptionId = '<subscription-guid>'
$ResourceGroup = '<resource-group-name>'
$AccountName = '<content-safety-account-name>'
az login
if ($LASTEXITCODE -ne 0) { throw 'Azure sign-in failed.' }
az account set --subscription $SubscriptionId
if ($LASTEXITCODE -ne 0) { throw 'Unable to select the subscription.' }
$AccountJson = az cognitiveservices account show `
--resource-group $ResourceGroup --name $AccountName --output json
if ($LASTEXITCODE -ne 0) { throw 'Unable to read the Content Safety resource.' }
$Account = ($AccountJson -join "`n") | ConvertFrom-Json
$AccountId = $Account.id
$Endpoint = $Account.properties.endpoint
if (-not $AccountId -or [string]::IsNullOrWhiteSpace($Endpoint)) {
throw 'The resource did not return an ID and endpoint.'
}
$Endpoint = $Endpoint.TrimEnd('/')
$ArmApiVersion = '2026-11-15-preview'
$DataApiVersion = '2026-10-15-preview'
$RegoId = "$AccountId/raiRegos/refund-quickstart"
$PolicyId = "$AccountId/raiPolicies/refund-quickstart"
If your signed-in user doesn't already have Cognitive Services User on the account, an administrator with role-assignment permission can run:
$CallerId = az ad signed-in-user show --query id --output tsv
if ($LASTEXITCODE -ne 0 -or -not $CallerId) {
throw 'Unable to resolve the signed-in user.'
}
az role assignment create `
--assignee-object-id $CallerId `
--assignee-principal-type User `
--role 'Cognitive Services User' `
--scope $AccountId `
--output none
if ($LASTEXITCODE -ne 0) { throw 'Unable to grant data-plane access.' }
The assignment applies to the signed-in user. An administrator assigning access to someone else must use that person's object ID instead. Allow time for role assignments to propagate.
Get an ARM access token for creating the resources:
$ArmToken = az account get-access-token `
--resource 'https://management.azure.com/' `
--query accessToken --output tsv
if ($LASTEXITCODE -ne 0 -or -not $ArmToken) {
throw 'Unable to obtain an ARM access token.'
}
ARM and Unified Moderate use different token audiences. You get the runtime token later in this walkthrough.
Create a Rego resource
Rego defines the refund rule. Save the following code as refund.rego:
package refund_guard
import rego.v1
default verdict := {"decision": "deny", "reason": "refund_not_permitted"}
verdict := {"decision": "allow"} if {
input.intervention_point == "pre_tool_call"
input.snapshot.tool_call.name == "refund_order"
amount := input.policy_target.value.amount
is_number(amount)
amount > 0
amount <= 100
}
This rule denies by default. It allows only a refund_order call with a numeric amount in the permitted range.
Create the ARM request body from the source file:
$RegoBody = @{
properties = @{
encoding = 'None'
rego = Get-Content -LiteralPath .\refund.rego -Raw
}
}
$RegoBody | ConvertTo-Json -Depth 10 |
Set-Content -LiteralPath .\rego-request.json -Encoding utf8
The rego property contains the source text. encoding: "None" means the source isn't Base64-encoded.
Upload it with an ARM PUT request:
curl.exe --request PUT `
--url "https://management.azure.com${RegoId}?api-version=$ArmApiVersion" `
--header "Authorization: Bearer $ArmToken" `
--header 'Content-Type: application/json' `
--header 'If-None-Match: *' `
--data-binary '@rego-request.json' `
--include --fail-with-body --silent --show-error --max-time 60
if ($LASTEXITCODE -ne 0) {
throw 'Rego creation failed. Check the preceding response.'
}
A successful PUT returns HTTP 200 or 201 and an ETag. If-None-Match: * prevents this request from replacing an existing resource. If refund-quickstart already exists, use a new resource name or follow the policy update guidance.
Create the policy
The policy manifest connects the pre_tool_call intervention point to the Rego rule and selects the tool arguments for evaluation.
Save this complete ARM request body as policy.json:
{
"properties": {
"format": "ACS",
"acs": {
"agent_control_specification_version": "0.4.0-alpha.1",
"policies": {
"refund-guard": {
"type": "rego",
"query": "data.refund_guard.verdict"
}
},
"intervention_points": {
"pre_tool_call": {
"policy_target": "$snap.tool_call.args",
"policy_target_kind": "tool_args",
"tool_name_from": "$snap.tool_call.name",
"policy": { "id": "refund-guard" }
}
},
"tools": {
"refund_order": {
"type": "write",
"description": "Issue a refund."
}
}
},
"acsRegos": [{ "regoName": "refund-quickstart" }]
}
}
| Property | Purpose |
|---|---|
format |
Selects the ACS policy format. |
query |
Identifies the verdict rule in the refund_guard Rego package. |
pre_tool_call |
Applies the rule before the host dispatches a tool call. |
policy_target |
Selects the submitted tool arguments. |
tool_name_from |
Selects the tool's entry in the manifest's tool catalog. |
acsRegos |
Loads the Rego resource created in the previous step. |
If you changed the Rego resource name, update acsRegos[0].regoName to match.
Create the policy with an ARM PUT request:
curl.exe --request PUT `
--url "https://management.azure.com${PolicyId}?api-version=$ArmApiVersion" `
--header "Authorization: Bearer $ArmToken" `
--header 'Content-Type: application/json' `
--header 'If-None-Match: *' `
--data-binary '@policy.json' `
--include --fail-with-body --silent --show-error --max-time 60
if ($LASTEXITCODE -ne 0) {
throw 'Policy creation failed. Check the preceding response.'
}
A successful PUT returns HTTP 200 or 201. The policy is stored under the Content Safety account and references Rego from that same account.
Evaluate a proposed tool call
Get a Content Safety access token and URL-encode the policy resource ID:
$DataToken = az account get-access-token `
--scope 'https://cognitiveservices.azure.com/.default' `
--query accessToken --output tsv
if ($LASTEXITCODE -ne 0 -or -not $DataToken) {
throw 'Unable to obtain a Content Safety access token.'
}
$EncodedPolicyId = [Uri]::EscapeDataString($PolicyId)
$ModerateUrl = "$Endpoint/contentsafety/content:unifiedModerate"
$ModerateUrl += "?api-version=$DataApiVersion"
$ModerateUrl += "&policyId=$EncodedPolicyId"
Save the following request as tool-call.json:
{
"spec": "agent-hooks/0.1",
"interception_point": "pre_tool_call",
"timestamp": "2026-11-06T12:00:00Z",
"sequence": 0,
"agent": { "id": "support-agent", "framework": "custom" },
"session": { "id": "refund-example" },
"tool_call": {
"id": "refund-1",
"name": "refund_order",
"args": { "order_id": "demo-001", "amount": 75 }
},
"target": { "order_id": "demo-001", "amount": 75 }
}
| Field | Purpose |
|---|---|
spec |
Identifies the Agent Hooks context format. |
interception_point |
Selects the lifecycle point to evaluate. |
timestamp, sequence |
Record the event time and order within the session. |
agent, session |
Identify the agent and run for correlation. They don't grant access. |
tool_call |
Describes the proposed tool name and arguments. |
target |
Contains the arguments selected for evaluation. At this point it must equal tool_call.args. |
The fixed timestamp and identifiers make this example easy to reproduce. In an application, construct them for the actual event. Keep arguments as native JSON, including the numeric amount.
Submit the request:
curl.exe --request POST `
--url $ModerateUrl `
--header "Authorization: Bearer $DataToken" `
--header 'Content-Type: application/json' `
--data-binary '@tool-call.json' `
--fail-with-body --silent --show-error --max-time 30
if ($LASTEXITCODE -ne 0) {
throw 'Policy evaluation failed. Check the preceding response.'
}
The policyId query parameter selects the policy you created through ARM. The body describes the proposed tool call. It doesn't contain a policy selector.
Interpret the response
Unified Moderate returns a verdict and a receipt. For a refund of 75, the rule's verdict is:
{
"decision": "allow"
}
This is the verdict portion of the response, not the complete response. Additional applicable policies can affect the final decision.
| Response field | Meaning |
|---|---|
verdict.decision |
The decision the host must enforce. This rule returns allow or deny. |
verdict.reason |
A reason code, when the rule provides one. |
receipt.evaluationId |
Identifies this evaluation for correlation with application records. |
receipt.evaluatedInterventionPoint |
The point evaluated, here pre_tool_call. |
receipt.evaluatedPolicyLayers |
Identifies the policies and versions evaluated. |
receipt.requestBinding |
Binds the receipt to the request and policy selector. |
HTTP 200 means evaluation completed. Check verdict.decision to determine whether the call is permitted.
Try a refund above the limit
Change both copies of the amount to 150, then submit a new event:
$Request = Get-Content -LiteralPath .\tool-call.json -Raw |
ConvertFrom-Json -AsHashtable
$Request.tool_call.args.amount = 150
$Request.target.amount = 150
$Request.tool_call.id = 'refund-2'
$Request.sequence = 1
$Request.timestamp = [DateTime]::UtcNow.ToString('o')
$Request | ConvertTo-Json -Depth 10 |
Set-Content -LiteralPath .\tool-call.json -Encoding utf8
curl.exe --request POST `
--url $ModerateUrl `
--header "Authorization: Bearer $DataToken" `
--header 'Content-Type: application/json' `
--data-binary '@tool-call.json' `
--fail-with-body --silent --show-error --max-time 30
if ($LASTEXITCODE -ne 0) {
throw 'Policy evaluation failed. Check the preceding response.'
}
The response still uses HTTP 200, but the rule returns this verdict:
{
"decision": "deny",
"reason": "refund_not_permitted"
}
In an application, the host checks the verdict and receipt before dispatching the tool. A denied or failed evaluation keeps the call blocked.
For an allowed call, the host executes the evaluated arguments. See Interpret the response for receipt checks and transform handling.
Connect evaluation to your agent
Add the check in the code that dispatches the tool, before the tool executes. Capture the proposed arguments once and use that same value for both evaluation and dispatch. The following code is pseudocode, not a supplied SDK API:
context = capturePreToolContext(proposedCall)
response = evaluate(policyId, context, boundedDeadline)
validateResponseAndReceipt(response, context, policyId, servingAccountId)
if response.verdict.decision != "allow":
block the call
else:
validate the captured arguments against the tool's schema
authorize the caller using trusted application state
dispatch the registered tool with the captured arguments
An evaluation or receipt-validation failure must stop dispatch. Receipt validation checks the exact request binding, selected policy, intervention point, and expected serving-account producer. For more information, see Receipt fields. The host must also implement every point required by the returned policy set.
This minimal gate blocks transforms and approval-bearing denies. Add those behaviors only when your host implements their validation and approval contracts. Don't retry a non-idempotent tool action merely because evaluation was retried.
For generated output, evaluate the complete content before releasing it. If the model streams, buffer the output within an application limit, submit the completed output for evaluation, then release only the permitted content. Stop on overflow or failure.
Sending tokens to the user before the check finishes can't be undone by a later deny. This REST walkthrough doesn't implement a per-chunk streaming-release protocol.
Clean up resources
After you finish, delete the refund-quickstart policy and then its Rego resource if they're no longer needed. To delete the policy and Rego resource with ETag protection and handle asynchronous operations, see Delete a policy and its Rego.
Delete the account separately only if you created it for this exercise and no other application needs it.
Next steps
- Author policies to add your own rules and Content Safety classifiers.
- Configure an LLM judge to evaluate content against a written rubric.
- Choose a policy template for other scenarios.
- Use a managed identity in production instead of an interactive developer identity.
- For optional client examples that help integrate evaluation and receipt checks into your application, see the HTTP client sample.