AdministrationHooks d'inférence

Configurer les hooks d’inférence

Copy page



Autorisez les hooks d’inférence 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 hooks d’inférence et quand les utiliser, consultez la présentation des hooks d’inférence. 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, que seuls les rôles Propriétaire et Propriétaire principal détiennent. Le rôle Administrateur ne la possède pas.
• 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 redirection. Les hôtes de tunnel inverse (ngrok et les services de tunnel similaires) ne sont pas pris en charge : la politique réseau d’Anthropic les bloque. N’effectuez pas vos tests via un tunnel ; hébergez votre serveur sur un domaine que vous contrôlez. Pour connaître l’ensemble des exigences d’hébergement, et pour créer le serveur et vérifier les requêtes signées, consultez Développer une intégration de hooks d’inférence.

Configurer les hooks d’inférence

Il existe trois états d’application :

• Désactivé : lorsque Appliquer les verdicts est désactivé, votre serveur de sécurité IA n’est jamais contacté et les prompts ne sont pas inspectés.
• Mode fantôme : lorsque Appliquer les verdicts est activé et que Mode est défini sur Mode fantôme, votre serveur de sécurité IA reçoit les prompts et renvoie des verdicts, et rien n’est bloqué.
• Application active : lorsque Appliquer les verdicts est activé et que Mode est défini sur Autoriser la demande ou Bloquer la requête, 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 hooks d’inférence pour votre organisation

   Accédez à claude.ai > Paramètres de l’organisation > Données et confidentialité et trouvez la section Hooks d’inférence. Activez Autoriser pour votre organisation.

   L’activation de cette option déverrouille la page de paramètres des hooks d’inférence et force toujours Appliquer les 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 Appliquer les verdicts à la dernière étape.

2. 2

   Ouvrir la page de paramètres Hooks d’inférence

   Toujours dans Données et confidentialité, ouvrez la section Hooks d’inférence pour accéder à la page des paramètres des hooks d’inférence. Elle se trouve sous Données et confidentialité plutôt que sous sa propre entrée dans la navigation des paramètres, c’est pourquoi son fil d’Ariane indique Données et confidentialité / Hooks d’inférence. Tant que vous n’avez pas enregistré de point de terminaison, la page signale que les prompts ne sont pas encore inspectés, et Appliquer les verdicts reste désactivé avec un badge Point de terminaison requis.

3. 3

   Configurer votre point de terminaison

   Cliquez sur Configurer pour ouvrir la boîte de dialogue Configurer l’endpoint et saisissez l’URL du point de terminaison : l’URL https:// qui reçoit les requêtes de verdict. Seules les URL https:// sont acceptées.

   La boîte de dialogue ne demande rien d’autre à ce stade : les en-têtes de requête personnalisés interviennent à l’étape 5, et la gestion des défaillances à l’étape 6. Cliquez sur Suivant pour enregistrer. Une fois un point de terminaison enregistré, le bouton indique Modifier.

4. 4

   Conserver votre secret de signature

   Le premier enregistrement génère votre « signing secret » (secret de signature) de webhook et l’affiche une seule fois. Copiez-le et conservez-le en lieu sûr avant de cliquer sur Suivant : 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, y compris le test de connexion de l’étape suivante. Pour la procédure de vérification, consultez Vérifier la signature.

5. 5

   Ajouter des en-têtes de requête et tester la connexion

   Cliquer sur Suivant dans la boîte de dialogue du secret de signature rouvre la boîte de dialogue du point de terminaison, désormais dotée de deux contrôles supplémentaires :

   • En-têtes de requête personnalisés : 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 saisir à nouveau 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 à une nouvelle destination ; saisissez-les à nouveau 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 cookies, 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.
   • Tester la connexion : 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 ; saisissez donc à nouveau toutes les valeurs d’en-têtes stockées 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 un comportement par défaut consistant à tout refuser avant que vous ne commenciez à appliquer les verdicts. Il affiche également le temps d’aller-retour mesuré par Anthropic pour cette unique requête de test, sur une nouvelle connexion, y compris la négociation de connexion.

   Cliquez sur Enregistrer pour enregistrer les en-têtes que vous avez saisis.

   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 de l’URL est une adresse IP privée ou interne, une adresse IPv6 ou localhost. Utilisez un hôte routable publiquement.
   Délai d’attente 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é, ou le nom d’hôte se résout en une adresse privée.
   Statut autre que 200	Le serveur de sécurité IA a répondu avec un statut autre que 200. Les verdicts doivent être renvoyés 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.
   Secret de signature requis	Votre organisation n’a pas de secret de signature, le test serait donc envoyé sans signature. Cliquez sur Générer un secret sous Signature des requêtes, puis testez à nouveau.

6. 6

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

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

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

   La troisième option du menu déroulant, Mode fantôme, est un outil de déploiement progressif plutôt qu’une politique de défaillance ; consultez Mode fantôme.

   Définissez ensuite Délai d’expiration du verdict de prompt (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 Autoriser la demande et 5 000 ms.

7. 7

   Choisir un pourcentage de déploiement

   Sous Déploiement, définissez Requêtes inspectées (%) 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 Bloquer la requête.

8. 8

   Activer « Appliquer les verdicts »

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

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

   Validate tool calls, sous Appliquer les verdicts, envoie également les appels d’outils de chacune des réponses de Claude à votre serveur de sécurité IA et attend son verdict avant leur exécution ; consultez La trame d’appel d’outil. Cette option est activée par défaut dans une nouvelle configuration. Elle n’a aucun effet tant que Appliquer les verdicts est désactivé, et une modification de cette option met environ une minute à atteindre tous les serveurs d’Anthropic, comme pour Appliquer les verdicts.

Mode fantôme

Le 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 application active, 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 à appliquer les verdicts. Avec Validate tool calls activé, votre serveur reçoit également les trames d’appel d’outil en mode shadow, et aucun appel d’outil n’est bloqué.

Pour utiliser le mode shadow, définissez Mode sur Mode fantôme sous Gestion des échecs, puis activez Appliquer les 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 Mode fantôme — aucun blocage. Pour quitter le mode shadow, redéfinissez Mode sur Autoriser la demande ou Bloquer la requête ; les verdicts sont de nouveau appliqués dès que l’application est activée.

Exclusions

Sous Who is inspected, lorsque Limit by role est activé, sélectionnez les rôles dont les membres ne sont pas couverts par les hooks d’inférence : 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. Sélectionnez-les dans le sélecteur de rôles, dont le texte indicatif affiche Sélectionner les rôles à exclure, et gérez les titulaires de chaque rôle depuis la page d’administration des rôles (Gérer les rôles) ; 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 régie est inspectée, sauf si Inspecter est défini sur Only selected roles.

L’exclusion s’applique aux sessions interactives d’un utilisateur. Les modifications de la liste d’exclusion sont enregistrées dans le flux d’activité de votre organisation en tant que modifications d’autorisations de rôle (rbac_role_permission_added et rbac_role_permission_removed).

Inspecter uniquement les rôles sélectionnés

Tout le contenu de la section Who is inspected dépend d’un seul interrupteur, Limit by role. Lorsque vous activez l’interrupteur, Inspecter est d’abord défini sur Everyone except excluded roles, et les rôles exclus sont sélectionnés en dessous comme décrit ci-dessus.

Pour essayer d’abord les hooks d’inférence sur une partie de votre organisation, activez Limit by role, définissez Inspecter sur Only selected roles et sélectionnez les rôles dans la boîte de dialogue qui s’ouvre. À partir de là, seuls les membres dont le rôle est défini sur Rôles personnalisés et à qui un rôle sélectionné est attribué sont inspectés. Les membres dont le rôle est défini sur une autre valeur, comme Utilisateur ou Propriétaire, ne sont pas inspectés, même si un rôle sélectionné leur est attribué. Cela vous inclut si votre rôle est défini sur Propriétaire ou Propriétaire principal. Supprimez tous les rôles exclus avant de basculer : une organisation utilise soit des exclusions, soit des rôles sélectionnés, pas les deux. Après la bascule, ajoutez ou supprimez des rôles dans le sélecteur de rôles sous Inspecter. Pour revenir à l’inspection de tout le monde, désactivez Limit by role : après votre confirmation, cela supprime tous les rôles exclus et désactive Only selected roles.

Lorsque Only selected roles est défini :

• Un rôle personnalisé dont l’Accès aux capacités est Toutes les capacités ou Tout généralement disponible n’est pris en compte que si vous le sélectionnez, comme tout autre rôle.
• Si aucun membre dont le rôle est défini sur Rôles personnalisés ne se voit attribuer un rôle sélectionné, aucun membre n’est inspecté.
• Les requêtes qui ne sont associées à aucun membre ne sont pas inspectées, comme les requêtes effectuées avec des clés API et les conversations Claude Tag dans Slack.

Les modifications du paramètre Inspecter et des rôles inspectés sont enregistrées dans le flux d’activité de votre organisation.

Message personnalisé pour invite bloquée

Sous Message personnalisé pour invite bloquée, 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 hooks d’inférence affiche :

• Statut de l’endpoint : Opérationnel, Déclenché, Non appliqué, ou Non configuré avant l’enregistrement d’un point de terminaison.
• Échecs par minute : les échecs de webhook sur les 2 dernières minutes, en moyenne.
• Taux de blocage : les refus en proportion des verdicts de votre serveur de sécurité IA, affiché lorsque le pourcentage de déploiement est inférieur à 100.
• Disjoncteur déclenché : le moment du dernier déclenchement du disjoncteur, le cas échéant.
• Erreurs récentes : chaque entrée indique quand l’échec s’est produit, un type d’erreur et une catégorie. La catégorie est webhook_error pour un problème lié à votre point de terminaison ou à la connexion à celui-ci, ou relay_error pour un échec au sein des systèmes d’Anthropic. Une entrée DlpWebhookStatusError peut également indiquer le statut HTTP renvoyé par votre serveur de sécurité IA et la taille du corps de la requête envoyée par Anthropic, par exemple HTTP 413 · 1.3 MB. Les entrées n’incluent jamais le contenu des requêtes ni l’URL de votre point de terminaison. La liste conserve les 10 échecs les plus récents et est effacée une heure après le dernier.

Les types d’erreur d’Erreurs récentes signifient :

En mode shadow, aucune erreur ne compte pour le disjoncteur.

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. Échecs par 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 Disjoncteur déclenché 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 Gestion des échecs s’applique à chaque requête inspectée. Avec Bloquer la requête 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 enregistré dans le flux d’activité de votre organisation en tant qu’activité inference_hooks_circuit_breaker_tripped, afin que votre équipe de sécurité ou votre fournisseur puisse recevoir des alertes sur les déclenchements à partir de la surveillance déjà en place, comme un SIEM qui ingère le flux. Une activité est enregistrée pour chaque déclenchement, et non pour chaque requête affectée. L’enregistrement 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 Appliquer les 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 vérifie si votre serveur est rétabli en lui envoyant une requête de test en arrière-plan, au maximum environ une fois par minute ; aucune requête utilisateur n’est impliquée. Si votre serveur répond avec un verdict valide, d’autorisation ou de refus, le disjoncteur se réinitialise et l’application reprend. Sinon, le disjoncteur reste déclenché et les vérifications se poursuivent.

La récupération automatique ne fonctionne que tant que vos paramètres de hooks d’inférence n’ont pas été modifiés depuis le déclenchement. Si vous modifiez un paramètre de hooks d’inférence après un déclenchement, y compris en renouvelant le secret de signature, les vérifications s’arrêtent et le disjoncteur ne se réinitialise plus de lui-même ; réactivez Appliquer les verdicts une fois votre serveur corrigé. La récupération automatique ne s’applique qu’aux déclenchements : si vous désactivez vous-même Appliquer les verdicts, l’application reste désactivée jusqu’à ce que vous la réactiviez.

Renouveler votre secret de signature

Cliquez sur Renouveler le secret sous Signature des requêtes pour remplacer votre secret de signature. Si votre organisation n’a pas encore de secret, le même bouton indique Générer un secret et crée le premier. Le renouvellement est une bascule immédiate : le nouveau secret est généré et affiché 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’existe donc aucune période de chevauchement sur laquelle s’appuyer.

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 hooks d’inférence est enregistré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 faute de verdict. Ce dernier type n’est enregistré que lorsque Appliquer les verdicts est activé et que Mode est Autoriser la demande. Son motif est endpoint_timeout, endpoint_error pour tout autre problème lors de l’appel à votre serveur de sécurité IA, ou internal_error pour un échec du côté d’Anthropic. Avec Bloquer la requête ou Mode fantôme, les requêtes en échec ne sont pas enregistrées individuellement. Le rétablissement automatique du disjoncteur n’est enregistré dans aucun mode. Tant que le disjoncteur est déclenché, aucune activité de hooks d’inférence par requête n’est enregistré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 hooks d’inférence

Il existe deux niveaux de désactivation :

• Appliquer les verdicts désactivé, sur la page des paramètres des hooks d’inférence : 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 avec l’ancien paramètre. La page des paramètres reste disponible ; utilisez donc cette option pour suspendre l’application pendant que vous travaillez sur votre serveur de sécurité IA.
• Autoriser pour votre organisation désactivé, dans les paramètres Données et confidentialité : les prompts ne sont plus inspectés, et les paramètres des hooks d’inférence 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 Appliquer les verdicts à l’état désactivé et réinitialise un disjoncteur déclenché ; réactivez donc l’application lorsque vous êtes prêt.

Étapes suivantes