Guida introduttiva: Valutare una chiamata di strumento con i controlli agente (anteprima)

In questa guida introduttiva si usano le API REST dei controlli agente per creare un criterio tramite Azure Resource Manager (ARM). Si valuta quindi una chiamata di strumento proposta con Unified Moderate.

Il criterio consente rimborsi maggiori di zero e non maggiori di 100. Inviare un rimborso di 75 per visualizzare un risultato consentito. Inviare un rimborso di 150 per visualizzare un risultato negativo.

Queste chiamate API valutano i rimborsi proposti. Non eseguono uno strumento né effettuano un rimborso.

Per un'introduzione ai criteri e ai punti di intervento, vedere Che cosa sono i controlli dell'agente?

Se non si ha una sottoscrizione di Azure, crearne una gratuitamente.

Prerequisites

  • Una sottoscrizione di Azure.
  • Una risorsa Sicurezza dei contenuti di Azure AI abilitata per l'anteprima dei controlli dell'agente. Se è necessaria una risorsa, creare una risorsa Content Safety in un'area abilitata per l'accesso in anteprima. La creazione di risorse da sola non abilita i controlli agente.
  • Autorizzazione per creare criteri e risorse Rego nell'account, ad esempio Contributor nell'ambito dell'account.
  • Il ruolo Cognitive Services User nell'account per le chiamate di runtime. La sezione setup mostra come un amministratore può concedere questo ruolo. La creazione di assegnazioni di ruolo richiede autorizzazioni aggiuntive, ad esempio Amministratore Role Based Controllo di accesso.
  • interfaccia della riga di comando di Azure, cURL 7.76 o versione successiva e PowerShell 7 o versione successiva.

Questa procedura dettagliata usa l'autenticazione Microsoft Entra e l'endpoint del sottodominio personalizzato dell'account. Non richiede un SDK, Node.js, o OPA.

Note

Questo esempio usa la versione 2026-11-15-preview dell'API ARM, la versione 2026-09-01-preview dell'API Unified Moderate e la versione 0.4.0-alpha.1 del manifesto ACS. L'account e l'area geografica devono supportare queste versioni.

Configurare la risorsa e l'accesso

Apri PowerShell in una directory di lavoro per i file di richiesta seguenti. Eseguire i comandi nella stessa sessione.

Accedere e selezionare la sottoscrizione che contiene la risorsa Content Safety:

$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-09-01-preview'
$RegoId = "$AccountId/raiRegos/refund-quickstart"
$PolicyId = "$AccountId/raiPolicies/refund-quickstart"

Se l'utente connesso non dispone già di Cognitive Services User nell'account, un amministratore con autorizzazione di assegnazione di ruolo può eseguire:

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

L'assegnazione si applica all'utente connesso. Un amministratore che assegna l'accesso a un altro utente deve usare invece l'ID oggetto di tale persona. Attendere la propagazione delle assegnazioni di ruolo.

Ottenere un token di accesso ARM per la creazione delle risorse:

$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 e la moderazione unificata usano gruppi di destinatari dei token diversi. Il token di runtime viene ottenuto più avanti in questa procedura dettagliata.

Creare una risorsa Rego

Rego definisce la regola di rimborso. Salvare il codice seguente come 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
}

Questa regola vieta per impostazione predefinita. Consente solo una refund_order chiamata con una quantità numerica nell'intervallo consentito.

Creare il corpo della richiesta ARM dal file di origine:

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

La proprietà rego contiene il testo di origine. encoding: "None" indica che il testo di origine non è codificato in Base64.

Caricalo con una richiesta PUT ARM:

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

Un'operazione PUT riuscita restituisce HTTP 200 o 201 e un ETag. If-None-Match: * impedisce a questa richiesta di sostituire una risorsa esistente. Se refund-quickstart esiste già, usare un nuovo nome di risorsa o seguire le indicazioni per l'aggiornamento dei criteri.

Creare la policy

Il manifest del criterio connette il pre_tool_call punto di intervento alla regola Rego e seleziona gli argomenti dello strumento per la valutazione.

Salva il corpo completo della richiesta ARM come 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 Seleziona il formato del criterio ACS.
query Identifica la verdict regola nel refund_guard pacchetto Rego.
pre_tool_call Applica la regola prima che l'host invii una chiamata allo strumento.
policy_target Seleziona gli argomenti dello strumento inviati.
tool_name_from Seleziona la voce dello strumento nel catalogo degli strumenti del manifesto.
acsRegos Carica la risorsa Rego creata nel passaggio precedente.

Se è stato modificato il nome della risorsa Rego, aggiornare acsRegos[0].regoName in modo che corrisponda.

Creare il criterio con una richiesta PUT arm:

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

Un'operazione PUT completata restituisce HTTP 200 o 201. Il criterio viene archiviato nell'account di Sicurezza dei contenuti e fa riferimento a Rego dallo stesso account.

Valutare una chiamata di strumento proposta

Ottenere un token di accesso a Content Safety:

$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.'
}
$ModerateUrl = "$Endpoint/contentsafety/content:unifiedModerate"
$ModerateUrl += "?api-version=$DataApiVersion"

Salvare la richiesta seguente come tool-call.json:

{
  "policyId": "refund-quickstart",
  "source": "pre_tool_call",
  "toolName": "refund_order",
  "toolCallId": "refund-1",
  "content": "{\"order_id\":\"demo-001\",\"amount\":75}",
  "context": {
    "agentId": "support-agent",
    "sessionId": "refund-example",
    "sequence": 0
  }
}
Field Purpose
policyId Seleziona il criterio di accesso pubblicato in base al nome nell'ambito dell'account di pubblicazione.
source Seleziona il punto da valutare.
toolName, toolCallId Identificare lo strumento proposto e la chiamata.
content Contiene gli argomenti dello strumento come stringa di oggetto con codifica JSON.
context Identifica l'agente, la sessione e la sequenza di eventi per la correlazione. Questi valori non concedono l'accesso.

Gli identificatori fissi semplificano la riproduzione di questo esempio. In un'applicazione crearli per l'evento effettivo. Mantenere i tipi di argomento all'interno della stringa con codifica JSON, incluso il valore numerico. Se il nome della risorsa dei criteri è stato modificato, aggiornare policyId in modo che corrisponda.

Invia la richiesta:

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

L'elemento body policyId seleziona il criterio creato tramite ARM. Non è necessaria alcuna associazione di risorse.

Interpreta la risposta

Unified Moderate restituisce una stringa verdict e i dettagli delle decisioni in acsVerdict. Per un rimborso di 75, la risposta include:

{
  "verdict": "allowed",
  "content": "{\"order_id\":\"demo-001\",\"amount\":75}",
  "acsVerdict": { "decision": "allow" }
}

La risposta può includere membri aggiuntivi. Altre politiche applicabili possono influire sulla decisione finale.

Campo risposta Meaning
verdict allowed o blocked.
acsVerdict.decision La decisione che l'host deve applicare. Questa regola restituisce allow o deny.
acsVerdict.reason Codice motivo, quando la regola ne fornisce uno.
content Stringa di contenuto consentita, restituita per un risultato consentito.

HTTP 200 significa che la valutazione è stata completata. Controllare sia verdict che acsVerdict.decision per determinare se la chiamata è consentita.

Prova a effettuare un rimborso oltre il limite

Modificare l'importo in content in 150, quindi inviare un nuovo evento:

$Request = Get-Content -LiteralPath .\tool-call.json -Raw |
    ConvertFrom-Json -AsHashtable
$Arguments = $Request.content | ConvertFrom-Json -AsHashtable
$Arguments.amount = 150
$Request.content = $Arguments | ConvertTo-Json -Compress
$Request.toolCallId = 'refund-2'
$Request.context.sequence = 1
$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.'
}

La risposta usa ancora HTTP 200, ma la regola restituisce questo verdetto:

{
  "verdict": "blocked",
  "reason": "refund_not_permitted",
  "acsVerdict": {
    "decision": "deny",
    "reason": "refund_not_permitted"
  }
}

In un'applicazione, l'host controlla il verdetto prima di inviare il tool. Una valutazione negata o non riuscita mantiene bloccata la chiamata.

Per una chiamata consentita, l'host esegue gli argomenti valutati. Vedere Interpretare la risposta per la convalida della risposta e la gestione delle trasformazioni.

Collega la valutazione al tuo agente

Aggiungere il controllo nel codice che distribuisce lo strumento, prima dell'esecuzione dello strumento. Acquisire gli argomenti proposti una sola volta e usare lo stesso valore sia per la valutazione che per l'invio. Il codice seguente è pseudocodice, non un'API SDK fornita:

arguments = captureProposedArguments(proposedCall)
request = { policyId, source: "pre_tool_call", toolName, toolCallId,
            content: json(arguments), context: { agentId, sessionId, sequence } }
response = evaluate(request, boundedDeadline)
validateResponse(response)

if response.verdict != "allowed" or response.acsVerdict.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

Un errore di valutazione o di convalida della risposta deve interrompere l'invio. Mantenere la risposta associata alla richiesta esatta in sospeso. L'host deve implementare ogni punto di intervento richiesto dall'applicazione.

Questo gate minimo blocca le trasformazioni e i deny con approvazione. Aggiungere questi comportamenti solo quando l'host implementa i contratti di convalida e approvazione. Non ritentare un'azione dello strumento non idempotente semplicemente perché la valutazione è stata ritentata.

Per l'output generato, valutare il contenuto completo prima di rilasciarlo. Se il modello trasmette in streaming, memorizzare l'output nel buffer entro un limite dell'applicazione, inviare l'output completato per la valutazione, quindi rilasciare solo il contenuto consentito. Arrestare in caso di overflow o errore.

L'invio di token all'utente prima del completamento del controllo non può essere annullato da un rifiuto successivo. Questa procedura dettagliata REST non implementa un protocollo di streaming-release per blocco.

Pulire le risorse

Al termine, eliminare il criterio refund-quickstart e quindi la relativa risorsa Rego se non sono più necessari. Per eliminare il criterio e la risorsa Rego con protezione ETag e gestire le operazioni asincrone, vedere Eliminare un criterio e il relativo Rego.

Eliminare l'account separatamente solo se è stato creato per questo esercizio e nessun'altra applicazione ne ha bisogno.

Passaggi successivi