Guardrails nas políticas

Esta seção explica como definir Bedrock Guardrails na política. O Bedrock Guardrails fornece proteções configuráveis que podem ser executadas em solicitações e respostas para manter os aplicativos de IA seguros. Atualmente, você pode definir ataques imediatos, filtros de conteúdo e proteções de informações confidenciais na política. Cada corrimão deve ser configurado com uma categoria e um limite entre 0 e 1.

Quando uma grade de proteção avalia o contexto, ela retorna uma pontuação de confiança entre 0 e 1, indicando o grau de confiança de que o conteúdo avaliado exibe a propriedade definida (por exemplo). PROMPT_INJECTION

Disponibilidade regional de guardrails

A tabela a seguir mostra quais AWS regiões têm apoio para barreiras de proteção na política:

Antes de começar

Antes de começar, você precisa configurar adequadamente sua função do IAM.

Permissões

A função de execução do AgentCore gateway configurada no gateway associado ao seu mecanismo de políticas deve ter permissões tanto para as AgentCore operações do Bedrock quanto para o Bedrock Guardrails. A bedrock:InvokeGuardrailChecks permissão é necessária porque o plano de dados da Política usa credenciais FAS (Forward Access Session) derivadas da função de execução do gateway para chamar a API Bedrock Guardrails em seu nome.

{
  "Version": "2012-10-17", 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "bedrock-agentcore:*",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "bedrock:InvokeGuardrailChecks",
      "Resource": "*"
    }
  ]
}

Guardrails suportados

Definindo barreiras nas políticas

Para definir barreiras na política, você pode escrever a política como código ou descrever a política em linguagem natural. Semelhante a qualquer política existente que você já tenha criado, você precisa especificar um efeito (por exemplopermit) com uma condição (when guardrails). Na condição, você precisa fornecer a proteção de proteção específica que deseja habilitar, a categoria de proteção a ser usada, o contexto que deseja que a proteção de proteção avalie e o limite de pontuação de confiança.

Exemplo de definição de guarda-corpo

suppressOutput (principal, action == AgentCore::Action::"<TARGET_NAME>_<METHOD>:<URI>", resource == AgentCore::Gateway::"<GATEWAY_ARN>")
when guardrails {
    BedrockGuardrails::ContentFilter(["HATE"],[context.output.message])["HATE"]
    .confidenceScore
    .greaterThan(decimal("0.2"))
};

Especificando uma proteção de guarda-corpo

Para escolher um tipo específico de entidade de proteção, use o BedrockGuardrails namespace:

Seleção de uma categoria de proteção

Selecione uma categoria para a salvaguarda fornecida (consulteGuardrails suportados).

por exemplo BedrockGuardrails::ContentFilter(["HATE"],[context.output.message])

Efeitos para grades de proteção

Para criar grades de proteção para uso em solicitações de autorização, use os efeitos permit e. forbid Eles continuam a reger a autorização de solicitações.

forbid (principal, action == AgentCore::Action::"<TargetName>___POST:/invocations", resource) when guardrails {
  BedrockGuardrails::PromptAttack(["PROMPT_INJECTION"], [context.input.prompt])["PROMPT_INJECTION"].confidenceScore.greaterThan(decimal("0.6"))
};

Para criar grades de proteção para uso na supressão de saídas de ferramentas, agentes ou modelos, use o efeito. suppressOutput suppressOutputé um novo efeito que opera nos dados que uma ação retorna. Depois que uma ação autorizada é concluída, ela avalia as saídas em relação à grade de proteção e suprime a saída quando a grade de proteção é violada.

suppressOutput (principal, action == AgentCore::Action::"<TargetName>___POST:/invocations", resource) when guardrails {
  BedrockGuardrails::SensitiveInformation(["US_SOCIAL_SECURITY_NUMBER"], [context.output.text])["US_SOCIAL_SECURITY_NUMBER"]
    .confidenceScore
    .greaterThan(decimal("0.5"))
};

Transmitindo contexto para sua grade de proteção

Ao definir barreiras na política, você deve especificar caminhos de dados (por exemplocontext.input.message) que identifiquem os valores a serem extraídos da carga útil da ação. A grade de proteção avalia os valores extraídos. Você pode especificar um ou mais caminhos para os dados com base em seu esquema de solicitação ou resposta.

por exemplo [context.input.message, context.input.systemPrompt]

Limites para grades de proteção

Com filtros de conteúdo e detecção imediata de ataques, o guardrail retorna uma pontuação de confiança, que é um valor numérico no intervalo [0, 1], em que 0 significa baixa confiança e 1 é alta confiança. A pontuação representa a confiança com que a grade de proteção detectou uma violação. As pontuações atuais possíveis são valores discretos {0, 0,2, 0,4, 0,6, 0,8 e 1,0}.

Para definir um limite, você precisa fornecer o valor decimal ao operador de comparação (por exemplo). greaterThan(decimal("0.4"))

Operadores de comparação de pontuação

Você pode aplicar os operadores de comparação abaixo a qualquer um dos confidenceScoremaxConfidenceScore(), ouminConfidenceScore():

Você pode usar uma agregação em sua política para extrair e comparar as pontuações retornadas pelas grades de proteção:

Agregações

Como escolher um limite

Se você não especificar um limite ao solicitar o serviço de criação, AgentCore defina um valor padrão. Se você escrever suas políticas sem a ajuda do serviço de criação, deverá fornecer o valor limite.

Os padrões abaixo são calibrados para fornecer ampla cobertura com precisão aceitável para a maioria das cargas de trabalho:

Escolhendo um limite personalizado

Se os limites padrão não atenderem aos seus requisitos, você poderá determinar o limite ideal para sua carga de trabalho usando uma das abordagens a seguir.

Opção 1: avaliar com base em um conjunto de testes dourado

Use essa abordagem quando você tiver um conjunto organizado de entradas de teste com resultados esperados claros.

Opção 2: avaliar em relação ao tráfego de produção

Use essa abordagem quando você não tiver um conjunto de testes pré-construído e quiser calibrar usando padrões reais de tráfego.

Teste as barreiras de proteção na política

AgentCore fornece vários mecanismos para testar políticas de proteção antes de aplicá-las ao tráfego de produção. Você pode controlar a aplicação no nível do mecanismo de políticas, no nível da política individual ou em ambos, permitindo validar o comportamento da barreira de proteção de forma incremental. Consulte testar uma política para obter mais informações.

Como as grades de proteção funcionam com a política

As políticas de proteção podem ser aplicadas a qualquer destino de gateway. Os guardrails são executados em: * alvos MCP — POST /mcp (JSON-RPC tools/call) * alvos de tempo de execução HTTP — * alvos de inferência HTTP — POST /<target>/invocations POST /inference

Quando uma chamada chega ao seu gateway, o Policy Evaluator executa o seguinte:

Nota: As grades de proteção não são determinísticas. A mesma entrada pode resultar em saídas diferentes. As políticas, no entanto, são determinísticas, a mesma entrada sempre resultará na mesma saída.

Limitações das barreiras de proteção na política