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, que apenas as funções Owner e Primary owner possuem. A função Admin não a possui.
• 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 publicamente roteável, 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 faça testes por meio de um túnel; hospede seu servidor em um domínio que você controla. Para os requisitos de hospedagem completos, e para criar 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 Configure para abrir a caixa de diálogo Set up endpoint e insira a Endpoint URL: a URL https:// que recebe as solicitações de veredito. Apenas URLs https:// são aceitas.

   A caixa de diálogo não pede mais nada neste momento: os cabeçalhos de solicitação personalizados vêm na etapa 5, e o tratamento de falhas na etapa 6. Clique em Next para salvar. Depois que um endpoint é salvo, o botão passa a exibir Edit.

4. 4

   Armazenar seu segredo de assinatura

   O primeiro salvamento gera seu segredo de assinatura de webhook e o revela uma única vez. Copie-o e armazene-o com segurança antes de clicar em Next: o segredo não pode ser recuperado depois, apenas rotacionado.

   Seu servidor de segurança de IA usa esse segredo para verificar a assinatura de cada solicitação que recebe, incluindo o teste de conexão na próxima etapa. Para o procedimento de verificação, consulte Verificar a assinatura.

5. 5

   Adicionar cabeçalhos de solicitação e testar a conexão

   Clicar em Next na caixa de diálogo do segredo de assinatura reabre a caixa de diálogo do endpoint, agora com mais dois controles:

   • Custom request headers: 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 apaga 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.
   • Test connection: o Claude envia um prompt de teste sintético para a URL e os cabeçalhos atualmente no formulário, não para 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 permissão ou de negação para o prompt de teste, o que revela um padrão de negar tudo antes que você comece a aplicar os vereditos.

   Clique em Save para armazenar os cabeçalhos que você inseriu.

   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 da URL é um endereço IP privado ou interno, um endereço IPv6 ou localhost. Use um host publicamente roteável.
   Tempo 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, ou o nome do host resolve para um endereço privado.
   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.
   Segredo de assinatura necessário	Sua organização não tem um segredo de assinatura, então o teste seria enviado sem assinatura. Clique em Generate secret em Request signing e teste novamente.

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 reapresenta sua escolha de tratamento de falhas. Aguarde cerca de um minuto para que a alteração chegue a todos os servidores da Anthropic; as solicitações já em andamento terminam com a configuração antiga. Desativá-lo faz com que os prompts deixem de ser enviados ao seu servidor de segurança de IA, também em cerca de um minuto; sua configuração é mantida.

   Validate tool calls, abaixo de Aplicar vereditos, também envia as chamadas de ferramentas em cada uma das respostas do Claude para seu servidor de segurança de IA e aguarda o veredito dele antes que sejam executadas; consulte O frame de chamada de ferramenta. Essa opção vem ativada por padrão em uma nova configuração. Ela não tem efeito enquanto Aplicar vereditos estiver desativado, e uma alteração nela leva cerca de um minuto para chegar a todos os servidores da Anthropic, assim como ocorre com Aplicar vereditos.

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 os 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 os vereditos. Com Validate tool calls ativado, seu servidor também recebe frames de chamada de ferramenta no modo sombra, e nenhuma chamada de ferramenta é bloqueada.

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. As alterações na lista de exclusões são registradas no Feed de atividades da sua organização como alterações de permissão de função (rbac_role_permission_added e rbac_role_permission_removed).

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 que um endpoint seja 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" (disjuntor) foi acionado pela última vez, se tiver sido.
• Erros recentes: cada entrada mostra quando a falha ocorreu, um tipo de erro e uma categoria. A categoria é webhook_error para um problema com seu endpoint ou com a conexão a ele, ou relay_error para uma falha dentro dos sistemas da Anthropic. As entradas nunca incluem o conteúdo da solicitação nem a URL do seu endpoint. A lista mantém as 10 falhas mais recentes e é limpa uma hora após a última.

Os tipos de erro em Erros recentes significam:

No modo sombra, nenhum erro conta para o circuit breaker.

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 disjuntor também pode ser redefinido por conta própria. A partir de 10 minutos após o acionamento, a Anthropic verifica se seu servidor se recuperou enviando a ele uma solicitação de teste em segundo plano, no máximo cerca de uma vez por minuto; nenhuma solicitação de usuário está envolvida. Se seu servidor responder com um veredito válido, de permissão ou de negação, o disjuntor é redefinido e a aplicação é retomada. Caso contrário, o disjuntor permanece acionado e as verificações continuam.

A recuperação automática só é executada enquanto suas configurações de Inference hooks permanecerem inalteradas desde o acionamento. Se você alterar qualquer configuração de Inference hooks após um acionamento, incluindo a rotação do segredo de assinatura, as verificações param e o disjuntor deixa de ser redefinido por conta própria; ative Enforce verdicts novamente quando seu servidor estiver corrigido. A recuperação automática se aplica apenas a acionamentos: se você mesmo desativar Enforce verdicts, a aplicação permanece desativada até que você a ative novamente.

Rotacionar seu segredo de assinatura

Clique em Rotate secret em Request signing para substituir seu segredo de assinatura. Se sua organização ainda não tiver um segredo, o mesmo botão exibe Generate secret e cria o primeiro. 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á um 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 porque nenhum veredito pôde ser obtido. Esse último tipo é registrado apenas enquanto Aplicar vereditos estiver ativado e Modo for Permitir a solicitação. Seu motivo é endpoint_timeout, endpoint_error para qualquer outro problema ao chamar seu servidor de segurança de IA, ou internal_error para uma falha do lado da Anthropic. Com Bloquear a solicitação ou Modo sombra, as solicitações com falha não são registradas individualmente. A recuperação automática do circuit breaker não é registrada em nenhum modo. Enquanto o circuit breaker estiver acionado, nenhuma atividade de Inference hooks por solicitação é registrada; a atividade de acionamento é o registro do feed para esse período. Os registros de negação contêm 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