AI Guardrails On Demand - Netskope Documentation technique

AI Guardrails On Demand vous permet de scanner en temps réel les invites et réponses IA grâce à des moteurs de détection AI Guardrails en utilisant une API provenant directement de passerelles IA ou d’agents IA tiers existants ou prédéployés. Vous pouvez alors exploiter votre infrastructure existante pour effectuer l’application de la loi.

AI Guardrails On Demand est proposé sous forme de VM pouvant être déployée dans vos environnements locaux et VPC. Il est également disponible de deux façons :

Hébergé par votre organisation
Hébergé par Netskope

Il s'agit d'une fonction bêta. Contactez le service d'assistance de Netskope ou votre représentant commercial pour activer cette fonction pour votre locataire.

Configuration d’un modèle de service pour AI Guardrails

Votre service AI Guardrails hébergé utilise le cadre de modèles de service Virtual Private Edge Netskope pour fonctionner.

Pour configurer un modèle de service pour AI Guardrails, voir Configurer Virtual Private Edge.

Spécifications API

Voici les points d’accès API que vous pouvez utiliser :

POST /api/v2/aiguardrails/evaluation

Évalue un texte (prompt ou réponse) par rapport aux profils AI Guardrail configurés et renvoie un verdict indiquant si une politique est correspondante.

Variables de requête

Paramètres	Type	Required	Description
`text`	string	Oui	Le contenu textuel que vous souhaitez inspecter par AI Guardrails.
`profiles`	string	Oui	Une application où la clé doit être `"ai-guardrails"` et dont la valeur est une liste non vide de noms de profil configurée dans le AI Guardrails.
`activity`	string	Non	Indique si le texte est une invite utilisateur ou une réponse IA. Par défaut, c’est `"prompt"`.
`eventMeta`	string	Non	Les métadonnées attachées à l’événement de détection généré. Voici les sous-domaines : `mode` (chaîne) — Mode de traitement. Par défaut, c’est `"ai-guardrails"`. `accessMethod` (chaîne) — Identifiant de méthode d’accès. Par défaut, c’est `"ai-explicit"`. `url` (chaîne) — URL de l’application d’IA en amont accédée. `app` (chaîne) — Le nom de l’application cloud (par exemple, « ChatGPT », « Google Bard »). `userId` (chaîne) — L’identifiant utilisateur associé à la requête.

Variables de réponse

Paramètres	Type	Required	Description
`transactionId`	string	Oui	Un identifiant unique pour cette évaluation.
`status`	string	Oui	`"Complete"` en cas de succès, `"Failed"` sur une erreur interne.
`verdict`	string	Oui	`"Match"` si une règle de profil était déclenchée ; `"Not Match"` autrement.
`text`	string	Non	Le texte d’entrée original qui n’est inclus que lorsque l’option de configuration `storeTexts` de service est activée.
`failureReason`	string	Non	Présent uniquement lorsque le statut est `"Failed"`. Décrit la raison de l’échec.
`matchDetails`	array	Non	Présent uniquement lorsque le verdict est `"Match"`. Chaque entrée contient : `profileMatched` (ficelle) — Le nom de profil correspondant. `profileDetails` (antenne) — Liste des détails de détection : `category` (chaîne) — Nom de la catégorie de détection. `confidence` (chaîne) — Niveau de confiance du match (par exemple, `"high"`, `"medium"`, `"low"`). `keywordMatched` (chaîne) — Mots-clés séparés par virgules qui ont déclenché la correspondance. `matchedText` (chaîne) — Contenu textuel séparé par virgules qui a déclenché la correspondance.

Error Codes

Code d'erreur	Error Message	Description
400	INVALID_JSON VALIDATION_FAILED	Échec de corps JSON invalide ou de validation (par exemple, clé de profil inconnue ou liste de profils vide).
501	INTERNAL_ERROR	Endpoint n’est disponible que sur les cibles de déploiement de la plateforme et de l’appliance.
503	CONFIG_ERROR	Service non prêt — Le `tenant_id` n’a pas encore été configuré.

Demande d’exemple

POST /api/v2/aiguardrails/evaluation
Content-Type: application/json
X-Netskope-Request-Id: <string, optional — propagated to response metadata>
X-Netskope-Transaction-Id: <string, optional — upstream gateway transaction ID for tracing>
{
  "text": "<string, required — the text content to evaluate>",
  "profiles": {
    "ai-guardrails": ["<profile_name_1>", "<profile_name_2>"]
  },
  "activity": "<string, optional — 'prompt' (default) | 'response'>",
  "eventMeta": {
    "mode": "<string, optional — default 'ai-guardrails'>",
    "accessMethod": "<string, optional — default 'ai-explicit'>",
    "url": "<string, optional — URL of upstream AI app>",
    "app": "<string, optional — application name>",
    "userId": "<string, optional — user identifier>"
  }
}

Exemple de réponse

HTTP 200 OK
Content-Type: application/json
x-netskope-audit-log-object: {"audit_log_event":"Rest API V2 Call","severity_level":6,"data_type":"ais guardrails evaluation","data_values":[200,"POST","/api/v2/aiguardrails/evaluation"]}
{
  "success": true,
  "metadata": {
    "requestId": "1717506269.b664302b190bb9987e04774bfb62367d"
  },
  "data": {
    "transactionId": "4611686018427387903",
    "status": "Complete",
    "verdict": "Match",
    "text": "<echoed input text, present if 'store_texts' is enabled>",
    "matchDetails": [
      {
        "profileMatched": "my-guardrail-profile",
        "profileDetails": [
          {
            "category": "prompt-injection",
            "confidence": "high",
            "keywordMatched": "",
            "matchedText": ""
          }
        ]
      }
    ]
  }
}

GET /api/v2/aiguardrails/evaluations

Liste les soumissions d’évaluation dans une plage de temps donnée. Ce point de terminaison vous permet de récupérer les résultats historiques des évaluations pour l’audit et l’observabilité.