AdministraçãoHooks de inferência

Configurar Inference hooks

Copy page



Permita Inference hooks para sua organização Claude Enterprise, conecte seu servidor de segurança de IA e controle a aplicação de vereditos, o tratamento de falhas e o rollout.

Os "Inference hooks" (hooks de inferência) enviam prompts da sua organização para um servidor de segurança de IA de sua escolha e retêm cada solicitação até receber um veredito de permitir ou negar antes que o Claude a processe. Esta página explica como ativar o recurso, conectar seu servidor e controlar a aplicação de vereditos. Para saber o que são os Inference hooks e quando usá-los, consulte a visão geral dos Inference hooks. Para construir o servidor de segurança de IA em si, consulte Desenvolver uma integração de Inference hooks.

Antes de começar

Você precisa de:

• A permissão organization:manage no claude.ai. As funções integradas Admin, Proprietário e Proprietário principal a possuem, assim como qualquer função personalizada à qual ela tenha sido concedida.
• Um endpoint HTTPS de servidor de segurança de IA que aceite solicitações de veredito: uma URL https:// na porta 443, em um host roteável publicamente, acessível sem redirecionamentos. Hosts de túnel reverso (ngrok e serviços de túnel semelhantes) não são suportados: a política de rede da Anthropic os bloqueia. Não teste por meio de um túnel; hospede seu servidor em um domínio que você controla. Para os requisitos de hospedagem completos, e para construir o servidor e verificar solicitações assinadas, consulte Desenvolver uma integração de Inference hooks.

Configurar Inference hooks

Existem três estados de aplicação: desativado (Aplicar vereditos está desativado: seu servidor de segurança de IA nunca é contatado e os prompts não são inspecionados), sombra (Aplicar vereditos está ativado com Modo definido como Modo sombra: seu servidor de segurança de IA recebe prompts e retorna vereditos, e nada é bloqueado) e aplicando (Aplicar vereditos está ativado com Modo definido como Permitir a solicitação ou Bloquear a solicitação: uma negação bloqueia a solicitação). As etapas a seguir levam uma nova configuração de desativada a aplicando.

1. 1

   Permitir Inference hooks para sua organização

   Acesse claude.ai > Configurações da organização > Dados e privacidade e encontre a seção Inference hooks. Ative Permitir para sua organização.

   Ativar essa opção desbloqueia a página de configurações dos Inference hooks e sempre força Aplicar vereditos para desativado, de modo que permitir o recurso nunca inicia a inspeção por si só: mesmo uma configuração que anteriormente tinha a aplicação ativada permanece sem inspeção até que você ative Aplicar vereditos novamente na etapa final.

2. 2

   Abrir a página de configurações dos Inference hooks

   Ainda em Dados e privacidade, abra a seção Inference hooks para chegar à página de configurações dos Inference hooks. Ela fica em Dados e privacidade, e não como uma entrada própria na navegação de configurações, portanto seu breadcrumb exibe Dados e privacidade / Inference hooks. Até que você salve um endpoint, a página avisa que os prompts ainda não estão sendo inspecionados, e Aplicar vereditos permanece desativado com um selo Requer endpoint.

3. 3

   Configurar seu endpoint

   Clique em Configurar para abrir a caixa de diálogo Configurar endpoint e preencha:

   • URL do endpoint: a URL https:// que recebe solicitações de veredito. Somente URLs https:// são aceitas.
   • Cabeçalhos de solicitação personalizados: até 16 cabeçalhos estáticos enviados com cada solicitação de veredito para que seu servidor de segurança de IA possa autenticar o chamador. Os valores dos cabeçalhos são armazenados criptografados e nunca são exibidos novamente; após salvar, apenas os nomes dos cabeçalhos são exibidos. Como os valores são somente de gravação, salvar qualquer alteração nos cabeçalhos exige inserir novamente todos os valores. Alterar a URL do endpoint limpa todos os valores de cabeçalho armazenados para que suas credenciais nunca sejam enviadas a um novo destino; insira-os novamente após uma alteração de URL. Os nomes dos cabeçalhos devem usar caracteres de token HTTP padrão com - em vez de _, e não devem colidir com nomes reservados (cabeçalhos de enquadramento de solicitação como Content-* e Host, cabeçalhos de proxy e de cookie, cabeçalhos de endereço do cliente como X-Forwarded-*, os cabeçalhos de assinatura webhook-* e o prefixo X-Anthropic-*). Os valores devem ser ASCII imprimível.

   A caixa de diálogo abrange apenas esses dois campos mais Testar conexão; ela não pergunta sobre tratamento de falhas, que você escolhe na etapa 6. Depois que um endpoint é salvo, o botão exibe Editar.

4. 4

   Testar a conexão

   Clique em Testar conexão. O Claude envia um prompt de teste sintético para a URL e os cabeçalhos atualmente no formulário, não os valores salvos, portanto insira novamente quaisquer valores de cabeçalho armazenados antes de testar. Em caso de sucesso, o resultado informa se seu servidor de segurança de IA retornou um veredito de permitir ou de negar para o prompt de teste, o que revela um padrão de negar tudo antes de você começar a aplicar vereditos.

   Resultados de falha comuns:

   Resultado	O que verificar
   URL rejeitada	A URL falhou em uma verificação estrutural. Use uma URL https:// na porta 443.
   IP privado ou interno	O host resolve para um endereço privado ou interno. Use um host roteável publicamente.
   Tempo limite esgotado	O servidor de segurança de IA não retornou um veredito dentro do tempo limite.
   Erro de transporte	A resolução de DNS, o handshake TLS ou a conexão falhou.
   Status diferente de 200	O servidor de segurança de IA respondeu com um status diferente de 200. Os vereditos devem retornar como HTTP 200; redirecionamentos não são seguidos e contam como falhas.
   Resposta não analisável	O servidor de segurança de IA respondeu, mas o corpo não é um veredito válido.

5. 5

   Salvar e armazenar seu segredo de assinatura

   Salve a configuração do endpoint. O primeiro salvamento gera seu segredo de assinatura do webhook e o revela uma única vez. Copie-o e armazene-o com segurança antes de fechar a caixa de diálogo: o segredo não pode ser recuperado posteriormente, apenas rotacionado.

   Seu servidor de segurança de IA usa esse segredo para verificar a assinatura em cada solicitação que recebe. Para o procedimento de verificação, consulte Verificar a assinatura.

6. 6

   Escolher o tratamento de falhas e o tempo limite

   Em Tratamento de falhas, defina Modo para escolher o que acontece enquanto o servidor de segurança de IA está inacessível ou os vereditos excedem o tempo limite:

   • Bloquear a solicitação: interromper a inferência quando seu servidor de segurança de IA não puder entregar um veredito (fail closed).
   • Permitir a solicitação: deixar a solicitação prosseguir para o modelo sem inspeção (fail open).

   A terceira opção do menu suspenso, Modo sombra, é uma ferramenta de rollout e não uma política de falhas; consulte Modo sombra.

   Em seguida, defina Tempo limite do veredito do prompt (ms): de 1 a 10.000 ms, com padrão de 5.000 ms. O orçamento cobre toda a troca, e um veredito mais lento conta como um servidor inacessível, portanto defina o menor valor que seu servidor consiga cumprir de forma confiável.

   As alterações nesta seção são salvas à medida que você as faz. No primeiro salvamento, os padrões são Permitir a solicitação e 5.000 ms.

7. 7

   Escolher uma porcentagem de rollout

   Em Rollout (implantação gradual), defina Solicitações inspecionadas (%) para executar a inspeção em uma porcentagem das solicitações enquanto você coloca seu servidor de segurança de IA em operação. O valor varia de 0 a 100: 100 inspeciona tudo e 0 desativa a inspeção.

   Cada solicitação é sorteada uma vez para todo o seu turno de conversa, portanto uma única conversa pode ser parcialmente inspecionada ao longo dos turnos. Solicitações fora da porcentagem amostrada prosseguem sem inspeção, mesmo quando o tratamento de falhas está definido como Bloquear a solicitação.

8. 8

   Ativar Aplicar vereditos

   Para avaliar vereditos em relação ao tráfego real sem bloquear ninguém no início, defina Modo como Modo sombra (etapa 6) antes de ativar a aplicação; consulte Modo sombra.

   Ative Aplicar vereditos para condicionar o Claude ao veredito do seu servidor de segurança de IA para cada prompt governado e, em seguida, confirme na caixa de diálogo, que reafirma sua escolha de tratamento de falhas. Aguarde cerca de um minuto para que a alteração chegue a todos os servidores da Anthropic; solicitações já em andamento terminam sob a configuração antiga. Desativá-lo interrompe o envio de prompts ao seu servidor de segurança de IA, novamente em cerca de um minuto; sua configuração é mantida.

Modo sombra

O "shadow mode" (modo sombra) executa seu hook em relação ao tráfego real sem bloquear nada. Seu servidor de segurança de IA recebe prompts governados e retorna vereditos exatamente como faria ao aplicá-los, mas nada é bloqueado: toda solicitação prossegue para o modelo, mesmo quando seu servidor a nega ou não pode ser alcançado, e o usuário final não vê nada. Use-o para ajustar sua política em relação ao tráfego real da sua organização antes de começar a aplicar vereditos.

Para usar o modo sombra, defina Modo como Modo sombra em Tratamento de falhas e, em seguida, ative Aplicar vereditos para que os prompts fluam para seu servidor de segurança de IA. Enquanto ele estiver ativo, a página de configurações exibe um selo Modo sombra — sem bloqueio. Para sair do modo sombra, defina Modo de volta para Permitir a solicitação ou Bloquear a solicitação; os vereditos são aplicados novamente assim que a aplicação estiver ativada.

Exclusões

Em Exclusões, selecione funções cujos membros não são cobertos pelos Inference hooks: seus prompts nunca são enviados ao seu servidor de segurança de IA. Somente funções personalizadas criadas pela sua organização podem ser excluídas; as funções integradas não são oferecidas. Escolha-as no seletor de funções, cujo placeholder exibe Selecionar funções a excluir, e gerencie quem possui cada função na página de administração de funções (Gerenciar funções); alterar exclusões requer permissão de gerenciamento de identidade. A lista fica vazia por padrão e, sem funções excluídas, toda solicitação governada é inspecionada.

A exclusão se aplica às sessões interativas de um usuário; o tráfego autenticado por credenciais de máquina é sempre inspecionado. Se o Claude não conseguir resolver a associação de funções de um solicitante, a solicitação falha de forma fechada (fail closed) com um erro que permite nova tentativa, em vez de prosseguir sem inspeção. As alterações na lista de exclusões são registradas na trilha de auditoria.

Mensagem personalizada de prompt bloqueado

Em Mensagem personalizada de prompt bloqueado, defina um texto personalizado de até 500 caracteres que é anexado ao erro que um usuário final vê quando seu servidor de segurança de IA nega uma solicitação (normalmente quem contatar ou onde solicitar uma exceção). A mensagem final é o deny_reason por solicitação do seu servidor de segurança de IA (quando presente), uma linha em branco e, em seguida, esse texto. Sem texto personalizado configurado, um padrão integrado orienta o usuário a contatar seus administradores; você também pode desativar totalmente a mensagem anexada para que o usuário veja apenas o deny_reason.

Monitorar seu servidor de segurança de IA

A área de integridade do endpoint na página de configurações dos Inference hooks mostra:

• Status do endpoint: Íntegro, Acionado, Sem aplicação ou Não configurado antes de um endpoint ser salvo.
• Falhas por minuto: falhas de webhook nos últimos dois minutos, em média.
• Taxa de bloqueio: negações como proporção dos vereditos do seu servidor de segurança de IA, exibida enquanto a porcentagem de rollout estiver abaixo de 100.
• Circuit breaker acionado: quando o circuit breaker foi acionado pela última vez, se tiver sido.
• Erros recentes: cada entrada é reduzida a um carimbo de data/hora, um tipo de erro e um motivo de uma linha. As entradas nunca incluem conteúdo de solicitações nem a URL do seu endpoint.

O painel opera em regime de melhor esforço: se a Anthropic não conseguir ler os contadores, ele mostra zero falhas e nenhum erro em vez de um erro próprio, portanto um painel com aparência saudável não é, por si só, prova de que seu servidor de segurança de IA está íntegro. Falhas por minuto conta todas as falhas, incluindo os erros de rede e de DNS que nunca acionam o circuit breaker, portanto pode estar alto enquanto Circuit breaker acionado permanece vazio.

Circuit breaker

Falhas de webhook sustentadas atribuíveis ao seu servidor de segurança de IA acionam o "circuit breaker" (disjuntor), que interrompe a aplicação: seu servidor não é mais contatado, e sua escolha de Tratamento de falhas se aplica a toda solicitação inspecionada. Com Bloquear a solicitação selecionado, os usuários da sua organização ficam bloqueados até que o circuit breaker seja redefinido. Quando o circuit breaker é acionado, os administradores também são notificados na central de notificações do claude.ai.

Cada acionamento também é registrado no Feed de atividades da sua organização como uma atividade inference_hooks_circuit_breaker_tripped, para que sua equipe de segurança ou fornecedor possa gerar alertas sobre acionamentos a partir do monitoramento que já executam, como um SIEM que ingere o feed. Uma atividade é registrada por acionamento, não uma por solicitação afetada. O registro requer que a Compliance API esteja habilitada para sua organização; consulte Configurar a Compliance API.

Para recuperar, corrija o servidor e, em seguida, ative Aplicar vereditos novamente para redefinir o circuit breaker.

O circuit breaker também pode ser redefinido por conta própria. A partir de 10 minutos após o acionamento, a Anthropic testa se seu servidor se recuperou: no máximo cerca de uma vez por minuto, uma solicitação do tráfego normal da sua organização é enviada ao seu servidor para inspeção, e essa solicitação prossegue para seu usuário independentemente de seu servidor responder ou não. Se seu servidor responder com um veredito válido, permitir ou negar, o circuit breaker é redefinido e a aplicação é retomada. Qualquer outro resultado é uma falha de webhook: o circuit breaker permanece acionado e os testes continuam.

A recuperação automática é executada apenas enquanto suas configurações de Inference hooks permanecem inalteradas desde o acionamento. Se você alterar qualquer configuração de Inference hooks após um acionamento, incluindo rotacionar o segredo de assinatura, os testes param e o circuit breaker não é mais redefinido por conta própria; ative Aplicar vereditos novamente quando seu servidor estiver corrigido. A recuperação automática se aplica apenas a acionamentos: se você mesmo desativar Aplicar vereditos, a aplicação permanece desativada até que você a ative novamente.

Rotacionar seu segredo de assinatura

Clique em Rotacionar segredo em Assinatura de solicitações para substituir seu segredo de assinatura. A rotação é uma transição imediata: o novo segredo é gerado e revelado uma única vez, o segredo antigo não pode mais ser recuperado, e nenhuma solicitação é assinada com ambos os segredos, portanto não há período de sobreposição com o qual contar.

Solicitações assinadas com o segredo anterior ainda podem chegar brevemente após a rotação; Verificar a assinatura aborda como seu servidor de segurança de IA deve lidar com a transição.

Trilha de auditoria

A atividade dos Inference hooks é registrada no Feed de atividades da sua organização: alterações de configuração, negações, acionamentos do circuit breaker e solicitações que prosseguiram sem inspeção sob sua configuração de tratamento de falhas. Enquanto o circuit breaker está acionado, nenhuma atividade de Inference hooks por solicitação é registrada; a atividade de acionamento é o registro do feed para essa janela. Os registros de negação carregam identificadores que permitem associar cada negação ao registro correspondente no seu próprio sistema.

Desativar os Inference hooks

Existem dois níveis de desativação:

• Aplicar vereditos desativado, na página de configurações dos Inference hooks: em cerca de um minuto, os prompts da sua organização deixam de ser enviados ao seu servidor de segurança de IA; solicitações já em andamento terminam sob a configuração antiga. A página de configurações permanece disponível, portanto use isso para pausar a aplicação enquanto você trabalha no seu servidor de segurança de IA.
• Permitir para sua organização desativado, nas configurações de Dados e privacidade: os prompts não são mais inspecionados, e as configurações dos Inference hooks ficam indisponíveis até que você o ative novamente. Sua configuração de endpoint, cabeçalhos personalizados e segredo de assinatura são mantidos de qualquer forma; ativá-lo novamente força Aplicar vereditos para desativado e limpa um circuit breaker acionado, portanto ative a aplicação novamente quando estiver pronto.

Próximos passos