Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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
Contributornell'ambito dell'account. - Il ruolo
Cognitive Services Usernell'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
- Creare i criteri per aggiungere regole personalizzate e classificatori di Sicurezza dei contenuti.
- Configurare un giudice LLM per valutare il contenuto in base a una rubrica scritta.
- Esplora il modello di criteri degli strumenti approvati per un altro scenario.
- Usa un'identità gestita nell'ambiente di produzione anziché un'identità per sviluppatori interattiva.