Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Gli "Inference hooks" (hook di inferenza) inviano i prompt della tua organizzazione a un server di sicurezza IA di tua scelta e trattengono ogni richiesta in attesa di un verdetto di autorizzazione o rifiuto prima che Claude la elabori. Questa pagina illustra come attivare la funzionalità, connettere il tuo server e controllare l'applicazione. Per sapere cosa sono gli Inference hooks e quando usarli, consulta la panoramica sugli Inference hooks. Per costruire il server di sicurezza IA stesso, consulta Sviluppare un'integrazione Inference hooks.
Ti serve:
organization:manage in claude.ai. I ruoli predefiniti Admin, Owner e Primary owner lo detengono, così come qualsiasi ruolo personalizzato a cui sia stato concesso.https:// sulla porta 443, su un host instradabile pubblicamente, raggiungibile senza reindirizzamenti. Per i requisiti di hosting completi, e per costruire il server e verificare le richieste firmate, consulta Sviluppare un'integrazione Inference hooks.Esistono tre stati di applicazione: disattivato (Enforce verdicts è disattivato: il tuo server di sicurezza IA 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 IA riceve i prompt e restituisce verdetti, ma nulla viene bloccato) e applicazione attiva (Enforce verdicts è attivato con Mode impostato su Allow the request o Block the request: un rifiuto blocca la richiesta). I passaggi seguenti portano una nuova configurazione da disattivato ad applicazione attiva.
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.
Attivare questa opzione sblocca la pagina delle impostazioni degli Inference hooks e forza sempre Enforce verdicts su disattivato, quindi consentire la funzionalità non avvia mai l'ispezione da sola: anche una configurazione che in precedenza aveva l'applicazione attiva rimane non ispezionata finché non riattivi Enforce verdicts nel passaggio finale.
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 separata 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 rimane disattivato con un badge Requires endpoint.
Configura il tuo endpoint
Fai clic su Configure per aprire la finestra di dialogo Configure endpoint e compila:
https:// che riceve le richieste di verdetto. Sono accettati solo URL https://.- 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 informazioni sulla gestione degli errori, che scegli nel passaggio 6. Una volta salvato un endpoint, il pulsante riporta Edit.
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 archiviati prima di testare. In caso di successo, il risultato riporta se il tuo server di sicurezza IA ha restituito un verdetto di autorizzazione o di rifiuto per il prompt di test, il che fa emergere un'eventuale impostazione predefinita di rifiuto totale prima di iniziare l'applicazione.
Risultati di errore comuni:
| Risultato | Cosa verificare |
|---|---|
| URL rejected | L'URL non ha superato un controllo strutturale. Usa un URL https:// sulla porta 443. |
| Private or internal IP | L'host si risolve in un indirizzo privato o interno. Usa un host instradabile pubblicamente. |
| Timeout | Il server di sicurezza IA non ha restituito un verdetto entro il timeout. |
| Transport error | La risoluzione DNS, l'handshake TLS o la connessione non sono riusciti. |
| Non-200 status | Il server di sicurezza IA ha risposto con uno stato diverso da 200. I verdetti devono essere restituiti come HTTP 200; i reindirizzamenti non vengono seguiti e contano come errori. |
| Unparseable response | Il server di sicurezza IA ha risposto, ma il corpo non è un verdetto valido. |
Salva e archivia 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 archivialo 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 IA usa questo segreto per verificare la firma su ogni richiesta che riceve. Per la procedura di verifica, consulta Verificare la firma.
Scegli la gestione degli errori e il timeout
Sotto Failure handling, imposta Mode per scegliere cosa succede quando il server di sicurezza IA non è raggiungibile o i verdetti vanno in timeout:
La terza opzione del menu a discesa, Shadow mode, è uno strumento di rollout piuttosto che una policy di gestione degli errori; consulta Shadow mode.
Poi 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 server non raggiungibile, 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.
Scegli una percentuale di rollout
Sotto Rollout, imposta Requests inspected (%) per eseguire l'ispezione su una percentuale di richieste mentre metti in funzione il tuo server di sicurezza IA. Il valore va da 0 a 100: 100 ispeziona tutto e 0 disattiva l'ispezione.
Ogni richiesta viene sorteggiata una volta per l'intero turno di conversazione, quindi una singola conversazione può essere ispezionata parzialmente tra i turni. Le richieste al di fuori della percentuale campionata procedono senza ispezione, anche quando la gestione degli errori è impostata su Block the request.
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 IA per ogni prompt governato, poi conferma nella finestra di dialogo, che riepiloga la tua scelta di gestione degli errori. Attendi circa un minuto affinché la modifica raggiunga ogni server Anthropic; le richieste già in corso terminano con l'impostazione precedente. Disattivarlo interrompe l'invio dei prompt al tuo server di sicurezza IA, sempre entro circa un minuto; la tua configurazione viene mantenuta.
La "shadow mode" (modalità ombra) esegue il tuo hook sul traffico reale senza bloccare nulla. Il tuo server di sicurezza IA riceve i prompt governati e restituisce verdetti esattamente come farebbe durante l'applicazione, ma nulla viene bloccato: ogni richiesta procede al modello, anche quando il tuo server la rifiuta o non può essere raggiunto, e l'utente finale non vede nulla. Usala per affinare la tua policy sul traffico reale della tua organizzazione prima di iniziare l'applicazione.
Per usare la shadow mode, imposta Mode su Shadow mode sotto Failure handling, poi attiva Enforce verdicts in modo che i prompt fluiscano al tuo server di sicurezza IA. 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.
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 IA. Possono essere esclusi solo i ruoli personalizzati creati dalla tua organizzazione; i ruoli predefiniti non sono offerti. Selezionali nel selettore di ruoli, il cui placeholder 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 da credenziali macchina viene sempre ispezionato. Se Claude non riesce a risolvere l'appartenenza al ruolo di un richiedente, la richiesta fallisce in modo chiuso con un errore ritentabile anziché procedere senza ispezione. Le modifiche all'elenco delle esclusioni vengono registrate nell'audit trail.
Sotto Custom blocked prompt message, imposta un testo personalizzato di massimo 500 caratteri che viene aggiunto all'errore che un utente finale vede quando il tuo server di sicurezza IA rifiuta una richiesta (tipicamente chi contattare o dove richiedere un'eccezione). Il messaggio finale è il deny_reason per richiesta del tuo server di sicurezza IA (quando presente), una riga vuota, poi questo testo. Senza testo personalizzato configurato, un messaggio predefinito integrato indirizza l'utente a contattare i propri amministratori; puoi anche disattivare completamente il messaggio aggiunto in modo che l'utente veda solo il deny_reason.
L'area di integrità dell'endpoint nella pagina delle impostazioni degli Inference hooks mostra:
Il pannello è best-effort: se Anthropic non riesce a leggere i contatori mostra zero errori e nessun errore anziché un errore proprio, quindi un pannello dall'aspetto sano non è di per sé prova che il tuo server di sicurezza IA 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 rimane vuoto.
Errori webhook prolungati attribuibili al tuo server di sicurezza IA fanno scattare il "circuit breaker" (interruttore automatico), che interrompe l'applicazione: 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é non intervieni. Quando il breaker scatta, gli amministratori vengono anche notificati nel centro notifiche di claude.ai.
Per ripristinare, correggi il server, poi riattiva Enforce verdicts per reimpostare il breaker.
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 c'è alcun periodo di sovrapposizione su cui fare affidamento.
Le richieste firmate con il segreto precedente possono ancora arrivare brevemente dopo la rotazione; Verificare la firma spiega come il tuo server di sicurezza IA dovrebbe gestire il passaggio.
L'attività degli Inference hooks viene registrata nell'Activity Feed della tua organizzazione: modifiche alla configurazione, rifiuti e richieste che sono procedute senza ispezione in base alla tua impostazione di gestione degli errori. I record di rifiuto contengono identificatori che ti consentono di collegare ogni rifiuto al record corrispondente nel tuo sistema.
Esistono due livelli di disattivazione:
Costruisci il server di sicurezza IA: gli schemi di richiesta e verdetto, la verifica della firma e la semantica operativa.
Cosa sono gli Inference hooks, come funziona il ciclo di andata e ritorno del verdetto e cosa viene inviato al tuo server di sicurezza IA.
Was this page helpful?