AmministrazioneHook di inferenza

Configurare gli Inference hooks

Copy page



Consenti gli Inference hooks per la tua organizzazione Claude Enterprise, collega il tuo server di sicurezza AI e controlla l'applicazione dei verdetti, la gestione degli errori e il rollout.

Gli Inference hooks inviano i prompt della tua organizzazione a un server di sicurezza AI di tua scelta e trattengono ogni richiesta in attesa di un verdetto di autorizzazione (allow) o rifiuto (deny) prima che Claude la elabori. Questa pagina illustra come attivare la funzionalità, collegare il tuo server e controllare l'applicazione dei verdetti. Per sapere cosa sono gli Inference hooks e quando usarli, consulta la panoramica degli Inference hooks. Per costruire il server di sicurezza AI stesso, consulta Sviluppare un'integrazione Inference hooks.

Prima di iniziare

Ti servono:

• Il permesso organization:manage in claude.ai. I ruoli integrati Admin, Owner e Primary owner lo detengono, così come qualsiasi ruolo personalizzato a cui sia stato concesso.
• Un endpoint HTTPS del server di sicurezza AI che accetti richieste di verdetto: un URL https:// sulla porta 443, su un host instradabile pubblicamente, raggiungibile senza redirect. Gli host reverse-tunnel (ngrok e servizi di tunnel simili) non sono supportati: la policy di rete di Anthropic li blocca. Non eseguire test attraverso un tunnel; ospita il tuo server su un dominio che controlli. Per i requisiti di hosting completi, e per costruire il server e verificare le richieste firmate, consulta Sviluppare un'integrazione Inference hooks.

Configurare gli Inference hooks

Esistono tre stati di applicazione: off (Enforce verdicts è disattivato: il tuo server di sicurezza AI non viene mai contattato e i prompt non vengono ispezionati), shadow (Enforce verdicts è attivato con Mode impostato su Shadow mode: il tuo server di sicurezza AI riceve i prompt e restituisce verdetti, e nulla viene bloccato) ed enforcing (Enforce verdicts è attivato con Mode impostato su Allow the request o Block the request: un deny blocca la richiesta). I passaggi seguenti portano una nuova configurazione da off a enforcing.

1. 1

   Consenti gli Inference hooks per la tua organizzazione

   Vai su claude.ai > Organization settings > Data and privacy e trova la sezione Inference hooks. Attiva Allow for your organization.

   Attivando questa opzione si sblocca la pagina delle impostazioni degli Inference hooks e si forza sempre Enforce verdicts su off, quindi consentire la funzionalità non avvia mai l'ispezione da sola: anche una configurazione che in precedenza aveva l'applicazione attiva resta non ispezionata finché non riattivi Enforce verdicts nell'ultimo passaggio.

2. 2

   Apri la pagina delle impostazioni degli Inference hooks

   Sempre in Data and privacy, apri la sezione Inference hooks per raggiungere la pagina delle impostazioni degli Inference hooks. Si trova sotto Data and privacy anziché come voce autonoma nella navigazione delle impostazioni, quindi il suo breadcrumb riporta Data and privacy / Inference hooks. Finché non salvi un endpoint, la pagina avvisa che i prompt non vengono ancora ispezionati, e Enforce verdicts resta disattivato con un badge Requires endpoint.

3. 3

   Configura il tuo endpoint

   Fai clic su Configure per aprire la finestra di dialogo Configure endpoint e compila:

   • Endpoint URL: l'URL https:// che riceve le richieste di verdetto. Sono accettati solo URL https://.
   • Custom request headers: fino a 16 header statici inviati con ogni richiesta di verdetto affinché il tuo server di sicurezza AI possa autenticare il chiamante. I valori degli header vengono memorizzati cifrati e non vengono mai più mostrati; dopo il salvataggio, vengono visualizzati solo i nomi degli header. Poiché i valori sono in sola scrittura, salvare qualsiasi modifica agli header richiede di reinserire ogni valore. Modificare l'URL dell'endpoint cancella tutti i valori degli header memorizzati, così le tue credenziali non vengono mai inviate a una nuova destinazione; reinseriscile dopo una modifica dell'URL. I nomi degli header devono usare i caratteri token HTTP standard con - anziché _, e non devono entrare in conflitto con nomi riservati (header di framing della richiesta come Content-* e Host, header di proxy e cookie, header di indirizzo client come X-Forwarded-*, gli header di firma webhook-* e il prefisso X-Anthropic-*). I valori devono essere ASCII stampabile.

   La finestra di dialogo copre solo questi due campi più Test connection; non chiede nulla sulla gestione degli errori, che scegli al passaggio 6. Una volta salvato un endpoint, il pulsante riporta Edit.

4. 4

   Testa la connessione

   Fai clic su Test connection. Claude invia un prompt di test sintetico all'URL e agli header attualmente presenti nel modulo, non ai valori salvati, quindi reinserisci eventuali valori di header memorizzati prima di testare. In caso di successo, il risultato riporta se il tuo server di sicurezza AI ha restituito un verdetto allow o deny per il prompt di test, il che fa emergere un'eventuale impostazione predefinita "nega tutto" prima che tu inizi ad applicare i verdetti.

   Risultati di errore comuni:

   Risultato	Cosa controllare
   URL rifiutato	L'URL non ha superato un controllo strutturale. Usa un URL https:// sulla porta 443.
   IP privato o interno	L'host si risolve in un indirizzo privato o interno. Usa un host instradabile pubblicamente.
   Timeout	Il server di sicurezza AI non ha restituito un verdetto entro il timeout.
   Errore di trasporto	La risoluzione DNS, l'handshake TLS o la connessione non sono riusciti.
   Stato diverso da 200	Il server di sicurezza AI ha risposto con uno stato diverso da 200. I verdetti devono tornare come HTTP 200; i redirect non vengono seguiti e contano come errori.
   Risposta non analizzabile	Il server di sicurezza AI ha risposto, ma il corpo non è un verdetto valido.

5. 5

   Salva e conserva il tuo segreto di firma

   Salva la configurazione dell'endpoint. Il primo salvataggio genera il tuo segreto di firma webhook e lo rivela una sola volta. Copialo e conservalo in modo sicuro prima di chiudere la finestra di dialogo: il segreto non può essere recuperato in seguito, solo ruotato.

   Il tuo server di sicurezza AI usa questo segreto per verificare la firma su ogni richiesta che riceve. Per la procedura di verifica, consulta Verificare la firma.

6. 6

   Scegli la gestione degli errori e il timeout

   Sotto Failure handling, imposta Mode per scegliere cosa accade mentre il server di sicurezza AI è irraggiungibile o i verdetti vanno in timeout:

   • Block the request: interrompe l'inferenza quando il tuo server di sicurezza AI non può fornire un verdetto (fail closed).
   • Allow the request: lascia che la richiesta proceda verso il modello senza ispezione (fail open).

   La terza opzione del menu a tendina, Shadow mode, è uno strumento di rollout piuttosto che una policy di gestione degli errori; consulta Shadow mode.

   Quindi imposta Prompt verdict timeout (ms): da 1 a 10.000 ms, con un valore predefinito di 5.000 ms. Il budget copre l'intero scambio, e un verdetto più lento conta come un server irraggiungibile, quindi imposta il valore più basso che il tuo server può rispettare in modo affidabile.

   Le modifiche in questa sezione vengono salvate man mano che le apporti. Al primo salvataggio, i valori predefiniti sono Allow the request e 5.000 ms.

7. 7

   Scegli una percentuale di rollout

   Sotto Rollout, imposta Requests inspected (%) per eseguire l'ispezione su una percentuale delle richieste mentre metti in funzione il tuo server di sicurezza AI. Il valore va da 0 a 100: 100 ispeziona tutto e 0 disattiva l'ispezione.

   Ogni richiesta viene estratta una sola volta per l'intero turno di conversazione, quindi una singola conversazione può essere ispezionata parzialmente tra un turno e l'altro. Le richieste al di fuori della percentuale campionata procedono senza ispezione, anche quando la gestione degli errori è impostata su Block the request.

8. 8

   Attiva Enforce verdicts

   Per valutare i verdetti sul traffico reale senza bloccare nessuno all'inizio, imposta Mode su Shadow mode (passaggio 6) prima di attivare l'applicazione; consulta Shadow mode.

   Attiva Enforce verdicts per subordinare Claude al verdetto del tuo server di sicurezza AI per ogni prompt governato, quindi conferma nella finestra di dialogo, che ribadisce la tua scelta di gestione degli errori. Attendi circa un minuto perché la modifica raggiunga ogni server Anthropic; le richieste già in corso terminano con la vecchia impostazione. Disattivandolo, i prompt smettono di essere inviati al tuo server di sicurezza AI, sempre entro circa un minuto; la tua configurazione viene conservata.

Shadow mode

La shadow mode (modalità ombra) esegue il tuo hook sul traffico reale senza bloccare nulla. Il tuo server di sicurezza AI riceve i prompt governati e restituisce verdetti esattamente come farebbe in fase di applicazione, ma nulla viene bloccato: ogni richiesta procede verso il modello, anche quando il tuo server la nega o non può essere raggiunto, e l'utente finale non vede nulla. Usala per mettere a punto la tua policy sul traffico reale della tua organizzazione prima di iniziare ad applicare i verdetti.

Per usare la shadow mode, imposta Mode su Shadow mode sotto Failure handling, quindi attiva Enforce verdicts affinché i prompt fluiscano verso il tuo server di sicurezza AI. Mentre è attiva, la pagina delle impostazioni mostra un badge Shadow mode — not blocking. Per uscire dalla shadow mode, reimposta Mode su Allow the request o Block the request; i verdetti vengono nuovamente applicati una volta che l'applicazione è attiva.

Esclusioni

Sotto Exclusions, seleziona i ruoli i cui membri non sono coperti dagli Inference hooks: i loro prompt non vengono mai inviati al tuo server di sicurezza AI. Possono essere esclusi solo i ruoli personalizzati creati dalla tua organizzazione; i ruoli integrati non vengono proposti. Selezionali nel selettore dei ruoli, il cui segnaposto riporta Select roles to exclude, e gestisci chi detiene ciascun ruolo dalla pagina di amministrazione dei ruoli (Manage roles); modificare le esclusioni richiede il permesso di gestione delle identità. L'elenco è vuoto per impostazione predefinita e, senza ruoli esclusi, ogni richiesta governata viene ispezionata.

L'esclusione si applica alle sessioni interattive di un utente; il traffico autenticato tramite credenziali macchina viene sempre ispezionato. Se Claude non riesce a risolvere l'appartenenza ai ruoli di un richiedente, la richiesta fallisce in modalità fail closed con un errore ripetibile anziché procedere senza ispezione. Le modifiche all'elenco delle esclusioni vengono registrate nell'audit trail.

Messaggio personalizzato per prompt bloccato

Sotto Custom blocked prompt message, imposta un testo personalizzato fino a 500 caratteri che viene aggiunto all'errore visualizzato dall'utente finale quando il tuo server di sicurezza AI nega una richiesta (tipicamente chi contattare o dove richiedere un'eccezione). Il messaggio finale è composto dal deny_reason per richiesta del tuo server di sicurezza AI (quando presente), una riga vuota, quindi questo testo. Senza testo personalizzato configurato, un valore predefinito integrato indirizza l'utente a contattare i propri amministratori; puoi anche disattivare del tutto il messaggio aggiunto in modo che l'utente veda solo il deny_reason.

Monitorare il tuo server di sicurezza AI

L'area di stato dell'endpoint nella pagina delle impostazioni degli Inference hooks mostra:

• Endpoint status: Healthy, Tripped, Not enforcing, oppure Not configured prima che un endpoint venga salvato.
• Failures per minute: errori webhook negli ultimi due minuti, in media.
• Block rate: i rifiuti come quota dei verdetti del tuo server di sicurezza AI, mostrato mentre la percentuale di rollout è inferiore a 100.
• Circuit breaker tripped: quando il circuit breaker è scattato l'ultima volta, se è successo.
• Recent errors: ogni voce è ridotta a un timestamp, un tipo di errore e una motivazione di una riga. Le voci non includono mai il contenuto delle richieste né l'URL del tuo endpoint.

Il pannello è best-effort: se Anthropic non riesce a leggere i contatori, mostra zero errori e nessun errore recente anziché un proprio errore, quindi un pannello dall'aspetto sano non è di per sé una prova che il tuo server di sicurezza AI sia sano. Failures per minute conta ogni errore, inclusi gli errori di rete e DNS che non fanno mai scattare il circuit breaker, quindi può essere alto mentre Circuit breaker tripped resta vuoto.

Circuit breaker

Errori webhook prolungati attribuibili al tuo server di sicurezza AI fanno scattare il circuit breaker (interruttore di protezione), che interrompe l'applicazione dei verdetti: il tuo server non viene più contattato e la tua scelta di Failure handling si applica a ogni richiesta ispezionata. Con Block the request selezionato, gli utenti della tua organizzazione vengono bloccati finché il circuit breaker non si ripristina. Quando il circuit breaker scatta, gli amministratori vengono anche avvisati nel centro notifiche di claude.ai.

Ogni scatto viene inoltre registrato nell'Activity Feed della tua organizzazione come attività inference_hooks_circuit_breaker_tripped, così il tuo team di sicurezza o il tuo fornitore possono generare avvisi sugli scatti dal monitoraggio che già eseguono, come un SIEM che acquisisce il feed. Viene registrata un'attività per scatto, non una per richiesta interessata. La registrazione richiede che la Compliance API sia abilitata per la tua organizzazione; consulta Configurare la Compliance API.

Per ripristinare, correggi il server, quindi riattiva Enforce verdicts per reimpostare il circuit breaker.

Il circuit breaker può anche ripristinarsi da solo. A partire da 10 minuti dopo lo scatto, Anthropic verifica se il tuo server si è ripreso: al massimo circa una volta al minuto, una richiesta del traffico normale della tua organizzazione viene inviata al tuo server per l'ispezione, e quella richiesta procede per il suo utente indipendentemente dal fatto che il tuo server risponda o meno. Se il tuo server risponde con un verdetto valido, allow o deny, il circuit breaker si ripristina e l'applicazione riprende. Qualsiasi altro esito è un errore webhook: il circuit breaker resta scattato e la verifica continua.

Il ripristino automatico funziona solo finché le tue impostazioni degli Inference hooks restano invariate dal momento dello scatto. Se modifichi qualsiasi impostazione degli Inference hooks dopo uno scatto, inclusa la rotazione del segreto di firma, la verifica si interrompe e il circuit breaker non si ripristina più da solo; riattiva Enforce verdicts quando il tuo server è stato corretto. Il ripristino automatico si applica solo agli scatti: se disattivi tu stesso Enforce verdicts, l'applicazione resta disattivata finché non la riattivi.

Ruotare il segreto di firma

Fai clic su Rotate secret sotto Request signing per sostituire il tuo segreto di firma. La rotazione è un passaggio immediato: il nuovo segreto viene generato e rivelato una sola volta, il vecchio segreto non può più essere recuperato e nessuna richiesta viene mai firmata con entrambi i segreti, quindi non esiste un periodo di sovrapposizione su cui fare affidamento.

Le richieste firmate con il segreto precedente possono ancora arrivare per breve tempo dopo la rotazione; Verificare la firma spiega come il tuo server di sicurezza AI dovrebbe gestire il passaggio.

Audit trail

L'attività degli Inference hooks viene registrata nell'Activity Feed della tua organizzazione: modifiche di configurazione, rifiuti, scatti del circuit breaker e richieste che sono procedute senza ispezione in base alla tua impostazione di gestione degli errori. Mentre il circuit breaker è scattato, non vengono registrate attività Inference hooks per singola richiesta; l'attività di scatto è la registrazione del feed per quella finestra temporale. I record di rifiuto contengono identificatori che ti permettono di collegare ogni rifiuto al record corrispondente nel tuo sistema.

Disattivare gli Inference hooks

Esistono due livelli di disattivazione:

• Enforce verdicts disattivato, nella pagina delle impostazioni degli Inference hooks: entro circa un minuto, i prompt della tua organizzazione smettono di essere inviati al tuo server di sicurezza AI; le richieste già in corso terminano con la vecchia impostazione. La pagina delle impostazioni resta disponibile, quindi usa questa opzione per mettere in pausa l'applicazione mentre lavori sul tuo server di sicurezza AI.
• Allow for your organization disattivato, nelle impostazioni Data and privacy: i prompt non vengono più ispezionati e le impostazioni degli Inference hooks diventano non disponibili finché non lo riattivi. La configurazione dell'endpoint, gli header personalizzati e il segreto di firma vengono conservati in entrambi i casi; riattivarlo forza Enforce verdicts su off e azzera un circuit breaker scattato, quindi riattiva l'applicazione quando sei pronto.

Passaggi successivi