Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
Dans ce guide de démarrage rapide, vous utilisez les API REST Contrôles d’agent pour créer une stratégie via Azure Resource Manager (ARM). Ensuite, vous évaluez un appel d’outil proposé avec Unified Moderate.
La politique autorise les remboursements supérieurs à zéro et non supérieurs à 100. Envoyez un remboursement de 75 pour voir un résultat accepté. Envoyez ensuite un remboursement de 150 afin de voir un résultat rejeté.
Ces appels d’API évaluent les remboursements proposés. Ils n’exécutent pas d’outil et n’émettent pas de remboursement.
Pour une présentation des politiques et des points d’intervention, consultez Que sont les contrôles d’agent ?
Si vous n’avez pas d’abonnement Azure, créez-en un gratuitement.
Prerequisites
- Un abonnement Azure.
- Ressource Azure AI Sécurité du Contenu activée pour la préversion des contrôles d’agent. Si vous avez besoin d’une ressource, créez une ressource Content Safety dans une région activée pour votre accès en préversion. Le simple fait de créer une ressource n’active pas Agent Controls.
- Autorisation de créer des ressources de stratégie et de régo sous ce compte, comme
Contributordans l’étendue du compte. - Rôle
Cognitive Services Usersur le compte, pour les appels d’exécution. La section d’installation montre comment un administrateur peut accorder ce rôle. La création d’attributions de rôles nécessite une autorisation supplémentaire, telle que Role Based Access Control Administrator. - Azure CLI, cURL 7.76 ou version ultérieure et PowerShell 7 ou version ultérieure.
Cette procédure pas à pas utilise Microsoft Entra l'authentification et le point de terminaison de sous-domaine personnalisé du compte. Il ne nécessite pas de SDK, de Node.js ou d’OPA.
Note
Cet exemple utilise la version 2026-11-15-previewde l’API ARM, la version 2026-10-15-previewde l’API Unified Moderate et la version 0.4.0-alpha.1du manifeste ACS. Votre compte et votre région doivent prendre en charge ces versions.
Configurer votre ressource et votre accès
Ouvrez PowerShell dans un répertoire de travail pour les fichiers de requête ci-dessous. Exécutez les commandes dans la même session.
Connectez-vous et sélectionnez l’abonnement qui contient votre ressource 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-10-15-preview'
$RegoId = "$AccountId/raiRegos/refund-quickstart"
$PolicyId = "$AccountId/raiPolicies/refund-quickstart"
Si votre utilisateur connecté n’a pas déjà Cognitive Services User sur le compte, un administrateur disposant de l’autorisation d’attribution de rôle peut exécuter la commande suivante :
$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’affectation s’applique à l’utilisateur connecté. Un administrateur affectant l’accès à une autre personne doit utiliser l’ID d’objet de cette personne à la place de son propre ID d’objet. Attendez que les attributions de rôles se propagent.
Obtenez un jeton d’accès ARM pour créer les ressources :
$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 et Unified Moderate utilisent des audiences de jetons différentes. Vous obtenez le jeton d’exécution plus loin dans cette procédure pas à pas.
Créer une ressource Rego
Rego définit la règle de remboursement. Enregistrez le code suivant en tant que 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
}
Cette règle refuse par défaut. Il autorise uniquement un appel refund_order avec un montant numérique dans la plage autorisée.
Créez le corps de la requête ARM à partir du fichier source :
$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 propriété rego contient le texte source.
encoding: "None" signifie que la source n’est pas encodée en Base64.
Chargez-le avec une requête ARM PUT :
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 PUT réussi retourne HTTP 200 ou 201 et un ETag.
If-None-Match: * empêche cette demande de remplacer une ressource existante. S’il refund-quickstart existe déjà, utilisez un nouveau nom de ressource ou suivez les instructions de mise à jour de stratégie.
Créer la politique
Le manifeste de stratégie connecte le pre_tool_call point d’intervention à la règle Rego et sélectionne les arguments de l’outil pour l’évaluation.
Enregistrez ce corps de requête ARM complet sous 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" }]
}
}
| Propriété | Purpose |
|---|---|
format |
Sélectionne le format de stratégie ACS. |
query |
Identifie la verdict règle dans le refund_guard package Rego. |
pre_tool_call |
Applique la règle avant que l’hôte distribue un appel d’outil. |
policy_target |
Sélectionne les arguments de l’outil soumis. |
tool_name_from |
Sélectionne l’entrée de l’outil dans le catalogue d’outils du manifeste. |
acsRegos |
Charge la ressource Rego créée à l’étape précédente. |
Si vous avez modifié le nom de la ressource Rego, mettez à jour acsRegos[0].regoName pour correspondre.
Créez la stratégie avec une requête ARM PUT :
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 PUT réussi retourne HTTP 200 ou 201. La politique est stockée sous le compte Content Safety et fait référence à Rego à partir de ce même compte.
Évaluer un appel d’outil proposé
Obtenez un jeton d’accès Content Safety et encodez l’URL de l’ID de ressource de stratégie :
$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"
Enregistrez la requête suivante comme tool-call.jsonsuit :
{
"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 }
}
| Champ | Purpose |
|---|---|
spec |
Identifie le format de contexte De hooks de l’agent. |
interception_point |
Sélectionne le point de cycle de vie à évaluer. |
timestamp, sequence |
Enregistrez l’heure et l’ordre de l’événement dans la session. |
agent, session |
Identifiez l’agent et exécutez la corrélation. Ils n’accordent pas d’accès. |
tool_call |
Décrit le nom proposé de l’outil et ses arguments. |
target |
Contient les arguments sélectionnés pour l’évaluation. À ce stade, il doit être égal à tool_call.args. |
L’horodatage fixe et les identificateurs facilitent la reproduction de cet exemple. Dans une application, construisez-les pour l’événement réel. Conservez les arguments en tant que JSON natif, y compris le montant numérique.
Envoyez la demande :
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.'
}
Le policyId paramètre de requête sélectionne la stratégie que vous avez créée via ARM. Le corps décrit l’appel d’outil proposé. Il ne contient pas de sélecteur de stratégie.
Interpréter la réponse
Unified Moderate retourne un verdict et un receipt. Pour un remboursement de 75, le verdict de la règle est le suivant :
{
"decision": "allow"
}
Il s’agit de la verdict partie de la réponse, et non de la réponse complète. Des politiques applicables supplémentaires peuvent affecter la décision finale.
| Champ réponse | Sens |
|---|---|
verdict.decision |
Décision que l’hôte doit appliquer. Cette règle retourne allow ou deny. |
verdict.reason |
Code de raison, quand la règle en fournit une. |
receipt.evaluationId |
Identifie cette évaluation pour la corrélation avec les enregistrements d’application. |
receipt.evaluatedInterventionPoint |
Le point évalué, ici pre_tool_call. |
receipt.evaluatedPolicyLayers |
Identifie les politiques et versions évaluées. |
receipt.requestBinding |
Lie le reçu à la demande et au sélecteur de stratégie. |
HTTP 200 signifie que l’évaluation est terminée. Vérifiez verdict.decision si l’appel est autorisé.
Essayez un remboursement au-dessus de la limite
Modifiez les deux copies du montant à 150, puis envoyez un nouvel événement :
$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.'
}
La réponse utilise toujours HTTP 200, mais la règle retourne ce verdict :
{
"decision": "deny",
"reason": "refund_not_permitted"
}
Dans une application, l’hôte vérifie le verdict et le reçu de traitement avant d’invoquer l’outil. Une évaluation refusée ou ayant échoué conserve l’appel bloqué.
Pour un appel autorisé, l’hôte exécute les arguments évalués. Consultez Interpréter la réponse pour les vérifications de reçu et la gestion des transformations.
Connecter l’évaluation à votre agent
Ajoutez la vérification dans le code qui appelle l’outil avant l’exécution de l’outil. Capturez les arguments proposés une fois et utilisez cette valeur à la fois pour l’évaluation et l’envoi. Le code suivant est du pseudocode, et non une API SDK fournie :
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
Un échec d’évaluation ou de validation de reçu doit arrêter la distribution. La validation des reçus vérifie la liaison de requête exacte, la stratégie sélectionnée, le point d’intervention et le producteur du compte émetteur attendu. Pour plus d’informations, consultez les champs Reçu. L’hôte doit également implémenter chaque point requis par le jeu de stratégies retourné.
Cette barrière minimale bloque les transformations et les refus assortis d’une approbation. Ajoutez ces comportements uniquement lorsque votre hôte implémente ses contrats de validation et d’approbation. N’effectuez pas de nouvelle tentative d’action d’outil non idempotente simplement parce que l’évaluation a été retentée.
Pour la sortie générée, évaluez le contenu complet avant de le libérer. Si le modèle diffuse le contenu en continu, placez la sortie en mémoire tampon dans les limites définies par l’application, envoyez la sortie terminée pour l’évaluation, puis ne publiez que le contenu autorisé. Arrêtez sur le dépassement de capacité ou l’échec.
L’envoi de jetons à l’utilisateur avant la fin de la vérification ne peut pas être annulé par un refus ultérieur. Cette procédure pas à pas REST n’implémente pas de protocole de diffusion en continu par bloc.
Nettoyer les ressources
Une fois que vous avez terminé, supprimez la refund-quickstart stratégie, puis sa ressource Rego s’ils ne sont plus nécessaires. Pour supprimer la stratégie et la ressource Rego avec la protection ETag et gérer les opérations asynchrones, consultez Supprimer une stratégie et son Rego.
Supprimez le compte séparément uniquement si vous l’avez créé pour cet exercice et qu’aucune autre application n’en a besoin.
Étapes suivantes
- Rédigez des politiques pour ajouter vos propres règles et classifieurs Content Safety.
- Configurez un juge LLM pour évaluer le contenu par rapport à une grille d’évaluation écrite.
- Choisissez un modèle de stratégie pour d’autres scénarios.
- Utilisez une identité managée en production au lieu d’une identité de développeur interactive.
- Pour obtenir des exemples de clients facultatifs qui permettent d’intégrer des vérifications d’évaluation et de reçu dans votre application, consultez l’exemple de client HTTP.