AdministraciónHooks de inferencia

Configurar hooks de inferencia

Copy page



Permite los hooks de inferencia 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 empezar

Necesitas:

• El permiso organization:manage en claude.ai, que solo tienen los roles Propietario y Propietario principal. El rol Administrador no lo tiene.
• 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 y 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 todos los requisitos de alojamiento, y para crear el servidor y verificar las solicitudes firmadas, consulta Desarrollar una integración de hooks de inferencia.

Configurar hooks de inferencia

Hay tres estados de aplicación:

• Desactivado: con Aplicar veredictos desactivado, nunca se contacta a tu servidor de seguridad de IA y los prompts no se inspeccionan.
• Sombra: con Aplicar veredictos activado y Modo establecido en Modo sombra, tu servidor de seguridad de IA recibe los prompts y devuelve veredictos, y no se bloquea nada.
• Aplicando: con Aplicar veredictos activado y 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 desactivada a aplicando.

1. 1

   Permitir los hooks de inferencia para tu organización

   Ve a claude.ai > Configuración de la organización > Datos y privacidad y busca la sección Hooks de inferencia. Activa Permitir para su organización.

   Activar esto desbloquea la página de configuración de los hooks de inferencia 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 Hooks de inferencia

   Todavía en Datos y privacidad, abre la sección Hooks de inferencia para llegar a la página de configuración de los hooks de inferencia. Se encuentra dentro de Datos y privacidad en lugar de tener su propia entrada en la navegación de configuración, por lo que su ruta de navegación muestra Datos y privacidad / Hooks de inferencia. 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

   Configura tu endpoint

   Haz clic en Configurar para abrir el cuadro de diálogo Configurar endpoint e introduce la URL del endpoint: la URL https:// que recibe las solicitudes de veredicto. Solo se aceptan URLs https://.

   En este punto el cuadro de diálogo no pide nada más: los encabezados de solicitud personalizados llegan en el paso 5, y el manejo de fallos en el paso 6. Haz clic en Siguiente para guardar. Una vez guardado un endpoint, el botón muestra Editar.

4. 4

   Guarda tu secreto de firma

   El primer guardado genera tu “signing secret” (secreto de firma) de webhook y lo muestra una sola vez. Cópialo y guárdalo de forma segura antes de hacer clic en Siguiente: 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, incluida la prueba de conexión del siguiente paso. Para conocer el procedimiento de verificación, consulta Verificar la firma.

5. 5

   Agrega encabezados de solicitud y prueba la conexión

   Al hacer clic en Siguiente en el cuadro de diálogo del secreto de firma se vuelve a abrir el cuadro de diálogo del endpoint, ahora con dos controles más:

   • Encabezados de solicitud personalizados: hasta 16 encabezados estáticos que se envían con cada solicitud de veredicto para que tu servidor de seguridad de IA pueda autenticar a quien llama. 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 destino nuevo; 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.
   • 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 los valores de encabezado almacenados antes de probar. Si la prueba tiene éxito, el resultado indica si tu servidor de seguridad de IA devolvió un veredicto de permitir o de denegar para el prompt de prueba, lo que revela un comportamiento predeterminado de denegarlo todo antes de que empieces a aplicar veredictos. También muestra el tiempo de ida y vuelta que Anthropic midió para esa única solicitud de prueba, en una conexión nueva, incluido el handshake de conexión.

   Haz clic en Guardar para guardar los encabezados que ingresaste.

   Resultados de fallo comunes:

   Resultado	Qué revisar
   URL rechazada	La URL no superó una verificación estructural. Usa una URL https:// en el puerto 443.
   IP privada o interna	El host de la URL es una dirección IP privada o interna, una dirección IPv6 o localhost. 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, o el nombre de host se resuelve a una dirección privada.
   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.
   Se requiere secreto de firma	Tu organización no tiene un secreto de firma, por lo que la prueba se enviaría sin firmar. Haz clic en Generar secreto en Firma de solicitudes y vuelve a probar.

6. 6

   Elegir el manejo de fallos y el tiempo de espera

   En Manejo de fallos, establece Modo para elegir qué ocurre 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 y no 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 cuadro de diálogo, que vuelve a indicar tu elección de manejo de fallos. Espera aproximadamente un minuto a que el cambio llegue a todos los servidores de Anthropic; las solicitudes que ya están en curso se completan con la configuración anterior. Desactivarlo detiene el envío de prompts a tu servidor de seguridad de IA, también en aproximadamente un minuto; tu configuración se conserva.

   Validar llamadas a herramientas, debajo de Aplicar veredictos, también envía las llamadas a herramientas de cada respuesta de Claude a tu servidor de seguridad de IA y espera su veredicto antes de que se ejecuten; consulta El marco de llamada a herramienta. Está activado de forma predeterminada en una configuración nueva. No tiene efecto mientras Aplicar veredictos está desactivado, y un cambio en esta opción tarda aproximadamente un minuto en llegar a todos los servidores de Anthropic, igual que con Aplicar veredictos.

Modo sombra

El “shadow mode” (modo sombra) ejecuta tu hook con 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 aplicarlos, 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 con el tráfico real de tu organización antes de empezar a aplicar los veredictos. Con Validar llamadas a herramientas activado, tu servidor también recibe marcos de llamadas a herramientas en modo sombra, y no se bloquea ninguna llamada a herramienta.

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 bloqueos. 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 Who is inspected, con Limit by role activado, selecciona los roles cuyos miembros no están cubiertos por los hooks de inferencia: sus prompts nunca se envían a tu servidor de seguridad de IA. Solo se pueden excluir los roles personalizados que creó tu organización; los roles integrados no se ofrecen. Selecciónalos en el selector de roles, cuyo texto de marcador dice Seleccionar roles para excluir, y administra quién tiene cada rol desde la página de administración de roles (Gestionar roles); cambiar las exclusiones requiere el permiso de administración de identidades. La lista está vacía de forma predeterminada y, sin roles excluidos, se inspecciona cada solicitud controlada, a menos que Inspeccionar esté establecido en Only selected roles.

La exclusión se aplica a las sesiones interactivas de un usuario. Los cambios en la lista de exclusiones se registran en el Activity Feed de tu organización como cambios de permisos de roles (rbac_role_permission_added y rbac_role_permission_removed).

Inspeccionar solo los roles seleccionados

Todo en la sección Who is inspected depende de un solo interruptor, Limit by role. Cuando activas el interruptor, Inspeccionar comienza en Everyone except excluded roles, y los roles excluidos se seleccionan debajo como se describió anteriormente.

Para probar los hooks de inferencia primero en una parte de tu organización, activa Limit by role, establece Inspeccionar en Only selected roles y selecciona los roles en el cuadro de diálogo que se abre. A partir de entonces, solo se inspeccionan los miembros configurados con Roles personalizados que tienen asignado un rol seleccionado. Los miembros configurados con cualquier otro rol, como Usuario o Propietario, no se inspeccionan, aunque tengan asignado un rol seleccionado. Eso te incluye a ti si estás configurado como Propietario o Propietario principal. Elimina todos los roles excluidos antes de cambiar: una organización usa exclusiones o roles seleccionados, no ambos. Después del cambio, agrega o elimina roles en el selector de roles bajo Inspeccionar. Para volver a inspeccionar a todos, desactiva Limit by role: después de confirmar, esto elimina todos los roles excluidos y desactiva Only selected roles.

Mientras Only selected roles está establecido:

• Un rol personalizado cuyo Acceso a capacidades es Todas las capacidades o Todo disponible de forma general solo cuenta si lo seleccionas, como cualquier otro rol.
• Si ningún miembro configurado con Roles personalizados tiene asignado un rol seleccionado, no se inspecciona a ningún miembro.
• No se inspeccionan las solicitudes que no tienen un miembro detrás, como las solicitudes realizadas con claves de API y las conversaciones de Claude Tag en Slack.

Los cambios en Inspeccionar y en los roles inspeccionados se registran en el Activity Feed de tu organización.

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 los hooks de inferencia muestra:

• Estado del endpoint: Saludable, Disparado, Sin aplicar o Sin configurar antes de que se guarde un endpoint.
• Fallas por minuto: fallos del webhook durante los últimos 2 minutos, promediados.
• Tasa de bloqueo: denegaciones como proporción de los veredictos de tu servidor de seguridad de IA, que se muestra mientras el porcentaje de despliegue es inferior a 100.
• Interruptor de circuito activado: cuándo se disparó el interruptor por última vez, si es que se disparó.
• Errores recientes: cada entrada muestra cuándo ocurrió el fallo, un tipo de error y una categoría. La categoría es webhook_error para un problema con tu endpoint o con la conexión a él, o relay_error para un fallo dentro de los sistemas de Anthropic. Una entrada DlpWebhookStatusError también puede mostrar el estado HTTP que devolvió tu servidor de seguridad de IA y el tamaño del cuerpo de la solicitud que envió Anthropic, como HTTP 413 · 1.3 MB. Las entradas nunca incluyen el contenido de la solicitud ni la URL de tu endpoint. La lista conserva los 10 fallos más recientes y se borra una hora después del último.

Los tipos de error en Errores recientes significan:

En modo sombra, ningún error cuenta para el disyuntor.

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. Fallas por minuto cuenta cada fallo, incluidos los errores de red y DNS que nunca disparan el interruptor de circuito, por lo que su valor puede ser alto mientras Interruptor de circuito activado 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 Activity Feed de tu organización como una actividad inference_hooks_circuit_breaker_tripped, para que tu equipo de seguridad o tu proveedor puedan generar alertas sobre los disparos desde la supervisión que ya utilizan, como un SIEM que ingiera el feed. Se registra una actividad por cada disparo, no una por cada 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 disyuntor también puede restablecerse por sí solo. A partir de 10 minutos después de la activación, Anthropic comprueba si tu servidor se ha recuperado enviándole una solicitud de prueba en segundo plano, como máximo aproximadamente una vez por minuto; no interviene ninguna solicitud de usuario. Si tu servidor responde con un veredicto válido, de permitir o de denegar, el disyuntor se restablece y la aplicación se reanuda. De lo contrario, el disyuntor permanece activado y las comprobaciones continúan.

La recuperación automática solo se ejecuta mientras tu configuración de los hooks de inferencia no haya cambiado desde la activación. Si cambias cualquier configuración de los hooks de inferencia después de una activación, incluida la rotación del secreto de firma, las comprobaciones se detienen y el disyuntor ya no se restablece por sí solo; vuelve a activar Aplicar veredictos cuando tu servidor esté corregido. La recuperación automática solo se aplica a las activaciones del disyuntor: si tú mismo desactivas Aplicar veredictos, 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. Si tu organización aún no tiene un secreto, el mismo botón dice Generar secreto y crea el primero. La rotación es un cambio inmediato: el nuevo secreto se genera y se muestra 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 puedas confiar.

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 los hooks de inferencia se registra en el Activity Feed de tu organización: cambios de configuración, denegaciones, activaciones del disyuntor y solicitudes que continuaron sin inspección porque no se pudo obtener un veredicto. Este último tipo solo se registra mientras Aplicar veredictos está activado y Modo es Permitir la solicitud. Su motivo es endpoint_timeout, endpoint_error para cualquier otro problema al llamar a tu servidor de seguridad de IA, o internal_error para un fallo del lado de Anthropic. Con Bloquear la solicitud o Modo sombra, las solicitudes fallidas no se registran individualmente. La recuperación automática del disyuntor no se registra en ningún modo. Mientras el disyuntor está activado, no se registran actividades de hooks de inferencia por solicitud; la actividad de activación es el registro del feed para ese período. Los registros de denegación incluyen identificadores que te permiten vincular cada denegación con el registro correspondiente en tu propio sistema.

Desactivar los hooks de inferencia

Hay dos niveles de desactivación:

• Aplicar veredictos desactivado, en la página de configuración de los hooks de inferencia: en aproximadamente un minuto, los prompts de tu organización dejan de enviarse a tu servidor de seguridad de IA; las solicitudes que ya están en curso se completan con la configuración anterior. La página de configuración sigue disponible, así que usa esta opción para pausar la aplicación mientras trabajas en tu servidor de seguridad de IA.
• Permitir para su organización desactivado, en la configuración de Datos y privacidad: los prompts ya no se inspeccionan, y la configuración de los hooks de inferencia 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