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.
This reference covers the standalone named-policy flow. Use ARM to manage policies and Rego, and the account's data-plane endpoint to evaluate them.
Prerequisites
Complete the quickstart for preview access, a serving account, and authoring and runtime permissions. The management examples use its resource variables and the scripts listed in the sample guide. Run the examples from the directory containing the management scripts.
Endpoints and versions
| Purpose | Endpoint | Version |
|---|---|---|
| Account and policy management | https://management.azure.com |
2026-11-15-preview |
| Evaluation | The serving Content Safety account's endpoint | 2026-09-01-preview |
The policy resources are:
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}
/providers/Microsoft.CognitiveServices/accounts/{accountName}
/raiRegos/{regoName}
/raiPolicies/{policyName}
The line breaks above are for readability. Each request uses a single resource path.
Create reusable Rego before the policy that references it. A Rego PUT body contains properties.encoding and properties.rego.
None means plain source; the contract also defines Base64. The examples use plain UTF-8 source.
A policy PUT body contains properties.format: "ACS", properties.acs, and properties.acsRegos. The inner manifest version is 0.4.0-alpha.1, not either API version.
Authentication and authorization
| Call | OAuth scope | Access |
|---|---|---|
| ARM | https://management.azure.com/.default |
Resource-management actions required for the account and child resources. |
| Unified Moderate | https://cognitiveservices.azure.com/.default |
Cognitive Services User on the serving account, with preview access enabled. |
| Customer-owned judge inference | The supported model service audience, acquired by the service | Inference permission for the serving account identity on the model account. |
Use a custom-subdomain endpoint for Microsoft Entra authentication. Do not interchange ARM and data-plane tokens.
The data-plane contract also declares Ocp-Apim-Subscription-Key authentication, subject to the account's local-authentication and preview configuration. These guides use Entra credentials and recommend managed identities for applications. A subscription key is not a separate application identity.
Agent IDs, actor metadata, session IDs, and customer-provided identity claims in JSON are not authorization.
Use a managed identity in production
The quickstart uses an interactive developer identity. For an application, use a managed identity attached to its compute:
- Create or enable the identity on the application host.
- Grant its principal
Cognitive Services Useron the serving Content Safety account. - Configure the application's credential to select that identity and obtain a token for
https://cognitiveservices.azure.com/.default. - Verify that an authorized request succeeds and an unauthorized identity is rejected.
For a user-assigned identity, role assignments use its principal ID and principal type ServicePrincipal. Credential selection uses its client ID. Creating the identity without attaching it to the application host does not make it available to the application.
The application's identity is separate from the serving account identity used by a customer-owned LLM judge.
Call Unified Moderate
This HTTP request is schematic. Replace {endpoint} with your Content Safety account's endpoint:
POST {endpoint}/contentsafety/content:unifiedModerate?api-version=2026-09-01-preview
Authorization: Bearer <access-token>
Content-Type: application/json
Put policyId in the JSON body, not the query string. Use the published policy's name under the serving account, such as refund-quickstart. The management examples continue to use full ARM IDs.
No resource binding or additional resource selector is required for this named-policy flow. Don't send both policyId and targetResourceId.
Request body
This example evaluates tool arguments before dispatch:
{
"policyId": "refund-quickstart",
"source": "pre_tool_call",
"toolName": "refund_order",
"toolCallId": "refund-1",
"content": "{\"order_id\":\"demo-001\",\"amount\":100}",
"context": {
"agentId": "support-agent",
"sessionId": "sample-tool",
"sequence": 2
}
}
For actual execution, use your session's ID, increasing sequence number, and the exact action your host is about to perform.
source |
content |
Tool fields |
|---|---|---|
input |
Nonempty plain text. | Don't send tool fields. |
output |
Nonempty plain text. | Don't send tool fields. |
pre_tool_call |
A JSON-encoded object string containing the proposed arguments. | toolName is required; toolCallId is optional. |
post_tool_call |
A JSON-encoded result string; don't use JSON null. |
toolName is required. Optional: toolCallId, toolArguments (a JSON-encoded object string), toolResultIsError (boolean), and toolDurationMs (finite, non-negative number). |
Preserve numbers, booleans, arrays, objects, and permitted null members inside JSON-encoded tool values. For example, amount above is a number after decoding content, not a string.
Optional context fields are agentId, sessionId, sequence (non-negative integer), correlationId, userId, tenantId, and extensions (a JSON-encoded object string). The service builds the snapshot used by manifest target paths. Populate context with these supported fields.
Limits
Keep content and toolArguments within about 10,000 characters each. toolName, toolCallId, and the context string fields (agentId, sessionId, correlationId, userId, and tenantId) are limited to 256 characters each. Context extensions is limited to 16 KiB of UTF-8 JSON and depth 16.
A supported HTTP payload size does not guarantee that a particular classifier or model can inspect that amount of content. Required capabilities have their own input and execution limits.
ARM authoring limits
Stored policy artifacts have separate limits from the runtime context:
| Item | Limit on enabled preview accounts | Measurement |
|---|---|---|
| ACS manifest | 256 KiB (262,144 bytes) | Compact serialized UTF-8 JSON for properties.acs. |
| Rego resource | 512 KiB (524,288 bytes) | Decoded UTF-8 source, including when uploaded with encoding: "Base64". |
| Complete ARM PUT body | 1 MiB (1,048,576 bytes) | The entire request body, including JSON wrappers and encoded source. |
These limits depend on the preview deployment. Some deployments enforce 48 KiB manifests and 200 KiB decoded Rego. Confirm the limits enabled for your account before relying on the larger caps.
Both artifact and whole-request limits apply. Base64 expands the transported source, and plain-source JSON escaping also contributes to body size. A request smaller than 1 MiB can still exceed the manifest or decoded-Rego limit.
Interpret the response
A successful response contains:
| Member | Meaning |
|---|---|
verdict |
allowed or blocked. |
reason |
Optional reason code. |
content |
Original or transformed content when allowed; omitted when blocked. Structured values remain JSON-encoded strings. |
acsVerdict |
Decision details: decision (allow, deny, or transform), optional reason, message, warnings, approval, transform, evidence, and harmResults. |
HTTP 200 means evaluation completed. It does not mean the action is allowed.
For example, a deny response includes:
{
"verdict": "blocked",
"reason": "tool_request_not_permitted",
"acsVerdict": {
"decision": "deny",
"reason": "tool_request_not_permitted",
"message": "Use approved tools. Refund amounts must be numeric: >0 and <=100."
}
}
The host must:
- Validate the response and associate it with the exact pending request.
- Stop on
blocked,deny, malformed or inconsistent data, or operational failure. - For
allowedwithallow, use the evaluated value. Forallowedwithtransform, use and validate the returnedcontent. - Execute or release only the evaluated, permitted value.
- Record what actually happened.
The service already applies a transform; don't apply acsVerdict.transform a second time. For input/output, the returned content is plain text. For tool sources, parse it as the replacement JSON tool value. Validate the replacement against your application's schema before use. The judge path in these guides does not support transform verdicts. If your application cannot safely handle a transformation or approval workflow, keep the action blocked.
Approval requests
A review decision is a deny until your host resolves it. For example, this Rego verdict produces blocked with acsVerdict.approval.type:
{
"decision": "deny",
"reason": "human_review_required",
"approval": {
"type": "transaction-review"
}
}
The approval object's contents must match a workflow your application implements; this example does not provision one. Bind any approval to the exact action and evaluated values. Do not treat the presence of approval as permission to execute, and do not let an approval override an independent unconditional deny.
The approval field does not open a review queue or grant permission.
Handle errors
| HTTP status or condition | Action |
|---|---|
400, BadRequest |
Correct malformed JSON or a field type, such as an object instead of a string for content. |
400, InvalidRequestBody |
Correct the source-specific fields, selector, unsupported profile, or size. The selected policy must bind the requested source. A missing body selector can report that targetResourceId is required; set policyId for this named-policy flow. |
401 |
Check credential acquisition, token audience, and expiration. |
403 |
Check the selected caller's data-plane role, account scope, preview access, and policy authorization. |
404 |
Check endpoint, API version, account, and region enablement. |
429 |
Honor Retry-After when supplied and reduce load. Keep the action blocked. |
500, 503, transport error, or timeout |
Keep the action blocked. Retry only within a bounded application deadline. |
200 with blocked / acsVerdict.decision: deny |
A policy outcome, not a transport failure. Do not retry until it becomes an allow. |
| Invalid or inconsistent verdict | Do not act. Record the failure and investigate. |
Operational error codes can differ between serving configurations. Preserve the actual returned code, HTTP status, and request correlation information without logging sensitive payloads. An unavailable required capability or dependency isn't permission to skip its check.
Retries and quotas
A single evaluation can invoke multiple required detectors or judges. Account limits and model-deployment limits are separate; an evaluation's HTTP request count does not establish its internal detector or inference usage.
Use the quotas assigned to your enabled account and model deployment when setting concurrency. Do not assume a universal requests-per-second limit from this guide.
An evaluation retry is not permission to retry a non-idempotent tool action. Keep the original action pending, bound retries by time and count, and prevent duplicate dispatch. Do not reuse a previous allow for changed arguments, changed output, a different lifecycle point, or a later action.
Update and roll out policies
Publish new named policy versions for a staged rollout. Use conditional replacement only when you intentionally update an existing resource.
Prefer a new named version
Create a new policy and Rego resource with a new name, test it, and deliberately change the application's configured selector. For example, use publish-policy.ps1:
$Candidate = .\publish-policy.ps1 -AccountId $AccountId `
-TemplateDirectory .\refund-guard -PolicyName 'refund-guard-v2'
Keep the previous version available during rollout. Moving the selector back is a configuration rollback; it does not undo actions already executed.
Conditional in-place replacement
If you intentionally replace a policy, GET its current ETag and use If-Match. The following example uses arm.ps1:
. .\arm.ps1
$Current = Invoke-AgentControlArm -Method GET -ResourceId $PolicyId
if (-not $Current.ETag) { throw 'The current policy has no ETag.' }
$Replacement = Get-Content .\refund-guard\policy.json -Raw |
ConvertFrom-Json -AsHashtable
# Preserve or deliberately change the same-account Rego references.
$Replacement.properties.acsRegos[0].regoName = '<intended-existing-Rego-name>'
$Updated = Invoke-AgentControlArm -Method PUT -ResourceId $PolicyId `
-Headers @{ 'If-Match' = $Current.ETag } -Body $Replacement
Use an accepted request body, not the complete GET response with read-only fields. A precondition failure requires review and reconciliation; do not retry an unconditional overwrite.
Changes to reusable Rego can affect policies that reference it. Publishing new named source and policy resources avoids treating multi-resource updates as an atomic operation.
Named-policy calls select the authorized policy by name in policyId; the request format shown here does not pin an ETag. Use distinct named versions for deliberate rollout, and retain the ARM ETag with your deployment records.
Monitor evaluation and enforcement
Record:
- Session, action, source, and caller-supplied correlation IDs.
- Configured policy names and deployment ETags.
- Decision and reason, including unresolved approvals.
- Service latency, timeouts, failures, and throttling.
- Whether the action was blocked, dispatched, transformed, or released.
A useful host assertion is zero protected dispatches or releases after deny/error. Check point coverage as well; perfect response handling does not protect an action that never called the service.
Avoid raw prompts, tool arguments, model output, access tokens, and judge rubrics in routine logs. Correlation metadata does not replace a data-handling policy.
Delete a policy and its Rego
- Stop or reconfigure clients using the policy.
- Check for other references to its reusable Rego.
- Delete the policy with its current ETag.
- If deletion is asynchronous, wait for the ARM operation to succeed.
- Delete Rego only after it is no longer referenced.
For resources created by the publishing script:
.\remove-policy.ps1 -PolicyId $Published.PolicyId -RegoId $Published.RegoId
The remove-policy.ps1 script checks that both IDs belong to the same account, uses ETags, waits for asynchronous operations, and deletes only those two resources. A conflict or failed deletion is an error; it does not proceed by force.
The script does not delete the serving account, model account, role assignments, or resource group. Review and remove unused resources separately.