Agent Controls API and operations (preview)

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-10-15-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:

  1. Create or enable the identity on the application host.
  2. Grant its principal Cognitive Services User on the serving Content Safety account.
  3. Configure the application's credential to select that identity and obtain a token for https://cognitiveservices.azure.com/.default.
  4. 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. {unified-moderate-url} includes your endpoint, /contentsafety/content:unifiedModerate, api-version=2026-10-15-preview, and the full ARM policyId, URL-encoded once.

POST {unified-moderate-url}
Authorization: Bearer <access-token>
Content-Type: application/json

Use the full ARM policy resource ID under the serving account as policyId. Where a deployment supports short policy names, the full ID is still the clearer selector. URL-encode it once using an HTTP query builder; do not manually concatenate unescaped IDs.

The standalone selector is a query parameter. No resource binding or additional resource selector is required.

Request body

This example evaluates tool arguments before dispatch:

{
  "spec": "agent-hooks/0.1",
  "interception_point": "pre_tool_call",
  "timestamp": "2026-11-04T12:00:00Z",
  "sequence": 2,
  "agent": { "id": "support-agent", "framework": "custom" },
  "session": { "id": "sample-tool" },
  "tool_call": {
    "id": "refund-1",
    "name": "refund_order",
    "args": { "order_id": "demo-001", "amount": 100 }
  },
  "target": { "order_id": "demo-001", "amount": 100 }
}

For actual execution, use a current timestamp, your session's ID and increasing sequence number, and the exact action your host is about to perform. The service validates the point-specific payload and target equality.

Keep values as native JSON. A tool argument object must not be encoded as a JSON string. Preserve numbers, booleans, arrays, objects, and null where the contract permits them.

The target mapping is listed in Author policies. SDK context builders help keep these fields consistent.

Limits

Requests and responses are each limited to 1,048,576 decoded UTF-8 JSON bytes and container depth 64, including the root. Use valid Unicode and unambiguous JSON member names. Duplicate members, conflicting selectors, and over-limit requests are errors, not truncated successful evaluations.

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 The aggregate allow, deny, or transform decision.
receipt Metadata identifying the evaluation and exact evaluated request and policies.

HTTP 200 means evaluation completed. It does not mean the action is allowed.

For example, the verdict member can be:

{
  "decision": "deny",
  "reason": "tool_request_not_permitted",
  "message": "Use approved tools. Refund amounts must be numeric: >0 and <=100."
}

The host must:

  1. Validate the response and receipt.
  2. Stop on deny, malformed data, or operational failure.
  3. Apply and validate a supported transform before using its replacement value.
  4. Execute or release only the evaluated, permitted value.
  5. Record what actually happened.

Startup and shutdown transforms are unsupported. The judge path in these guides also does not support transform verdicts. If your application cannot implement a returned transformation or approval workflow safely, keep the action blocked.

Approval requests

A review decision is a deny until your host resolves it. A policy can return, for example:

{
  "decision": "deny",
  "reason": "human_review_required",
  "approval": {
    "workflow": "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.

Receipt fields

Field Host check or use
receiptVersion Match the transport contract, here 2026-10-15-preview.
profile Expect namedPolicy for this flow.
evaluationId, attempt Correlate service evaluation and host execution records.
requestBinding Require algorithm: "sha256" and canonicalization: "rfc8785", then compare digest with the hash of the exact request material below.
evaluatedPolicyLayers Verify the expected named policy; retain its revision, semantic digest, activated artifact digest, and decision.
evaluatedInterventionPoint Match the point sent in this request.
requiredInterventionPoints Check that your host implements every required point. This does not prove that the host called them.
hostProfileVersion Record the service evaluation profile.
authenticatedProducerResourceId For this namedPolicy flow, match the serving account ID from trusted configuration, not a value copied from the response.
harmResults, when present Public classifier summaries, not the Rego input or complete internal model diagnostics.

For example, a complete named-policy deny response has this shape. The resource IDs, revision, evaluation ID, and digests are illustrative placeholders, not values to copy into a validator. Real policyResourceId and authenticatedProducerResourceId values are full ARM IDs for the policy and serving account, respectively:

{
  "verdict": { "decision": "deny", "reason": "refund_not_permitted" },
  "receipt": {
    "receiptVersion": "2026-10-15-preview",
    "profile": "namedPolicy",
    "evaluationId": "evaluation-<unique-id>",
    "attempt": 1,
    "requestBinding": {
      "algorithm": "sha256",
      "canonicalization": "rfc8785",
      "digest": "sha256:<request-digest>"
    },
    "evaluatedPolicyLayers": [
      {
        "kind": "namedPolicy",
        "policyResourceId": "<full-policy-resource-id>",
        "policyRevision": "<policy-revision>",
        "policySemanticDigest": "sha256:<semantic-digest>",
        "manifestRegoDigest": "sha256:<artifact-digest>",
        "decision": "deny"
      }
    ],
    "evaluatedInterventionPoint": "pre_tool_call",
    "requiredInterventionPoints": ["pre_tool_call"],
    "hostProfileVersion": "<host-profile-version>",
    "authenticatedProducerResourceId": "<serving-account-resource-id>"
  }
}

Each real digest contains sha256: followed by 64 lowercase hexadecimal characters. evaluatedPolicyLayers can contain additional applicable layers; do not assume there is always exactly one. Verify the selected named policy is present, preserve the other layers, and enforce the aggregate verdict rather than an individual layer's allow.

The request-binding digest is the SHA-256 hash of RFC 8785 canonical UTF-8 JSON for:

{
  "apiVersion": <the exact Unified Moderate API version>,
  "context": <the exact decoded request body>,
  "selectors": { "policyId": <the exact accepted selector value> }
}

The digest string is prefixed with sha256:. Use a canonicalization library rather than assuming ordinary JSON serialization has the required order and number representation. The sample client implements this check.

The digest binds evaluation metadata to a request; it is not a receipt signature or proof that a tool executed. Keep it with a separate host outcome.

Handle errors

HTTP status or condition Action
400, InvalidRequest Correct the context, JSON types, point/target pairing, selector, or payload size.
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, NativeRouteDisabled Check endpoint, API version, account, and region enablement. Do not change to an older request format as an automatic fallback.
409, PolicyFenceChanged The policy changed during evaluation. Reconcile the intended version before a bounded retry.
UnsupportedCapability or unavailable required policy/dependency Restore the required capability or policy. Do not skip its check.
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 deny A policy outcome, not a transport failure. Do not retry until it becomes an allow.
Invalid verdict or receipt mismatch 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/evaluation correlation information without logging sensitive payloads.

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 ID; the request format shown here does not pin an ETag. Use distinct named versions for deliberate rollout, and record the actual revision returned in each receipt.

Monitor evaluation and enforcement

Record:

  • Session, action, point, and evaluation IDs.
  • Policy resource IDs, revisions, and digests.
  • 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. Receipt metadata is useful for correlation, but it does not replace a data-handling policy.

Delete a policy and its Rego

  1. Stop or reconfigure clients using the policy.
  2. Check for other references to its reusable Rego.
  3. Delete the policy with its current ETag.
  4. If deletion is asynchronous, wait for the ARM operation to succeed.
  5. 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.