AdministrationHooks d'inférence

Configurer les Inference hooks

Copy page



Autorisez les Inference hooks pour votre organisation Claude Enterprise, connectez votre serveur de sécurité IA et contrôlez l'application des verdicts, la gestion des échecs et le déploiement progressif.

Les « Inference hooks » (hooks d'inférence) envoient les prompts de votre organisation à un serveur de sécurité IA de votre choix et retiennent chaque requête en attente d'un verdict d'autorisation ou de refus avant que Claude ne la traite. Cette page vous guide pour activer la fonctionnalité, connecter votre serveur et contrôler l'application des verdicts. Pour savoir ce que sont les Inference hooks et quand les utiliser, consultez la présentation des Inference hooks. Pour construire le serveur de sécurité IA lui-même, consultez Développer une intégration Inference hooks.

Avant de commencer

Vous avez besoin de :

• L'autorisation organization:manage dans claude.ai. Les rôles intégrés Admin, Owner et Primary owner la détiennent, ainsi que tout rôle personnalisé auquel elle a été accordée.
• Un point de terminaison HTTPS de serveur de sécurité IA qui accepte les requêtes de verdict : une URL https:// sur le port 443, sur un hôte routable publiquement, accessible sans redirections. Les hôtes à tunnel inverse (ngrok et services de tunnel similaires) ne sont pas pris en charge : la politique réseau d'Anthropic les bloque. Ne testez pas via un tunnel ; hébergez votre serveur sur un domaine que vous contrôlez. Pour l'ensemble des exigences d'hébergement, et pour construire le serveur et vérifier les requêtes signées, consultez Développer une intégration Inference hooks.

Configurer les Inference hooks

Il existe trois états d'application : désactivé (Enforce verdicts est désactivé : votre serveur de sécurité IA n'est jamais contacté et les prompts ne sont pas inspectés), shadow (Enforce verdicts est activé avec Mode défini sur Shadow mode : votre serveur de sécurité IA reçoit les prompts et renvoie des verdicts, et rien n'est bloqué), et application active (Enforce verdicts est activé avec Mode défini sur Allow the request ou Block the request : un refus bloque la requête). Les étapes suivantes font passer une nouvelle configuration de l'état désactivé à l'application active.

1. 1

   Autoriser les Inference hooks pour votre organisation

   Accédez à claude.ai > Organization settings > Data and privacy et trouvez la section Inference hooks. Activez Allow for your organization.

   L'activation de cette option déverrouille la page de paramètres des Inference hooks et force toujours Enforce verdicts à l'état désactivé, de sorte qu'autoriser la fonctionnalité ne démarre jamais l'inspection par elle-même : même une configuration dont l'application était auparavant activée reste non inspectée jusqu'à ce que vous réactiviez Enforce verdicts à la dernière étape.

2. 2

   Ouvrir la page de paramètres des Inference hooks

   Toujours dans Data and privacy, ouvrez la section Inference hooks pour accéder à la page de paramètres des Inference hooks. Elle se trouve sous Data and privacy plutôt que comme entrée distincte dans la navigation des paramètres, de sorte que son fil d'Ariane indique Data and privacy / Inference hooks. Tant que vous n'avez pas enregistré de point de terminaison, la page avertit que les prompts ne sont pas encore inspectés, et Enforce verdicts reste désactivé avec un badge Requires endpoint.

3. 3

   Configurer votre point de terminaison

   Cliquez sur Configure pour ouvrir la boîte de dialogue Configure endpoint et renseignez :

   • Endpoint URL : l'URL https:// qui reçoit les requêtes de verdict. Seules les URL https:// sont acceptées.
   • Custom request headers : jusqu'à 16 en-têtes statiques envoyés avec chaque requête de verdict afin que votre serveur de sécurité IA puisse authentifier l'appelant. Les valeurs des en-têtes sont stockées chiffrées et ne sont plus jamais affichées ; après l'enregistrement, seuls les noms des en-têtes sont affichés. Comme les valeurs sont en écriture seule, l'enregistrement de toute modification des en-têtes nécessite de ressaisir chaque valeur. La modification de l'URL du point de terminaison efface toutes les valeurs d'en-têtes stockées afin que vos identifiants ne soient jamais envoyés vers une nouvelle destination ; ressaisissez-les après un changement d'URL. Les noms d'en-têtes doivent utiliser les caractères de jeton HTTP standard avec - plutôt que _, et ne doivent pas entrer en conflit avec les noms réservés (en-têtes de cadrage de requête tels que Content-* et Host, en-têtes de proxy et de cookie, en-têtes d'adresse client tels que X-Forwarded-*, les en-têtes de signature webhook-* et le préfixe X-Anthropic-*). Les valeurs doivent être en ASCII imprimable.

   La boîte de dialogue ne couvre que ces deux champs plus Test connection ; elle ne demande rien concernant la gestion des échecs, que vous choisissez à l'étape 6. Une fois un point de terminaison enregistré, le bouton indique Edit.

4. 4

   Tester la connexion

   Cliquez sur Test connection. Claude envoie un prompt de test synthétique à l'URL et aux en-têtes actuellement présents dans le formulaire, et non aux valeurs enregistrées ; ressaisissez donc toute valeur d'en-tête stockée avant de tester. En cas de succès, le résultat indique si votre serveur de sécurité IA a renvoyé un verdict d'autorisation ou de refus pour le prompt de test, ce qui révèle une configuration par défaut refusant tout avant que vous ne commenciez l'application.

   Résultats d'échec courants :

   Résultat	Ce qu'il faut vérifier
   URL rejetée	L'URL a échoué à une vérification structurelle. Utilisez une URL https:// sur le port 443.
   IP privée ou interne	L'hôte se résout en une adresse privée ou interne. Utilisez un hôte routable publiquement.
   Délai dépassé	Le serveur de sécurité IA n'a pas renvoyé de verdict dans le délai imparti.
   Erreur de transport	La résolution DNS, la négociation TLS ou la connexion a échoué.
   Statut autre que 200	Le serveur de sécurité IA a répondu avec un statut autre que 200. Les verdicts doivent revenir en HTTP 200 ; les redirections ne sont pas suivies et comptent comme des échecs.
   Réponse non analysable	Le serveur de sécurité IA a répondu, mais le corps n'est pas un verdict valide.

5. 5

   Enregistrer et conserver votre secret de signature

   Enregistrez la configuration du point de terminaison. Le premier enregistrement génère votre secret de signature de webhook et le révèle une seule fois. Copiez-le et conservez-le en lieu sûr avant de fermer la boîte de dialogue : le secret ne peut pas être récupéré ultérieurement, seulement renouvelé.

   Votre serveur de sécurité IA utilise ce secret pour vérifier la signature de chaque requête qu'il reçoit. Pour la procédure de vérification, consultez Vérifier la signature.

6. 6

   Choisir la gestion des échecs et le délai d'expiration

   Sous Failure handling, définissez Mode pour choisir ce qui se passe lorsque le serveur de sécurité IA est injoignable ou que les verdicts expirent :

   • Block the request : arrêter l'inférence lorsque votre serveur de sécurité IA ne peut pas fournir de verdict (échec fermé).
   • Allow the request : laisser la requête parvenir au modèle sans inspection (échec ouvert).

   La troisième option de la liste déroulante, Shadow mode, est un outil de déploiement plutôt qu'une politique d'échec ; consultez Mode shadow.

   Définissez ensuite Prompt verdict timeout (ms) : de 1 à 10 000 ms, avec une valeur par défaut de 5 000 ms. Ce budget couvre l'intégralité de l'échange, et un verdict plus lent compte comme un serveur injoignable ; définissez donc la valeur la plus basse que votre serveur peut respecter de manière fiable.

   Les modifications de cette section s'enregistrent au fur et à mesure que vous les effectuez. Lors du premier enregistrement, les valeurs par défaut sont Allow the request et 5 000 ms.

7. 7

   Choisir un pourcentage de déploiement

   Sous Rollout, définissez Requests inspected (%) pour exécuter l'inspection sur un pourcentage des requêtes pendant que vous mettez en service votre serveur de sécurité IA. La valeur va de 0 à 100 : 100 inspecte tout, et 0 désactive l'inspection.

   Chaque requête est tirée au sort une seule fois pour l'ensemble de son tour de conversation, de sorte qu'une même conversation peut être partiellement inspectée d'un tour à l'autre. Les requêtes hors du pourcentage échantillonné se poursuivent sans inspection, même lorsque la gestion des échecs est définie sur Block the request.

8. 8

   Activer Enforce verdicts

   Pour évaluer les verdicts sur le trafic réel sans bloquer personne dans un premier temps, définissez Mode sur Shadow mode (étape 6) avant d'activer l'application ; consultez Mode shadow.

   Activez Enforce verdicts pour conditionner Claude au verdict de votre serveur de sécurité IA pour chaque prompt gouverné, puis confirmez dans la boîte de dialogue, qui rappelle votre choix de gestion des échecs. Prévoyez environ une minute pour que la modification atteigne tous les serveurs d'Anthropic ; les requêtes déjà en cours se terminent selon l'ancien paramètre. La désactivation arrête l'envoi des prompts à votre serveur de sécurité IA, là encore en environ une minute ; votre configuration est conservée.

Mode shadow

Le « shadow mode » (mode shadow) exécute votre hook sur le trafic réel sans rien bloquer. Votre serveur de sécurité IA reçoit les prompts gouvernés et renvoie des verdicts exactement comme il le ferait en mode d'application, mais rien n'est bloqué : chaque requête parvient au modèle, même lorsque votre serveur la refuse ou est injoignable, et l'utilisateur final ne voit rien. Utilisez-le pour ajuster votre politique sur le trafic réel de votre organisation avant de commencer l'application.

Pour utiliser le mode shadow, définissez Mode sur Shadow mode sous Failure handling, puis activez Enforce verdicts afin que les prompts soient transmis à votre serveur de sécurité IA. Tant qu'il est actif, la page de paramètres affiche un badge Shadow mode — not blocking. Pour quitter le mode shadow, redéfinissez Mode sur Allow the request ou Block the request ; les verdicts sont de nouveau appliqués dès que l'application est activée.

Exclusions

Sous Exclusions, sélectionnez les rôles dont les membres ne sont pas couverts par les Inference hooks : leurs prompts ne sont jamais envoyés à votre serveur de sécurité IA. Seuls les rôles personnalisés créés par votre organisation peuvent être exclus ; les rôles intégrés ne sont pas proposés. Choisissez-les dans le sélecteur de rôles, dont le texte indicatif indique Select roles to exclude, et gérez qui détient chaque rôle depuis la page d'administration des rôles (Manage roles) ; la modification des exclusions nécessite l'autorisation de gestion des identités. La liste est vide par défaut et, sans rôle exclu, chaque requête gouvernée est inspectée.

L'exclusion s'applique aux sessions interactives d'un utilisateur ; le trafic authentifié par des identifiants machine est toujours inspecté. Si Claude ne peut pas déterminer l'appartenance d'un demandeur à un rôle, la requête échoue en mode fermé avec une erreur réessayable plutôt que de se poursuivre sans inspection. Les modifications de la liste d'exclusion sont consignées dans la piste d'audit.

Message personnalisé de prompt bloqué

Sous Custom blocked prompt message, définissez un texte personnalisé de 500 caractères maximum qui est ajouté à l'erreur qu'un utilisateur final voit lorsque votre serveur de sécurité IA refuse une requête (généralement qui contacter ou où demander une exception). Le message final est constitué du deny_reason par requête de votre serveur de sécurité IA (lorsqu'il est présent), d'une ligne vide, puis de ce texte. Sans texte personnalisé configuré, un message par défaut intégré invite l'utilisateur à contacter ses administrateurs ; vous pouvez également désactiver entièrement le message ajouté afin que l'utilisateur ne voie que le deny_reason.

Surveiller votre serveur de sécurité IA

La zone d'état du point de terminaison de la page de paramètres des Inference hooks affiche :

• Endpoint status : Healthy, Tripped, Not enforcing, ou Not configured avant l'enregistrement d'un point de terminaison.
• Failures per minute : les échecs de webhook sur les deux dernières minutes, en moyenne.
• Block rate : les refus en proportion des verdicts de votre serveur de sécurité IA, affiché tant que le pourcentage de déploiement est inférieur à 100.
• Circuit breaker tripped : la date du dernier déclenchement du disjoncteur, le cas échéant.
• Recent errors : chaque entrée est réduite à un horodatage, un type d'erreur et une raison sur une ligne. Les entrées n'incluent jamais le contenu des requêtes ni l'URL de votre point de terminaison.

Le panneau fonctionne au mieux : si Anthropic ne peut pas lire les compteurs, il affiche zéro échec et aucune erreur plutôt qu'une erreur propre, de sorte qu'un panneau d'apparence saine ne prouve pas à lui seul que votre serveur de sécurité IA est sain. Failures per minute compte chaque échec, y compris les erreurs réseau et DNS qui ne déclenchent jamais le disjoncteur, et peut donc être élevé alors que Circuit breaker tripped reste vide.

Disjoncteur

Des échecs de webhook persistants imputables à votre serveur de sécurité IA déclenchent le « circuit breaker » (disjoncteur), ce qui arrête l'application : votre serveur n'est plus contacté, et votre choix de Failure handling s'applique à chaque requête inspectée. Avec Block the request sélectionné, les utilisateurs de votre organisation sont bloqués jusqu'à la réinitialisation du disjoncteur. Lorsque le disjoncteur se déclenche, les administrateurs sont également avertis dans le centre de notifications de claude.ai.

Chaque déclenchement est également consigné dans le flux d'activité de votre organisation sous la forme d'une activité inference_hooks_circuit_breaker_tripped, afin que votre équipe de sécurité ou votre fournisseur puisse générer des alertes sur les déclenchements à partir de la surveillance qu'ils exploitent déjà, comme un SIEM qui ingère le flux. Une activité est consignée par déclenchement, et non une par requête affectée. La consignation nécessite que la Compliance API soit activée pour votre organisation ; consultez Configurer la Compliance API.

Pour rétablir le service, corrigez le serveur, puis réactivez Enforce verdicts pour réinitialiser le disjoncteur.

Le disjoncteur peut également se réinitialiser de lui-même. À partir de 10 minutes après le déclenchement, Anthropic teste si votre serveur s'est rétabli : au plus environ une fois par minute, une requête issue du trafic normal de votre organisation est envoyée à votre serveur pour inspection, et cette requête se poursuit pour son utilisateur, que votre serveur réponde ou non. Si votre serveur répond avec un verdict valide, autorisation ou refus, le disjoncteur se réinitialise et l'application reprend. Tout autre résultat est un échec de webhook : le disjoncteur reste déclenché et les tests continuent.

La récupération automatique ne fonctionne que tant que vos paramètres Inference hooks sont inchangés depuis le déclenchement. Si vous modifiez un paramètre Inference hooks après un déclenchement, y compris en renouvelant le secret de signature, les tests s'arrêtent et le disjoncteur ne se réinitialise plus de lui-même ; réactivez Enforce verdicts lorsque votre serveur est corrigé. La récupération automatique ne s'applique qu'aux déclenchements : si vous désactivez vous-même Enforce verdicts, l'application reste désactivée jusqu'à ce que vous la réactiviez.

Renouveler votre secret de signature

Cliquez sur Rotate secret sous Request signing pour remplacer votre secret de signature. Le renouvellement est une bascule immédiate : le nouveau secret est généré et révélé une seule fois, l'ancien secret ne peut plus être récupéré, et aucune requête n'est jamais signée avec les deux secrets ; il n'y a donc aucune période de chevauchement sur laquelle compter.

Des requêtes signées avec le secret précédent peuvent encore arriver brièvement après le renouvellement ; Vérifier la signature explique comment votre serveur de sécurité IA doit gérer la transition.

Piste d'audit

L'activité des Inference hooks est consignée dans le flux d'activité de votre organisation : modifications de configuration, refus, déclenchements du disjoncteur et requêtes qui se sont poursuivies sans inspection selon votre paramètre de gestion des échecs. Tant que le disjoncteur est déclenché, aucune activité Inference hooks par requête n'est consignée ; l'activité de déclenchement constitue l'enregistrement de cette période dans le flux. Les enregistrements de refus comportent des identifiants qui vous permettent de rapprocher chaque refus de l'enregistrement correspondant dans votre propre système.

Désactiver les Inference hooks

Il existe deux niveaux de désactivation :

• Enforce verdicts désactivé, sur la page de paramètres des Inference hooks : en environ une minute, les prompts de votre organisation cessent d'être envoyés à votre serveur de sécurité IA ; les requêtes déjà en cours se terminent selon l'ancien paramètre. La page de paramètres reste disponible ; utilisez donc cette option pour suspendre l'application pendant que vous travaillez sur votre serveur de sécurité IA.
• Allow for your organization désactivé, dans les paramètres Data and privacy : les prompts ne sont plus inspectés, et les paramètres des Inference hooks deviennent indisponibles jusqu'à ce que vous le réactiviez. La configuration de votre point de terminaison, vos en-têtes personnalisés et votre secret de signature sont conservés dans les deux cas ; la réactivation force Enforce verdicts à l'état désactivé et réinitialise un disjoncteur déclenché ; réactivez donc l'application lorsque vous êtes prêt.

Étapes suivantes