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:

• L'autorizzazione organization:manage in claude.ai, di cui dispongono solo i ruoli Owner e Primary owner. Il ruolo Admin non la possiede.
• Un endpoint HTTPS del server di sicurezza AI che accetti le richieste di verdetto: un URL https:// sulla porta 443, su un host instradabile pubblicamente, raggiungibile senza reindirizzamenti. Gli host di tunnel inverso (ngrok e servizi di tunneling simili) non sono supportati: la policy di rete di Anthropic li blocca. Non eseguire test tramite un tunnel; ospita il tuo server su un dominio che controlli. Per i requisiti di hosting completi, e per creare il server e verificare le richieste firmate, consulta Sviluppare un'integrazione con gli 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 Set up endpoint e inserisci l'Endpoint URL: l'URL https:// che riceve le richieste di verdetto. Sono accettati solo URL https://.

   A questo punto la finestra di dialogo non chiede nient'altro: le intestazioni di richiesta personalizzate arrivano nel passaggio 5 e la gestione degli errori nel passaggio 6. Fai clic su Next per salvare. Una volta salvato un endpoint, il pulsante riporta Edit.

4. 4

   Conserva il tuo segreto di firma

   Il primo salvataggio genera il "signing secret" (segreto di firma) del tuo webhook e lo mostra una sola volta. Copialo e conservalo in modo sicuro prima di fare clic su Next: il segreto non può essere recuperato in seguito, ma solo ruotato.

   Il tuo server di sicurezza AI usa questo segreto per verificare la firma di ogni richiesta che riceve, incluso il test di connessione nel passaggio successivo. Per la procedura di verifica, consulta Verificare la firma.

5. 5

   Aggiungi le intestazioni di richiesta e testa la connessione

   Facendo clic su Next nella finestra di dialogo del segreto di firma si riapre la finestra di dialogo dell'endpoint, ora con due controlli aggiuntivi:

   • Custom request headers: fino a 16 intestazioni statiche inviate con ogni richiesta di verdetto, in modo che il tuo server di sicurezza AI possa autenticare il chiamante. I valori delle intestazioni vengono archiviati crittografati e non vengono mai più mostrati; dopo il salvataggio, vengono visualizzati solo i nomi delle intestazioni. Poiché i valori sono di sola scrittura, salvare qualsiasi modifica alle intestazioni richiede di reinserire ogni valore. La modifica dell'URL dell'endpoint cancella tutti i valori delle intestazioni archiviati, in modo che le tue credenziali non vengano mai inviate a una nuova destinazione; reinseriscili dopo una modifica dell'URL. I nomi delle intestazioni devono usare i caratteri token HTTP standard con - anziché _ e non devono entrare in conflitto con i nomi riservati (intestazioni di framing della richiesta come Content-* e Host, intestazioni di proxy e cookie, intestazioni dell'indirizzo del client come X-Forwarded-*, le intestazioni di firma webhook-* e il prefisso X-Anthropic-*). I valori devono essere caratteri ASCII stampabili.
   • Test connection: Claude invia un prompt di test sintetico all'URL e alle intestazioni attualmente presenti nel modulo, non ai valori salvati, quindi reinserisci eventuali valori delle intestazioni archiviati prima di eseguire il test. In caso di successo, il risultato indica se il tuo server di sicurezza AI ha restituito un verdetto di autorizzazione o di rifiuto per il prompt di test, il che fa emergere un'impostazione predefinita che rifiuta tutto prima che tu inizi ad applicare i verdetti.

   Fai clic su Save per archiviare le intestazioni che hai inserito.

   Risultati di errore comuni:

   Risultato	Cosa verificare
   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 essere restituiti come HTTP 200; i reindirizzamenti non vengono seguiti e sono considerati errori.
   Risposta non analizzabile	Il server di sicurezza AI ha risposto, ma il corpo non è un verdetto valido.
   Segreto di firma richiesto	La tua organizzazione non ha un segreto di firma, quindi il test verrebbe inviato senza firma. Fai clic su Generate secret in Request signing, quindi esegui di nuovo il test.

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. 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 l'intervento, Anthropic verifica se il tuo server si è ripreso inviandogli una richiesta di test in background, al massimo circa una volta al minuto; non è coinvolta alcuna richiesta degli utenti. Se il tuo server risponde con un verdetto valido, di autorizzazione o di rifiuto, il circuit breaker si ripristina e l'applicazione dei verdetti riprende. In caso contrario, il circuit breaker resta scattato e le verifiche continuano.

Il ripristino automatico viene eseguito solo finché le impostazioni degli Inference hooks restano invariate dall'intervento. Se modifichi qualsiasi impostazione degli Inference hooks dopo un intervento, inclusa la rotazione del segreto di firma, le verifiche si interrompono 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 interventi: se disattivi tu stesso Enforce verdicts, l'applicazione resta disattivata finché non la riattivi.

Ruotare il segreto di firma

Fai clic su Rotate secret in Request signing per sostituire il tuo segreto di firma. Se la tua organizzazione non ha ancora un segreto, lo stesso pulsante riporta Generate secret e crea il primo. La rotazione è un passaggio immediato: il nuovo segreto viene generato e mostrato 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