API et opérations Des contrôles d’agent (préversion)

Cette référence couvre le flux de stratégie nommée autonome. Utilisez ARM pour gérer les stratégies et Rego, ainsi que le point de terminaison du plan de données du compte pour les évaluer.

Prerequisites

Suivez le guide de démarrage rapide pour l’accès en préversion, un compte de service et des autorisations de création et d’exécution. Les exemples de gestion utilisent ses variables de ressources et les scripts répertoriés dans l’exemple de guide. Exécutez les exemples à partir du répertoire contenant les scripts de gestion.

Points de terminaison et versions

Purpose Endpoint Version
Gestion des comptes et des stratégies https://management.azure.com 2026-11-15-preview
Evaluation Point de terminaison du compte Content Safety service 2026-10-15-preview

Les ressources de stratégie sont les suivantes :

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}
  /providers/Microsoft.CognitiveServices/accounts/{accountName}
    /raiRegos/{regoName}
    /raiPolicies/{policyName}

Les sauts de ligne ci-dessus sont à des fins de lisibilité. Chaque requête utilise un chemin d’accès de ressource unique.

Créez un régo réutilisable avant la stratégie qui la référence. Un corps Rego PUT contient properties.encoding et properties.rego.

None signifie une source simple ; le contrat définit Base64également . Les exemples utilisent une source UTF-8 simple.

Un corps PUT de stratégie contient properties.format: "ACS", properties.acset properties.acsRegos. La version du manifeste interne n’est 0.4.0-alpha.1pas une version de l’API.

Authentification et autorisation

Call Étendue OAuth Access
ARM https://management.azure.com/.default Actions de gestion des ressources requises pour le compte et les ressources enfants.
Modéré unifié https://cognitiveservices.azure.com/.default Cognitive Services User sur le compte de service, avec l’accès en préversion activé.
Inférence du juge appartenant au client Public de service de modèle pris en charge, acquis par le service Autorisation d’inférence pour l’identité du compte de service sur le compte de modèle.

Utilisez un point de terminaison de sous-domaine personnalisé pour l’authentification Microsoft Entra. N’échangez pas de jetons ARM et de plan de données.

Le contrat de plan de données déclare également l’authentification Ocp-Apim-Subscription-Key , sous réserve de la configuration de l’authentification locale et de la préversion du compte. Ces guides utilisent les informations d’identification Entra et recommandent des identités managées pour les applications. Une clé d’abonnement n’est pas une identité d’application distincte.

Les ID d’agent, les métadonnées d’acteur, les ID de session et les revendications d’identité fournies par le client dans JSON ne sont pas autorisés.

Utiliser une identité managée en production

Le guide de démarrage rapide utilise une identité de développeur interactive. Pour une application, utilisez une identité managée attachée à son calcul :

  1. Créez ou activez l’identité sur l’hôte de l’application.
  2. Accordez son principal Cognitive Services User au compte de sécurité du contenu de service.
  3. Configurez les informations d’identification de l’application pour sélectionner cette identité et obtenir un jeton pour https://cognitiveservices.azure.com/.default.
  4. Vérifiez qu’une demande autorisée réussit et qu’une identité non autorisée est rejetée.

Pour une identité affectée par l’utilisateur, les attributions de rôles utilisent son ID principal et son type ServicePrincipalde principal. La sélection des informations d’identification utilise son ID client. La création de l’identité sans l’attacher à l’hôte de l’application ne le rend pas disponible pour l’application.

L’identité de l’application est distincte de l’identité de compte de service utilisée par un juge LLM appartenant au client.

Appeler un modéré unifié

Cette requête HTTP est schématique. {unified-moderate-url} inclut votre point de terminaison, /contentsafety/content:unifiedModerate, api-version=2026-10-15-previewet le arm policyIdcomplet , encodé une seule fois par URL.

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

Utilisez l’ID de ressource de stratégie ARM complet sous le compte de service en tant que policyId. Lorsqu’un déploiement prend en charge les noms de stratégie courts, l’ID complet est toujours le sélecteur plus clair. Encoder l’URL une fois à l’aide d’un générateur de requêtes HTTP ; ne concaténer manuellement pas les ID non bouctés.

Le sélecteur autonome est un paramètre de requête. Aucune liaison de ressource ou sélecteur de ressources supplémentaire n’est nécessaire.

Corps de la demande

Cet exemple évalue les arguments de l’outil avant la répartition :

{
  "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 }
}

Pour l’exécution réelle, utilisez un horodatage actuel, l’ID de votre session et le numéro de séquence croissant, et l’action exacte que votre hôte est sur le point d’effectuer. Le service valide la charge utile spécifique au point et l’égalité cible.

Conservez les valeurs en tant que JSON natif. Un objet d’argument d’outil ne doit pas être encodé en tant que chaîne JSON. Conservez les nombres, les booléens, les tableaux, les objets et null où le contrat les autorise.

Le mappage cible est répertorié dans les stratégies d’auteur. Les générateurs de contexte du Kit de développement logiciel (SDK) aident à assurer la cohérence de ces champs.

Limits

Les requêtes et réponses sont toutes limitées à 1 048 576 octets JSON décodés UTF-8 et à la profondeur du conteneur 64, y compris la racine. Utilisez des noms de membres JSON unicode et non ambigus valides. Les membres en double, les sélecteurs en conflit et les demandes de dépassement de limite sont des erreurs, et les évaluations réussies ne sont pas tronquées.

Une taille de charge utile HTTP prise en charge ne garantit pas qu’un classifieur ou un modèle particulier peut inspecter cette quantité de contenu. Les fonctionnalités requises ont leurs propres limites d’entrée et d’exécution.

Limites de création ARM

Les artefacts de stratégie stockés ont des limites distinctes du contexte d’exécution :

Item Limite sur les comptes en préversion activés Mesure
Manifeste ACS 256 Kio (262 144 octets) Compacter le json UTF-8 sérialisé pour properties.acs.
Ressource Rego 512 Kio (524 288 octets) Source UTF-8 décodée, y compris lors du chargement avec encoding: "Base64".
Compléter le corps ARM PUT 1 Mio (1 048 576 octets) Corps de la requête entier, y compris les wrappers JSON et la source encodée.

Ces limites dépendent du déploiement en préversion. Certains déploiements appliquent 48 manifestes KiB et 200 KiB décodés Rego. Vérifiez les limites activées pour votre compte avant de compter sur les limites supérieures.

Les limites d’artefact et de requête entière s’appliquent. Base64 étend la source transportée et l’échappement JSON source brut contribue également à la taille du corps. Une requête inférieure à 1 Mio peut toujours dépasser le manifeste ou la limite décodée-Rego.

Interpréter la réponse

Une réponse réussie contient :

Membre Sens
verdict allowAgrégat , denyou transform décision.
receipt Métadonnées identifiant l’évaluation et les stratégies évaluées exactement.

HTTP 200 signifie que l’évaluation est terminée. Cela ne signifie pas que l’action est autorisée.

Par exemple, le verdict membre peut être :

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

L’hôte doit :

  1. Validez la réponse et le reçu.
  2. Arrêtez sur , les denydonnées incorrectes ou les défaillances opérationnelles.
  3. Appliquez et validez une valeur de remplacement prise en charge transform avant d’utiliser sa valeur de remplacement.
  4. Exécutez ou relâchez uniquement la valeur évaluée et autorisée.
  5. Enregistrez ce qui s’est passé.

Les transformations de démarrage et d’arrêt ne sont pas prises en charge. Le chemin du juge dans ces guides ne prend pas non plus en charge les verdicts de transformation. Si votre application ne peut pas implémenter une transformation retournée ou un workflow d’approbation en toute sécurité, conservez l’action bloquée.

Demandes d’approbation

Une décision de révision est un refus jusqu’à ce que votre hôte le résolve. Une stratégie peut retourner, par exemple :

{
  "decision": "deny",
  "reason": "human_review_required",
  "approval": {
    "workflow": "transaction-review"
  }
}

Le contenu de l’objet d’approbation doit correspondre à un flux de travail que votre application implémente ; cet exemple n’en provisionne pas un. Liez toute approbation à l’action exacte et aux valeurs évaluées. Ne traitez pas la présence d’une approval autorisation d’exécution et ne laissez pas une approbation remplacer un refus sans condition indépendant.

Le approval champ n’ouvre pas de file d’attente de révision ou n’accorde pas d’autorisation.

Champs de reçu

Champ Vérification ou utilisation de l’hôte
receiptVersion Correspond au contrat de transport, ici 2026-10-15-preview.
profile Attendez-vous namedPolicy à ce flux.
evaluationId, attempt Mettre en corrélation les enregistrements d’évaluation de service et d’exécution de l’hôte.
requestBinding Exiger algorithm: "sha256" , canonicalization: "rfc8785"puis comparer digest avec le hachage du matériel de requête exact ci-dessous.
evaluatedPolicyLayers Vérifiez la stratégie nommée attendue ; conservez sa révision, sa synthèse sémantique, son digest d’artefact activé et sa décision.
evaluatedInterventionPoint Correspond au point envoyé dans cette requête.
requiredInterventionPoints Vérifiez que votre hôte implémente chaque point requis. Cela ne prouve pas que l’hôte les a appelés.
hostProfileVersion Enregistrez le profil d’évaluation du service.
authenticatedProducerResourceId Pour ce namedPolicy flux, correspondez à l’ID de compte de service de la configuration approuvée, et non à une valeur copiée à partir de la réponse.
harmResults, lorsqu’il est présent Résumés du classifieur public, pas l’entrée Rego ni les diagnostics de modèle interne complets.

Par exemple, une réponse complète de refus de stratégie nommée a cette forme. Les ID de ressource, la révision, l’ID d’évaluation et les synthèses sont des espaces réservés illustrant, et non des valeurs à copier dans un validateur. Les ID ARM réels policyResourceId et authenticatedProducerResourceId les valeurs sont des ID ARM complets pour la stratégie et le compte de service, respectivement :

{
  "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>"
  }
}

Chaque synthèse réelle contient sha256: 64 caractères hexadécimaux minuscules. evaluatedPolicyLayers peut contenir des couches applicables supplémentaires ; ne supposez pas qu’il y en a toujours un. Vérifiez que la stratégie nommée sélectionnée est présente, conservez les autres couches et appliquez le verdict d’agrégation plutôt que l’autorisation d’une couche individuelle.

Le digest de liaison de requête est le hachage SHA-256 de RFC 8785 canonique UTF-8 JSON pour :

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

La chaîne digest est précédée sha256:de . Utilisez une bibliothèque de canonisation plutôt que de supposer que la sérialisation JSON ordinaire a l’ordre et la représentation numérique requis. L’exemple de client implémente cette vérification.

Le digest lie les métadonnées d’évaluation à une demande ; il ne s’agit pas d’une signature de reçu ou d’une preuve qu’un outil a été exécuté. Conservez-la avec un résultat d’hôte distinct.

Gérer les erreurs

État ou condition HTTP Action
400, InvalidRequest Corrigez le contexte, les types JSON, le jumelage point/cible, le sélecteur ou la taille de charge utile.
401 Vérifiez l’acquisition des informations d’identification, l’audience des jetons et l’expiration.
403 Vérifiez le rôle de plan de données de l’appelant sélectionné, l’étendue du compte, l’accès en préversion et l’autorisation de stratégie.
404, NativeRouteDisabled Vérifiez l’activation du point de terminaison, de la version de l’API, du compte et de la région. Ne passez pas à un format de requête plus ancien en tant que secours automatique.
409, PolicyFenceChanged La stratégie a changé lors de l’évaluation. Rapprochez la version prévue avant une nouvelle tentative limitée.
UnsupportedCapability ou non disponible stratégie/dépendance requise Restaurez la fonctionnalité ou la stratégie requise. Ne pas ignorer sa vérification.
429 Respectez Retry-After la charge fournie et réduisez la charge. Conservez l’action bloquée.
500, erreur 503de transport ou délai d’expiration Conservez l’action bloquée. Réessayez uniquement dans le cadre d’une échéance d’application limitée.
200 avec deny Résultat d’une stratégie, pas un échec de transport. Ne réessayez pas tant qu’elle n’est pas autorisée.
Incompatibilité de verdict ou de réception non valide Ne pas agir. Enregistrez l’échec et examinez.

Les codes d’erreur opérationnels peuvent différer entre les configurations de service. Conservez le code retourné réel, l’état HTTP et les informations de corrélation de requête/évaluation sans journaliser les charges utiles sensibles.

Nouvelles tentatives et quotas

Une seule évaluation peut appeler plusieurs détecteurs ou juges requis. Les limites de compte et les limites de déploiement de modèle sont distinctes ; le nombre de requêtes HTTP d’une évaluation n’établit pas son utilisation interne du détecteur ou de l’inférence.

Utilisez les quotas attribués à votre compte et déploiement de modèle activés lors de la définition de l’accès concurrentiel. Ne supposez pas une limite de requêtes universelles par seconde à partir de ce guide.

Une nouvelle tentative d’évaluation n’est pas autorisée à réessayer une action d’outil non idempotente. Conservez l’action d’origine en attente, les nouvelles tentatives liées par heure et par nombre, et empêchez la distribution en double. Ne réutilisez pas une autorisation précédente pour les arguments modifiés, la sortie modifiée, un point de cycle de vie différent ou une action ultérieure.

Mettre à jour et déployer des stratégies

Publiez de nouvelles versions de stratégie nommées pour un déploiement intermédiaire. Utilisez le remplacement conditionnel uniquement lorsque vous mettez intentionnellement à jour une ressource existante.

Préférer une nouvelle version nommée

Créez une stratégie et une ressource Rego avec un nouveau nom, testez-la et modifiez délibérément le sélecteur configuré de l’application. Par exemple, utilisez publish-policy.ps1:

$Candidate = .\publish-policy.ps1 -AccountId $AccountId `
    -TemplateDirectory .\refund-guard -PolicyName 'refund-guard-v2'

Conservez la version précédente disponible lors du déploiement. Le déplacement du sélecteur est une restauration de configuration ; elle n’annule pas les actions déjà exécutées.

Remplacement conditionnel sur place

Si vous remplacez intentionnellement une stratégie, OBTENez son ETag actuel et utilisez If-Match. L'exemple suivant utilise 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

Utilisez un corps de demande accepté, et non la réponse GET complète avec des champs en lecture seule. Une défaillance de condition préalable nécessite un examen et un rapprochement ; n’effectuez pas une nouvelle tentative de remplacement inconditionnelle.

Les modifications apportées à Rego réutilisables peuvent affecter les stratégies qui le référencent. La publication de nouvelles ressources de source et de stratégie nommées évite de traiter les mises à jour multi-ressources comme une opération atomique.

Les appels de stratégie nommée sélectionnent la stratégie autorisée par ID ; le format de requête indiqué ici n’épingle pas un ETag. Utilisez des versions nommées distinctes pour le déploiement délibéré et enregistrez la révision réelle retournée dans chaque reçu.

Surveiller l’évaluation et l’application

Enregistrer:

  • ID de session, d’action, de point et d’évaluation.
  • ID de ressources de stratégie, révisions et synthèses.
  • Décision et raison, y compris les approbations non résolues.
  • Latence du service, délais d’attente, échecs et limitation.
  • Indique si l’action a été bloquée, distribuée, transformée ou libérée.

Une assertion d’hôte utile est zéro répartition ou mise en production protégée après refus/erreur. Couverture des points de contrôle également ; la gestion parfaite des réponses ne protège pas une action qui n’a jamais appelé le service.

Évitez les invites brutes, les arguments de l’outil, la sortie du modèle, les jetons d’accès et les rubriques de juge dans les journaux de routine. Les métadonnées de reçu sont utiles pour la corrélation, mais elles ne remplacent pas une stratégie de gestion des données.

Supprimer une stratégie et son Rego

  1. Arrêtez ou reconfigurez les clients à l’aide de la stratégie.
  2. Recherchez d’autres références à son Rego réutilisable.
  3. Supprimez la stratégie avec son ETag actuel.
  4. Si la suppression est asynchrone, attendez que l’opération ARM réussisse.
  5. Supprimez Rego uniquement après qu’il n’est plus référencé.

Pour les ressources créées par le script de publication :

.\remove-policy.ps1 -PolicyId $Published.PolicyId -RegoId $Published.RegoId

Le remove-policy.ps1 script vérifie que les deux ID appartiennent au même compte, utilise des ETags, attend des opérations asynchrones et supprime uniquement ces deux ressources. Un conflit ou une suppression ayant échoué est une erreur ; elle ne se poursuit pas par force.

Le script ne supprime pas le compte de service, le compte de modèle, les attributions de rôles ou le groupe de ressources. Passez en revue et supprimez les ressources inutilisées séparément.