AdministraciónHooks de inferencia

Configurar Inference hooks

Copy page



Permite Inference hooks para tu organización de Claude Enterprise, conecta tu servidor de seguridad de IA y controla la aplicación de veredictos, el manejo de fallos y el despliegue gradual.

Los "Inference hooks" (hooks de inferencia) envían los prompts de tu organización a un servidor de seguridad de IA que tú eliges, y retienen cada solicitud hasta recibir un veredicto de permitir o denegar antes de que Claude la procese. Esta página explica cómo activar la función, conectar tu servidor y controlar la aplicación de veredictos. Para saber qué son los Inference hooks y cuándo usarlos, consulta la descripción general de Inference hooks. Para construir el servidor de seguridad de IA en sí, consulta Desarrollar una integración de Inference hooks.

Antes de comenzar

Necesitas:

• El permiso organization:manage en claude.ai. Los roles integrados Admin, Owner y Primary owner lo poseen, así como cualquier rol personalizado al que se le haya otorgado.
• Un endpoint HTTPS de servidor de seguridad de IA que acepte solicitudes de veredicto: una URL https:// en el puerto 443, en un host enrutable públicamente, accesible sin redirecciones. Los hosts de túnel inverso (ngrok y servicios de túnel similares) no son compatibles: la política de red de Anthropic los bloquea. No hagas pruebas a través de un túnel; aloja tu servidor en un dominio que controles. Para conocer los requisitos de alojamiento completos, y para construir el servidor y verificar las solicitudes firmadas, consulta Desarrollar una integración de Inference hooks.

Configurar Inference hooks

Hay tres estados de aplicación: desactivado (Aplicar veredictos está desactivado: nunca se contacta a tu servidor de seguridad de IA y los prompts no se inspeccionan), sombra (Aplicar veredictos está activado con Modo establecido en Modo sombra: tu servidor de seguridad de IA recibe los prompts y devuelve veredictos, y no se bloquea nada) y aplicando (Aplicar veredictos está activado con Modo establecido en Permitir la solicitud o Bloquear la solicitud: una denegación bloquea la solicitud). Los siguientes pasos llevan una configuración nueva de desactivado a aplicando.

1. 1

   Permitir Inference hooks para tu organización

   Ve a claude.ai > Configuración de la organización > Datos y privacidad y busca la sección Inference hooks. Activa Permitir para tu organización.

   Activar esto desbloquea la página de configuración de Inference hooks y siempre fuerza Aplicar veredictos a desactivado, de modo que permitir la función nunca inicia la inspección por sí sola: incluso una configuración que anteriormente tenía la aplicación activada permanece sin inspección hasta que vuelvas a activar Aplicar veredictos en el paso final.

2. 2

   Abrir la página de configuración de Inference hooks

   Aún en Datos y privacidad, abre la sección Inference hooks para llegar a la página de configuración de Inference hooks. Se encuentra dentro de Datos y privacidad en lugar de ser una entrada propia en la navegación de configuración, por lo que su ruta de navegación dice Datos y privacidad / Inference hooks. Hasta que guardes un endpoint, la página advierte que los prompts aún no se están inspeccionando, y Aplicar veredictos permanece desactivado con una insignia Requiere endpoint.

3. 3

   Configurar tu endpoint

   Haz clic en Configurar para abrir el diálogo Configurar endpoint y completa:

   • URL del endpoint: la URL https:// que recibe las solicitudes de veredicto. Solo se aceptan URLs https://.
   • Encabezados de solicitud personalizados: hasta 16 encabezados estáticos enviados con cada solicitud de veredicto para que tu servidor de seguridad de IA pueda autenticar al emisor. Los valores de los encabezados se almacenan cifrados y nunca se vuelven a mostrar; después de guardar, solo se muestran los nombres de los encabezados. Como los valores son de solo escritura, guardar cualquier cambio en los encabezados requiere volver a ingresar todos los valores. Cambiar la URL del endpoint borra todos los valores de encabezado almacenados para que tus credenciales nunca se envíen a un nuevo destino; vuelve a ingresarlos después de cambiar la URL. Los nombres de los encabezados deben usar caracteres de token HTTP estándar con - en lugar de _, y no deben coincidir con nombres reservados (encabezados de estructura de solicitud como Content-* y Host, encabezados de proxy y de cookies, encabezados de dirección del cliente como X-Forwarded-*, los encabezados de firma webhook-* y el prefijo X-Anthropic-*). Los valores deben ser ASCII imprimible.

   El diálogo cubre solo esos dos campos más Probar conexión; no pregunta sobre el manejo de fallos, que eliges en el paso 6. Una vez guardado un endpoint, el botón dice Editar.

4. 4

   Probar la conexión

   Haz clic en Probar conexión. Claude envía un prompt de prueba sintético a la URL y los encabezados que están actualmente en el formulario, no a los valores guardados, así que vuelve a ingresar cualquier valor de encabezado almacenado antes de probar. Si tiene éxito, el resultado informa si tu servidor de seguridad de IA devolvió un veredicto de permitir o de denegar para el prompt de prueba, lo que pone en evidencia una configuración predeterminada de denegar todo antes de que empieces a aplicar veredictos.

   Resultados de fallo comunes:

   Resultado	Qué verificar
   URL rechazada	La URL no pasó una verificación estructural. Usa una URL https:// en el puerto 443.
   IP privada o interna	El host se resuelve a una dirección privada o interna. Usa un host enrutable públicamente.
   Tiempo de espera agotado	El servidor de seguridad de IA no devolvió un veredicto dentro del tiempo de espera.
   Error de transporte	Falló la resolución DNS, el handshake TLS o la conexión.
   Estado distinto de 200	El servidor de seguridad de IA respondió con un estado distinto de 200. Los veredictos deben devolverse como HTTP 200; las redirecciones no se siguen y cuentan como fallos.
   Respuesta no analizable	El servidor de seguridad de IA respondió, pero el cuerpo no es un veredicto válido.

5. 5

   Guardar y almacenar tu secreto de firma

   Guarda la configuración del endpoint. El primer guardado genera tu secreto de firma de webhook y lo revela una sola vez. Cópialo y almacénalo de forma segura antes de cerrar el diálogo: el secreto no se puede recuperar más tarde, solo rotar.

   Tu servidor de seguridad de IA usa este secreto para verificar la firma de cada solicitud que recibe. Para el procedimiento de verificación, consulta Verificar la firma.

6. 6

   Elegir el manejo de fallos y el tiempo de espera

   En Manejo de fallos, establece Modo para elegir qué sucede mientras el servidor de seguridad de IA no está accesible o los veredictos agotan el tiempo de espera:

   • Bloquear la solicitud: detener la inferencia cuando tu servidor de seguridad de IA no puede entregar un veredicto (fallo cerrado).
   • Permitir la solicitud: dejar que la solicitud continúe hacia el modelo sin inspección (fallo abierto).

   La tercera opción del menú desplegable, Modo sombra, es una herramienta de despliegue gradual más que una política de fallos; consulta Modo sombra.

   Luego establece Tiempo de espera del veredicto del prompt (ms): de 1 a 10,000 ms, con un valor predeterminado de 5,000 ms. El presupuesto cubre todo el intercambio, y un veredicto más lento cuenta como un servidor inaccesible, así que establece el valor más bajo que tu servidor pueda cumplir de forma confiable.

   Los cambios en esta sección se guardan a medida que los haces. En el primer guardado, los valores predeterminados son Permitir la solicitud y 5,000 ms.

7. 7

   Elegir un porcentaje de despliegue

   En Despliegue, establece Solicitudes inspeccionadas (%) para ejecutar la inspección en un porcentaje de las solicitudes mientras pones en marcha tu servidor de seguridad de IA. El valor va de 0 a 100: 100 inspecciona todo y 0 desactiva la inspección.

   Cada solicitud se sortea una vez para todo su turno de conversación, por lo que una misma conversación puede inspeccionarse parcialmente a lo largo de los turnos. Las solicitudes fuera del porcentaje muestreado continúan sin inspección, incluso cuando el manejo de fallos está establecido en Bloquear la solicitud.

8. 8

   Activar Aplicar veredictos

   Para evaluar los veredictos contra tráfico real sin bloquear a nadie al principio, establece Modo en Modo sombra (paso 6) antes de activar la aplicación; consulta Modo sombra.

   Activa Aplicar veredictos para condicionar a Claude al veredicto de tu servidor de seguridad de IA para cada prompt gobernado, y luego confirma en el diálogo, que reitera tu elección de manejo de fallos. Espera aproximadamente un minuto para que el cambio llegue a todos los servidores de Anthropic; las solicitudes ya en curso terminan con la configuración anterior. Desactivarlo detiene el envío de prompts a tu servidor de seguridad de IA, de nuevo en aproximadamente un minuto; tu configuración se conserva.

Modo sombra

El modo sombra ejecuta tu hook contra tráfico real sin bloquear nada. Tu servidor de seguridad de IA recibe los prompts gobernados y devuelve veredictos exactamente como lo haría al aplicar, pero no se bloquea nada: cada solicitud continúa hacia el modelo, incluso cuando tu servidor la deniega o no se puede contactar, y el usuario final no ve nada. Úsalo para ajustar tu política contra el tráfico real de tu organización antes de empezar a aplicar veredictos.

Para usar el modo sombra, establece Modo en Modo sombra en Manejo de fallos, y luego activa Aplicar veredictos para que los prompts fluyan hacia tu servidor de seguridad de IA. Mientras está activo, la página de configuración muestra una insignia Modo sombra — sin bloqueo. Para salir del modo sombra, vuelve a establecer Modo en Permitir la solicitud o Bloquear la solicitud; los veredictos se aplican de nuevo una vez que la aplicación está activada.

Exclusiones

En Exclusiones, selecciona los roles cuyos miembros no están cubiertos por Inference hooks: sus prompts nunca se envían a tu servidor de seguridad de IA. Solo se pueden excluir los roles personalizados que tu organización creó; los roles integrados no se ofrecen. Elígelos en el selector de roles, cuyo texto de marcador dice Seleccionar roles para excluir, y administra quién posee cada rol desde la página de administración de roles (Administrar roles); cambiar las exclusiones requiere permiso de administración de identidades. La lista está vacía de forma predeterminada y, sin roles excluidos, se inspecciona cada solicitud gobernada.

La exclusión se aplica a las sesiones interactivas de un usuario; el tráfico autenticado con credenciales de máquina siempre se inspecciona. Si Claude no puede resolver la pertenencia a roles de un solicitante, la solicitud falla en modo cerrado con un error reintentable en lugar de continuar sin inspección. Los cambios en la lista de exclusiones se registran en el registro de auditoría.

Mensaje personalizado de prompt bloqueado

En Mensaje personalizado de prompt bloqueado, establece un texto personalizado de hasta 500 caracteres que se añade al error que ve un usuario final cuando tu servidor de seguridad de IA deniega una solicitud (normalmente a quién contactar o dónde solicitar una excepción). El mensaje final es el deny_reason por solicitud de tu servidor de seguridad de IA (cuando está presente), una línea en blanco y luego este texto. Sin texto personalizado configurado, un valor predeterminado integrado indica al usuario que contacte a sus administradores; también puedes desactivar por completo el mensaje añadido para que el usuario vea solo el deny_reason.

Monitorear tu servidor de seguridad de IA

El área de estado del endpoint de la página de configuración de Inference hooks muestra:

• Estado del endpoint: Saludable, Disparado, Sin aplicar o Sin configurar antes de que se guarde un endpoint.
• Fallos por minuto: fallos de webhook durante los últimos dos minutos, promediados.
• Tasa de bloqueo: denegaciones como proporción de los veredictos de tu servidor de seguridad de IA, mostrada mientras el porcentaje de despliegue está por debajo de 100.
• Interruptor de circuito disparado: cuándo se disparó el interruptor por última vez, si lo ha hecho.
• Errores recientes: cada entrada se reduce a una marca de tiempo, un tipo de error y un motivo de una línea. Las entradas nunca incluyen contenido de la solicitud ni la URL de tu endpoint.

El panel funciona en modo de mejor esfuerzo: si Anthropic no puede leer los contadores, muestra cero fallos y ningún error en lugar de un error propio, por lo que un panel de aspecto saludable no es por sí mismo prueba de que tu servidor de seguridad de IA esté saludable. Fallos por minuto cuenta cada fallo, incluidos los errores de red y DNS que nunca disparan el interruptor de circuito, por lo que puede ser alto mientras Interruptor de circuito disparado permanece vacío.

Interruptor de circuito

Los fallos de webhook sostenidos atribuibles a tu servidor de seguridad de IA disparan el "circuit breaker" (interruptor de circuito), que detiene la aplicación: ya no se contacta a tu servidor, y tu elección de Manejo de fallos se aplica a cada solicitud inspeccionada. Con Bloquear la solicitud seleccionado, los usuarios de tu organización quedan bloqueados hasta que el interruptor se restablezca. Cuando el interruptor se dispara, también se notifica a los administradores en el centro de notificaciones de claude.ai.

Cada disparo también se registra en el Feed de actividad de tu organización como una actividad inference_hooks_circuit_breaker_tripped, para que tu equipo de seguridad o proveedor pueda generar alertas sobre los disparos desde el monitoreo que ya ejecutan, como un SIEM que ingiere el feed. Se registra una actividad por disparo, no una por solicitud afectada. El registro requiere que la Compliance API esté habilitada para tu organización; consulta Configurar la Compliance API.

Para recuperarte, corrige el servidor y luego vuelve a activar Aplicar veredictos para restablecer el interruptor.

El interruptor también puede restablecerse por sí solo. A partir de 10 minutos después del disparo, Anthropic prueba si tu servidor se ha recuperado: como máximo aproximadamente una vez por minuto, una solicitud del tráfico normal de tu organización se envía a tu servidor para inspección, y esa solicitud continúa para su usuario independientemente de si tu servidor responde o no. Si tu servidor responde con un veredicto válido, permitir o denegar, el interruptor se restablece y la aplicación se reanuda. Cualquier otro resultado es un fallo de webhook: el interruptor permanece disparado y las pruebas continúan.

La recuperación automática se ejecuta solo mientras tu configuración de Inference hooks no haya cambiado desde el disparo. Si cambias cualquier ajuste de Inference hooks después de un disparo, incluida la rotación del secreto de firma, las pruebas se detienen y el interruptor ya no se restablece por sí solo; vuelve a activar Aplicar veredictos cuando tu servidor esté corregido. La recuperación automática se aplica solo a los disparos: si desactivas Aplicar veredictos tú mismo, la aplicación permanece desactivada hasta que la vuelvas a activar.

Rotar tu secreto de firma

Haz clic en Rotar secreto en Firma de solicitudes para reemplazar tu secreto de firma. La rotación es un cambio inmediato: el nuevo secreto se genera y se revela una sola vez, el secreto anterior ya no se puede recuperar, y ninguna solicitud se firma nunca con ambos secretos, por lo que no hay un período de superposición en el que apoyarse.

Las solicitudes firmadas con el secreto anterior aún pueden llegar brevemente después de la rotación; Verificar la firma cubre cómo tu servidor de seguridad de IA debe manejar la transición.

Registro de auditoría

La actividad de Inference hooks se registra en el Feed de actividad de tu organización: cambios de configuración, denegaciones, disparos del interruptor de circuito y solicitudes que continuaron sin inspección según tu configuración de manejo de fallos. Mientras el interruptor de circuito está disparado, no se registran actividades de Inference hooks por solicitud; la actividad de disparo es el registro del feed para ese período. Los registros de denegación llevan identificadores que te permiten relacionar cada denegación con el registro correspondiente en tu propio sistema.

Desactivar Inference hooks

Hay dos niveles de desactivación:

• Aplicar veredictos desactivado, en la página de configuración de Inference hooks: en aproximadamente un minuto, los prompts de tu organización dejan de enviarse a tu servidor de seguridad de IA; las solicitudes ya en curso terminan con la configuración anterior. La página de configuración sigue disponible, así que usa esto para pausar la aplicación mientras trabajas en tu servidor de seguridad de IA.
• Permitir para tu organización desactivado, en la configuración de Datos y privacidad: los prompts ya no se inspeccionan, y la configuración de Inference hooks deja de estar disponible hasta que lo vuelvas a activar. Tu configuración de endpoint, encabezados personalizados y secreto de firma se conservan en cualquier caso; volver a activarlo fuerza Aplicar veredictos a desactivado y borra un interruptor de circuito disparado, así que activa la aplicación de nuevo cuando estés listo.

Próximos pasos