Schnellstart: Einen Toolaufruf mit Agent Controls auswerten (Vorschau)

In dieser Schnellstartanleitung verwenden Sie die AGENT-Steuerelemente-REST-APIs, um eine Richtlinie über Azure Resource Manager (ARM) zu erstellen. Anschließend bewerten Sie einen vorgeschlagenen Toolaufruf mit Unified Moderate.

Die Richtlinie erlaubt Rückerstattungen größer als Null und nicht größer als 100. Übermitteln Sie eine Rückerstattung über 75, um ein zulässiges Ergebnis anzuzeigen. Übermitteln Sie dann eine Rückerstattung von 150, um ein abgelehntes Ergebnis zu sehen.

Diese API-Aufrufe bewerten die vorgeschlagenen Rückerstattungen. Sie führen kein Tool aus oder veranlassen eine Rückerstattung.

Eine Einführung in Richtlinien und Interventionspunkte finden Sie unter Was sind Agent Controls?

Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen.

Prerequisites

  • Ein Azure-Abonnement.
  • Eine Azure KI Inhaltssicherheit Ressource, die für die Vorschau der Agentsteuerelemente aktiviert ist. Wenn Sie eine Ressource benötigen, erstellen Sie eine Content Safety-Ressource in einer Region, die für Ihren Vorschauzugriff aktiviert ist. Die Ressourcenerstellung allein aktiviert keine Agentsteuerelemente.
  • Berechtigung zum Erstellen von Richtlinien- und Rego-Ressourcen unter diesem Konto, z. B. Contributor, im Bereich des Kontos.
  • Die Cognitive Services User Rolle auf dem Konto für Laufzeitaufrufe. Der Setupabschnitt zeigt, wie ein Administrator diese Rolle erteilen kann. Das Erstellen von Rollenzuweisungen erfordert zusätzliche Berechtigungen, z. B. Role Based Access Control Administrator.
  • Azure CLI, cURL 7.76 oder höher und PowerShell 7 oder höher.

In dieser exemplarischen Vorgehensweise werden Microsoft Entra Authentifizierung und der Endpunkt der benutzerdefinierten Unterdomäne des Kontos verwendet. Es ist kein SDK, Node.jsoder OPA erforderlich.

Note

In diesem Beispiel wird ARM-API-Version 2026-11-15-preview, Unified Moderate API-Version 2026-10-15-previewund ACS-Manifestversion 0.4.0-alpha.1verwendet. Ihr Konto und Ihre Region müssen diese Versionen unterstützen.

Richten Sie Ihre Ressource und den Zugriff ein

Öffnen Sie PowerShell in einem Arbeitsverzeichnis für die nachfolgenden Anfragedateien. Führen Sie die Befehle in derselben Sitzung aus.

Melden Sie sich an, und wählen Sie das Abonnement aus, das Ihre Content Safety-Ressource enthält:

$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"

Wenn Ihr angemeldeter Benutzer noch nicht Cognitive Services User für das Konto hat, kann ein Administrator mit Rollenzuweisungsberechtigung Folgendes ausführen:

$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.' }

Die Zuweisung gilt für den angemeldeten Benutzer. Ein Administrator, der einer anderen Person Zugriff zuweist, muss stattdessen die Objekt-ID dieser Person verwenden. Warten Sie, bis die Rollenzuweisungen wirksam werden.

Rufen Sie ein ARM-Zugriffstoken zum Erstellen der Ressourcen ab:

$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 und Unified Moderate verwenden unterschiedliche Token-Zielgruppen. Sie erhalten das Laufzeittoken später in dieser exemplarischen Vorgehensweise.

Erstellen einer Rego-Ressource

Rego definiert die Erstattungsregel. Speichern Sie den folgenden Code als 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
}

Diese Regel verweigert standardmäßig. Er lässt nur einen refund_order Aufruf mit einem numerischen Betrag im zulässigen Bereich zu.

Erstellen Sie den ARM-Anforderungstext aus der Quelldatei:

$RegoBody = @{
    properties = @{
        encoding = 'None'
        rego = Get-Content -LiteralPath .\refund.rego -Raw
    }
}
$RegoBody | ConvertTo-Json -Depth 10 |
    Set-Content -LiteralPath .\rego-request.json -Encoding utf8

Die rego Eigenschaft enthält den Quelltext. encoding: "None" bedeutet, dass die Quelle nicht base64-codiert ist.

Laden Sie ihn mit einer ARM PUT-Anforderung hoch:

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.'
}

Ein erfolgreicher PUT gibt HTTP 200 oder 201 sowie ein ETag zurück. If-None-Match: * verhindert, dass diese Anforderung eine vorhandene Ressource ersetzt. Falls refund-quickstart bereits vorhanden ist, verwenden Sie einen neuen Ressourcennamen, oder befolgen Sie die Richtlinien für Richtlinienaktualisierungen.

Richtlinie erstellen

Das Richtlinienmanifest verbindet den pre_tool_call Interventionspunkt mit der Rego-Regel und wählt die Toolargumente für die Auswertung aus.

Diesen vollständigen ARM-Anforderungstext speichern unter 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" }]
  }
}
Eigenschaft Purpose
format Wählt das ACS Richtlinienformat aus.
query Identifiziert die verdict Regel im refund_guard Rego-Paket.
pre_tool_call Wendet die Regel an, bevor der Host einen Toolaufruf auslöst.
policy_target Wählt die übermittelten Toolargumente aus.
tool_name_from Wählt den Tooleintrag im Toolkatalog des Manifests aus.
acsRegos Lädt die im vorherigen Schritt erstellte Rego-Ressource.

Wenn Sie den Namen der Rego-Ressource geändert haben, aktualisieren Sie acsRegos[0].regoName entsprechend.

Erstellen Sie die Richtlinie mit einer ARM PUT-Anforderung:

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.'
}

Ein erfolgreicher PUT gibt HTTP 200 oder 201. Die Richtlinie wird unter dem Konto für die Inhaltssicherheit gespeichert und verweist auf Rego von diesem Konto.

Auswerten eines vorgeschlagenen Toolaufrufs

Rufen Sie ein Inhaltssicherheits-Zugriffstoken ab und URL-codieren Sie die Richtlinienressourcen-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"

Speichern Sie die folgende Anforderung als 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 }
}
Feld Purpose
spec Identifiziert das Agent-Hooks-Kontextformat.
interception_point Wählt den zu bewertenden Lebenszykluspunkt aus.
timestamp, sequence Zeichnen Sie die Ereigniszeit und -reihenfolge innerhalb der Sitzung auf.
agent, session Identifizieren Sie den Agent, und führen Sie ihn für die Korrelation aus. Sie gewähren keinen Zugang.
tool_call Beschreibt den vorgeschlagenen Toolnamen und die vorgeschlagenen Argumente.
target Enthält die argumente, die für die Auswertung ausgewählt sind. An diesem Punkt muss es gleich sein tool_call.args.

Der feste Zeitstempel und die Bezeichner machen das Reproduzieren dieses Beispiels einfach. Erstellen Sie sie in einer Anwendung für das tatsächliche Ereignis. Behalten Sie Argumente als systemeigenes JSON, einschließlich des numerischen Betrags.

Senden Sie die Anforderung:

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.'
}

Der policyId Abfrageparameter wählt die Richtlinie aus, die Sie über ARM erstellt haben. Der Textkörper beschreibt den vorgeschlagenen Toolaufruf. Es enthält keine Richtlinienauswahl.

Antwort interpretieren

Unified Moderate gibt ein verdict und ein receipt. Für eine Rückerstattung von 75 lautet das Urteil der Regel:

{
  "decision": "allow"
}

Dies ist der verdict Teil der Antwort, nicht die vollständige Antwort. Zusätzliche anwendbare Richtlinien können sich auf die endgültige Entscheidung auswirken.

Antwortfeld Dies bedeutet
verdict.decision Die Entscheidung, die der Host erzwingen muss. Diese Regel gibt allow zurück oder deny.
verdict.reason Ein Grundcode, wenn die Regel einen bereitstellt.
receipt.evaluationId Identifiziert diese Auswertung für die Korrelation mit Anwendungsdatensätzen.
receipt.evaluatedInterventionPoint Der hier pre_tool_call bewertete Punkt.
receipt.evaluatedPolicyLayers Identifiziert die ausgewerteten Richtlinien und Versionen.
receipt.requestBinding Bindet den Beleg an die Anforderungs- und Richtlinienselektor.

HTTP 200 bedeutet, dass die Auswertung abgeschlossen ist. Prüfen Sie anhand von verdict.decision, ob der Anruf zulässig ist.

Probieren Sie eine Rückerstattung über dem Grenzwert aus.

Ändern Sie beide Kopien des Betrags in 150, und senden Sie dann ein neues Ereignis:

$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.'
}

Die Antwort verwendet weiterhin HTTP 200, aber die Regel gibt diese Bewertung zurück:

{
  "decision": "deny",
  "reason": "refund_not_permitted"
}

In einer Anwendung überprüft der Host die Bewertung und die Empfangsbestätigung, bevor das Tool aufgerufen wird. Bei einer verweigerten oder fehlgeschlagenen Auswertung wird der Aufruf blockiert.

Bei einem zulässigen Aufruf führt der Host die ausgewerteten Argumente aus. Siehe Die Antwort interpretieren für Bestätigungsprüfungen und Transformationsverarbeitung.

Verbinden Sie die Bewertung mit Ihrem Agenten

Fügen Sie die Überprüfung in den Code ein, der das Tool aufruft, bevor das Tool ausgeführt wird. Erfassen Sie die vorgeschlagenen Argumente einmal, und verwenden Sie diesen Wert sowohl für die Auswertung als auch für die Weiterleitung. Der folgende Code ist Pseudocode, keine bereitgestellte 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

Ein Auswertungs- oder Belegvalidierungsfehler muss die Weiterleitung stoppen. Die Belegvalidierung überprüft die genaue Anforderungsbindung, die ausgewählte Policy, den Interventionspunkt und den erwarteten Produzenten des Serving-Accounts. Weitere Informationen finden Sie unter "Belegfelder". Der Host muss auch jeden Punkt implementieren, der vom zurückgegebenen Richtliniensatz benötigt wird.

Diese minimale Sperre blockiert Transformationen und Ablehnungen mit Genehmigung. Fügen Sie diese Verhaltensweisen nur hinzu, wenn Ihr Host deren Validierungs- und Genehmigungsverträge implementiert. Versuchen Sie nicht erneut, eine nicht-idempotente Toolaktion nur zu wiederholen, weil die Auswertung wiederholt wurde.

Für die generierte Ausgabe werten Sie den vollständigen Inhalt aus, bevor Sie ihn freigeben. Wenn das Modell streamt, puffern Sie die Ausgabe innerhalb eines Anwendungslimits, übermitteln Sie die abgeschlossene Ausgabe für die Auswertung, und geben Sie nur den zulässigen Inhalt frei. Bei Überlauf oder Fehler stoppen.

Das Senden von Token an den Benutzer, bevor die Überprüfung abgeschlossen ist, kann von einer späteren Ablehnung nicht rückgängig gemacht werden. Diese REST-Anleitung implementiert kein Protokoll zur Streaming-Freigabe pro Chunk.

Bereinigen von Ressourcen

Nachdem Sie fertig sind, löschen Sie die refund-quickstart Richtlinie und dann die zugehörige Rego-Ressource, wenn beide nicht mehr benötigt werden. Informationen zum Löschen der Richtlinie und der Rego-Ressource mit ETag-Schutz und zum Behandeln asynchroner Vorgänge finden Sie unter Löschen einer Richtlinie und des zugehörigen Rego-Vorgangs.

Löschen Sie das Konto separat, wenn Sie es für diese Übung erstellt haben und keine andere Anwendung es benötigt.

Nächste Schritte