View a markdown version of this page

Barandillas en las pólizas - lecho rocoso amazónico AgentCore

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Barandillas en las pólizas

En esta sección se explica cómo poner barreras a las políticas, de modo que la decisión de una política dependa de si el contenido de la solicitud o de la respuesta contiene material no seguro. La comprobación del contenido propiamente dicha se lleva a cabo mediante una barrera de protección, a la que recurre la política durante la evaluación. AgentCore Hoy en día, las barandillas están respaldadas por Amazon Bedrock Guardrails.

Una condición de barandilla designa tres cosas: el tipo de barandilla, las categorías que el tipo debe evaluar y el contenido que se va a evaluar. La barandilla devuelve una puntuación de confianza y su póliza decide qué hacer con ella.

Si es la primera vez que utiliza las barandillas de protección en las pólizas, comience por Primeros pasos con las barandillas, que le explicarán cómo crear una barrera integral. Para ver ejemplos de políticas que cubren el MCP, el tiempo de ejecución y cada API de inferencia, consulte los ejemplos de políticas de Guardrail.

Componentes básicos de una condición de barandilla

La política AgentCore admite tres tipos de barandillas. Cada uno toma un conjunto de categorías para evaluarlo y devuelve su resultado de manera diferente.

ContentFilter

Harmful-content categorías como VIOLENCE oHATE. Devuelve una puntuación de confianza para cada categoría que nombre, independientemente de que el contenido la muestre o no.

PromptAttack

Prompt-manipulation categorías como JAILBREAK oPROMPT_INJECTION. Devuelve una puntuación de confianza para cada categoría que nombre.

SensitiveInformation

Entidades sensibles como EMAIL oUS_SOCIAL_SECURITY_NUMBER. Devuelve una detección por entidad encontrada en lugar de una puntuación por categoría, por lo que no tiene una puntuación por categoría y requiere una agregación.

Para ver las categorías que acepta cada tipo, consulte Barandillas compatibles. Para ver el contenido que debes evaluar, consulta Cómo transferir el contexto a tu barandilla.

Una puntuación de confianza es un decimal entre 0 y 1 que expresa la intensidad con la que el contenido exhibe la propiedad evaluada. Usted decide qué hacer con esa puntuación y la política expresa su decisión como una condición en el resultado de la barrera de seguridad, que suele ser una comparación de umbrales, por ejemplo. .confidenceScore.greaterThan(decimal("0.4")) Para ver los umbrales y los operadores de comparación, consulte Umbrales para barandas.

Las puntuaciones también se pueden reducir en todas las categorías en lugar de compararlas una por una. Una agregación hace lo siguiente: maxConfidenceScore() minConfidenceScore() devuelve una puntuación, mientras que count() devuelve el número de detecciones que hubo y categories() devuelve el conjunto de categorías detectadas, por lo que estas dos categorías no necesitan ningún umbral. Para ver la lista completa, consulte Agregaciones.

Disponibilidad regional de barandas

En la siguiente tabla se muestran AWS las regiones que admiten barreras en las políticas.

Nombre de la región Barreras en las políticas

Este de EE. UU. (Norte de Virginia)

✓ Sí

Este de EE. UU. (Ohio)

✓ Sí

Oeste de EE. UU. (Norte de California)

No

Oeste de EE. UU. (Oregón)

✓ Sí

Asia-Pacífico (Hyderabad)

No

Asia-Pacífico (Malasia)

No

Asia-Pacífico (Mumbai)

No

Asia-Pacífico (Seúl)

No

Asia-Pacífico (Singapur)

No

Asia-Pacífico (Sídney)

✓ Sí

Asia-Pacífico (Tailandia)

No

Asia-Pacífico (Tokio)

✓ Sí

Canadá (centro)

No

Europa (Fráncfort)

No

Europa (Irlanda)

No

Europa (Londres)

✓ Sí

Europa (Milán)

No

Europa (París)

No

Europa (España)

No

Europa (Estocolmo)

✓ Sí

América del Sur (São Paulo)

No

AWS GovCloud (US-West)

No

Antes de empezar

Antes de empezar, debe configurar correctamente su función de IAM.

Permisos

La función de ejecución de la puerta de enlace necesita, bedrock:InvokeGuardrailChecks además de los AgentCore permisos que ya tiene. Para ver estos últimos, consulte AgentCore Pasarela y política en Permisos de AgentCore IAM.

La política AgentCore utiliza las credenciales de sesión de acceso directo (FAS) derivadas de la función de ejecución de la puerta de enlace para llamar a la API Bedrock Guardrails en su nombre, razón por la cual el permiso pertenece a esa función.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "bedrock:InvokeGuardrailChecks", "Resource": "arn:aws:bedrock:us-west-2:123456789012:guardrail/abc123" } ] }

Barandillas compatibles

Tipo de barandilla Tipo de identidad Categorías

Filtro de contenido

ContentFilter

VIOLENCE, HATE, SEXUAL, MISCONDUCT, INSULTS

Detección rápida de ataques

PromptAttack

JAILBREAK, PROMPT_INJECTION, PROMPT_LEAKAGE

Información confidencial

SensitiveInformation

Identidad personal: ADDRESSAGE, NAMEEMAIL,PHONE,USERNAME,PASSWORD,PIN,DRIVER_ID,LICENSE_PLATE, VEHICLE_IDENTIFICATION_NUMBER

Financiero — CREDIT_DEBIT_CARD_NUMBERCREDIT_DEBIT_CARD_CVV,CREDIT_DEBIT_CARD_EXPIRY,US_BANK_ACCOUNT_NUMBER,US_BANK_ROUTING_NUMBER,INTERNATIONAL_BANK_ACCOUNT_NUMBER, SWIFT_CODE

Identificadores gubernamentales y de salud:US_SOCIAL_SECURITY_NUMBER,US_PASSPORT_NUMBER,US_INDIVIDUAL_TAX_IDENTIFICATION_NUMBER,,CA_SOCIAL_INSURANCE_NUMBER,CA_HEALTH_NUMBER,UK_NATIONAL_INSURANCE_NUMBER, UK_NATIONAL_HEALTH_SERVICE_NUMBER UK_UNIQUE_TAXPAYER_REFERENCE_NUMBER

Credenciales y red:AWS_ACCESS_KEY,AWS_SECRET_KEY,,IP_ADDRESS, MAC_ADDRESS URL

nota

Esta tabla es la lista actual de barreras y categorías compatibles con Policy in AgentCore . Una categoría ajena a ella no pasa la validación al crear la política. En concreto, no hay ninguna ACCOUNT_NUMBER categoría: usar US_BANK_ACCOUNT_NUMBER oINTERNATIONAL_BANK_ACCOUNT_NUMBER.

Incluir barreras en las políticas

Para poner una barrera a una política, puede crear la política como código o describirla en lenguaje natural. Al igual que con otras políticas, especifique un efecto, por ejemplopermit, con una condición ()when guardrails. En esta condición, indique la barrera que desee activar, las categorías que desee evaluar, el contenido que desee evaluar y la comparación de puntuaciones que desee.

Ejemplo de definición de barandilla

suppressOutput (principal, action == AgentCore::Action::"<TargetName>___<METHOD>:<uri>", resource == AgentCore::Gateway::"<gateway-arn>") when guardrails { BedrockGuardrails::ContentFilter(["HATE"],[context.output.message])["HATE"] .confidenceScore .greaterThan(decimal("0.2")) };
nota

suppressOutputse ejecuta después de que la herramienta haya producido un resultado y oculta la respuesta a la persona que llama. La herramienta sigue funcionando; solo se suprime la respuesta.

suppressOutputsolo funciona en condiciones de barandilla. Su estado debe consistir únicamente en controles de barandillas. Escriba esos cheques en un when guardrails {…​} bloque o en un bloque simplewhen {…​}. suppressOutputno es compatible con temporal {…​} las condiciones estándar de Cedar.

Tenga en cuenta los tres caracteres de subrayado que separan el nombre del objetivo del método y la URI. Para ver ejemplos de una pasarela de referencia completa, consulte los ejemplos de políticas de Guardrail.

Crear una política con barandas

Para crear la política, coloque la declaración en el policy campo de la definition propiedad. Para obtener más información, consulte Crear una política. De lo contrario, se crea como cualquier otra política.

ejemplo
AgentCore CLI

El asistente interactivo es la forma más sencilla de añadir una barandilla, ya que crea la declaración automáticamente.

  1. Corre agentcore add policy sin banderas:

    agentcore add policy

    El asistente solicita la puerta de enlace, el objetivo, el motor y el nombre de la política. Elija el formulario de barandilla como fuente y, a continuación, solicitará el efecto, la categoría de la barandilla, los filtros y la ruta de datos, y le mostrará la declaración que creó antes de crearla.

  2. Implemente el proyecto:

    agentcore deploy --yes

    Para programar lo mismo de forma no interactiva, pase los indicadores del formulario:--form-category, --form-filters--form-effect, y. --form-data-path Al proporcionar cualquiera de ellos, se omite el asistente. Para proporcionar una declaración que haya escrito usted mismo, guárdela en un archivo y pase--source:

    agentcore add policy --name BlockViolentReason \ --engine my_policy_engine \ --source block_violent_reason.dw \ --validation-mode IGNORE_ALL_FINDINGS

    Para obtener más información, consulte Introducción a las barandillas.

AWS CLI
  1. Ejecute el siguiente comando AWS CLI en una terminal para crear la política:

    aws bedrock-agentcore-control create-policy \ --policy-engine-id my_policy_engine-a1b2c3d4e5 \ --name BlockViolentReason \ --validation-mode IGNORE_ALL_FINDINGS \ --definition '{ "policy": { "statement": "forbid (principal, action == AgentCore::Action::\"RefundTool___process_refund\", resource == AgentCore::Gateway::\"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/my-gateway-a1b2c3d4e5\") when guardrails { BedrockGuardrails::ContentFilter([\"VIOLENCE\"], [context.input.reason])[\"VIOLENCE\"].confidenceScore.greaterThan(decimal(\"0.4\")) };" } }'
AWS Python SDK (Boto3)
  1. Ejecute el siguiente código de Python para crear la política mediante el AWS SDK para Python:

    import boto3 client = boto3.client("bedrock-agentcore-control") GATEWAY_ARN = "arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/my-gateway-a1b2c3d4e5" statement = ( 'forbid (principal, ' 'action == AgentCore::Action::"RefundTool___process_refund", ' f'resource == AgentCore::Gateway::"{GATEWAY_ARN}") ' 'when guardrails { ' 'BedrockGuardrails::ContentFilter(["VIOLENCE"], [context.input.reason])["VIOLENCE"]' '.confidenceScore.greaterThan(decimal("0.4")) };' ) response = client.create_policy( policyEngineId="my_policy_engine-a1b2c3d4e5", name="BlockViolentReason", validationMode="IGNORE_ALL_FINDINGS", definition={"policy": {"statement": statement}}, ) # CreatePolicy returns 202 - wait for the terminal status client.get_waiter("policy_active").wait( policyEngineId="my_policy_engine-a1b2c3d4e5", policyId=response["policyId"], ) print(response["policyId"])

Sea cual sea la superficie que utilice, prefiera expresar la regla como a permit con la comparación inversa. La evaluación de políticas se deniega por defecto, por lo permit que una sola opción válida solo se mantiene mientras la puntuación se mantenga baja, otorga la acción y la cierra:

permit (principal, action == AgentCore::Action::"RefundTool___process_refund", resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/my-gateway-a1b2c3d4e5") when guardrails { BedrockGuardrails::ContentFilter(["VIOLENCE"], [context.input.reason])["VIOLENCE"] .confidenceScore.lessThanOrEqual(decimal("0.4")) };

Úselo forbid cuando desee restringir un permiso que ya existe, una acción que alguna otra política permite, por ejemplo, en sus valores de entrada. A forbid anula cualquier concesiónpermit, por lo que se resta de la concesión existente. Por sí sola, no garantiza nada: la acción permanece denegada por defecto y nunca se consulta la barrera, por lo que una persona forbid necesita un acompañante permit para la misma acción.

importante

La validación de políticas analiza todo el conjunto de políticas del motor y no puede interpretar el estado de una barandilla. Por lo tanto, un dispositivo forbid cuya única puerta es una barandilla le parece incondicional, por lo que si nada más en el motor permite ese principio, acción y recurso, el conjunto se considera demasiado restrictivo:. Overly Restrictive: Policy Engine will deny every request for the specified principal (…​), action (…​) and resource (…​) combination if the policy is added or updated Por defecto, --validation-mode FAIL_ON_ANY_FINDINGS la política es rechazada. Pase --validation-mode IGNORE_ALL_FINDINGS para crearlo de todos modos.

Como el hallazgo es una propiedad del conjunto de políticas y no de una afirmación en particular, el hecho de que se vea o no depende de lo que el motor ya demuestre.

El rechazo es asíncrono. La llamada devuelve el 202 con el 202 yCREATING, a continuación, la política se establece CREATE_FAILED con el motivo puestostatusReasons, así que consulta el estado del terminal en lugar de tratar el 202 como un éxito.

Para obtener un recorrido completo mediante la AgentCore CLI en su lugar, consulte Introducción a las barandas. Para ver las declaraciones sobre cada tipo de objetivo, consulte los ejemplos de políticas de Guardrail.

Especificar un tipo de barandilla

Para elegir un tipo de barandilla específico, utilice el espacio de nombres: BedrockGuardrails

Tipo de barandilla Nombre de la función Guardrail

Filtro de contenido

BedrockGuardrails::ContentFilter

Ataque rápido

BedrockGuardrails::PromptAttack

Información confidencial

BedrockGuardrails::SensitiveInformation

Selección de una categoría de barandilla

Seleccione una categoría para el tipo de barandilla elegido (consulte). Barandillas compatibles

Por ejemplo: BedrockGuardrails::ContentFilter(["HATE"],[context.output.message])

Efectos para barandas

Para bloquear una solicitud de autorización en una barandilla, utilice los efectos y. permit forbid Estas siguen rigiendo la solicitud de autorización.

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

Para suprimir los resultados de las herramientas, los agentes o los modelos, utilice el suppressOutput efecto. suppressOutputopera con los datos que devuelve una acción. Una vez completada una acción autorizada, evalúa las salidas con respecto a la barandilla y suprime la salida cuando se infringe la barandilla.

suppressOutput (principal, action == AgentCore::Action::"<TargetName>___POST:/invocations", resource == AgentCore::Gateway::"<gateway-arn>") when guardrails { BedrockGuardrails::SensitiveInformation(["US_SOCIAL_SECURITY_NUMBER"], [context.output.text]) .count() > 0 };
importante

Hay dos reglas que determinan qué lado de la solicitud puede leer una barrera y ambas se aplican al crear la política.

  • Un efecto de autorización (permito...) puede leer forbid solo las rutas. context.input.* El suppressOutput efecto puede leer solo context.output.* las rutas. Si se usa context.output con permit o forbid se rechaza conGuardrail '<name>' references 'context.output' but the policy has an authorization effect.

  • Una sola llamada de barandilla no puede mezclar context.input.* context.output.* rutas; todas las rutas de una llamada deben estar del mismo lado. Para filtrar tanto una solicitud como su respuesta, escribe dos llamadas de barandilla en la misma suppressOutput política, una en cada lado. La restricción es por llamada, no por política.

Como una política nombra una acción específica, también debe nombrar un ARN de puerta de enlace específico con. resource == Se rechaza dejar el recurso sin restricciones. Para obtener más información, consulte Requisitos de especificidad de los recursos.

Pasar el contexto a tu barandilla

En un estado de barrera, especifique las rutas de datos, por ejemplocontext.input.message, que identifiquen los valores que se van a extraer de la carga útil de la acción. La barandilla evalúa los valores extraídos. Puede especificar una o más rutas en función de su esquema de solicitud o respuesta.

Por ejemplo: [context.input.message, context.input.systemPrompt]

Puede proporcionar una ruta de datos de dos maneras:

Una ruta de campo, context.input.<field> o context.output.<field>

Úselo cuando el valor que desee sea una cadena única, como el argumento de una herramienta o un campo escalar del cuerpo de una solicitud. La ruta de un campo debe convertirse en una cadena; al crear la política, se rechazará si apunta a un objeto o a una lista.

Un JSONPath: una cadena literal que comienza con $

Úselo cuando el texto esté dentro de una lista o un objeto al que no pueda acceder una ruta de campo (una conversación o una lista de bloques de contenido). Escríbelo enraizado en la carga útil, sin context.input. prefijo: por ejemplo. "$.messages[*].content" Un JSONPath se evalúa como una consulta, por lo que un comodín puede coincidir con muchos valores, incluidos los valores anidados a diferentes profundidades. Esas coincidencias se aplanan en una sola secuencia de texto en lugar de conservarse como una lista.

Puede asignar a cada llamada varias rutas de datos. Cada ruta se extrae de forma independiente y se envía a la barandilla como su propio bloque de contenido, por lo que para que una lista se evalúe como elementos distintos, asigne nombres a los elementos con rutas independientes en lugar de utilizar una ruta comodín.

importante

Un JSONPath no contiene ningún marcador de dirección, por lo que el efecto de la política determina su dirección: suppressOutput lee la respuesta y cualquier otro efecto lee la solicitud. Por lo tanto, una barandilla de salida que utilice un JSONPath debe ser unasuppressOutput, mientras que una de entrada puede ser una forbid o unapermit; ambas leen la solicitud. No mezcle un JSONPath y un context.input.* campo vacío en la misma llamada, ya que ambos implican direcciones opuestas y la solicitud se rechaza por tratarse de un conflicto secundario. suppressOutput

Todas las coincidencias de un solo JSONPath se concatenan en una cadena, sin ningún carácter separador entre ellas. Esto es deliberado: un patrón dividido en dos bloques de contenido, como el número de seguro social 123- seguido de él45-6789, permanece contiguo y no puede pasar desapercibido si un detector busca el patrón completo. También significa que el texto de las coincidencias adyacentes va unido, por lo que una ruta que abarque campos no relacionados puede producir un valor que no contenga ningún campo.

Una ruta que no coincide con nada no aporta nada, siempre que se resuelva al menos otra ruta configurada. Esto permite nombrar varias formas candidatas en una sola llamada, para cargas útiles cuya estructura varía, y hacer que la que exista sea la ruta que se utilice.

aviso

Un JSONPath no se valida al crear la política. A diferencia de una ruta de campo, no AgentCore comprueba su sintaxis ni su adecuación al esquema. Sigue apareciendo una ruta mal formada o una que dé nombre a un campo que tu carga nunca envía. ACTIVE Lo que ocurra en el momento de la evaluación depende de si se resuelve algo más.

Si ninguna ruta de datos configurada se resuelve en ninguna parte del alcance, la evaluación no se cierra. No se puede ejecutar ninguna barrera, por lo que se deniega la solicitud y se asignan nombres a las rutas que no ha podido resolver. Authorization denied: request missing field(s) required for guardrail evaluation El tráfico que estaba funcionando se detiene. Compruebe primero el JSONPath cuando se encuentre con este error.

Si se resuelve al menos una ruta configurada, las barandillas que contienen contenido se ejecutan y deciden con normalidad, y solo se omite la comprobación cuya ruta no se haya resuelto. Esa comprobación no aporta nada y no genera ningún hallazgo, por lo que una sola ruta mal escrita entre varias que funcionan falla silenciosamente y no de forma ruidosa.

Pruebe cada barandilla de JSONPath con el contenido que debería atrapar y tome las rutas de Reaching text inside arrays con un JSONPath en lugar de adaptarlas desde otra API.

Para ver ejemplos de cada ruta de API de inferencia, consulta Cómo llegar al texto de las matrices con un JSONPath.

Umbrales para barandas

Con filtros de contenido y detección rápida de ataques, la barandilla devuelve una puntuación de confianza, que es un valor numérico en el rango [0, 1], donde 0 es una confianza baja y 1 es una confianza alta. La puntuación representa la confianza con la que la barandilla detectó una infracción. Las puntuaciones posibles actuales son los valores discretos {0.0, 0.2, 0.4, 0.6, 0.8, 1.0}.

Para establecer un umbral, proporcione el valor decimal al operador de comparación, por ejemplogreaterThan(decimal("0.4")).

Operadores de comparación de puntuaciones

Puede aplicar los siguientes operadores de comparación a confidenceScoremaxConfidenceScore(), ominConfidenceScore():

Operador De uso

.greaterThan(decimal("X.X"))

Puntuación > umbral

.greaterThanOrEqual(decimal("X.X"))

Puntuación ≥ umbral

.lessThan(decimal("X.X"))

Puntuación < umbral

.lessThanOrEqual(decimal("X.X"))

Puntuación ≤ umbral

Puedes usar una agregación en tu política para extraer y comparar las puntuaciones devueltas por las barandillas:

Agregaciones

Agregación Description (Descripción) Ejemplo

[<category>].confidenceScore

Acceda a la puntuación de confianza de una categoría específica (decimal). No disponible paraSensitiveInformation.

["HATE"].confidenceScore

maxConfidenceScore()

Máxima confianza en todas las categorías escaneadas (decimal)

.maxConfidenceScore()

minConfidenceScore()

Confianza mínima en todas las categorías escaneadas (decimal)

.minConfidenceScore()

count()

Número de hallazgos detectados (largo). Compárelo con un operador entero, no con un decimal método.

.count() > 0

categories()

El conjunto de categorías que detectó la barandilla (conjunto de cadenas)

.categories().contains("HATE")

importante

SensitiveInformationrequiere uno de los métodos de agregación y no admite la indexación por categoría. Una afirmación como la que BedrockGuardrails::SensitiveInformation(["EMAIL"], [context.input.text])["EMAIL"].confidenceScore se rechaza al crear la política, con. Per-category indexing is not supported for SensitiveInformation Utilicecount(), categories()maxConfidenceScore(), o minConfidenceScore() en su lugar. ContentFiltery PromptAttack admiten ambas formas.

¿Cómo elegir un umbral

Si no especifica un umbral al solicitar el servicio de creación, AgentCore establece un valor por defecto. Si redacta sus políticas sin la ayuda del servicio de creación, debe proporcionar el valor límite.

Los siguientes valores predeterminados están calibrados para ofrecer una cobertura amplia con una precisión aceptable para la mayoría de las cargas de trabajo:

Tipo de barandilla Umbral predeterminado

Filtro de contenido

0.2

Detección rápida de ataques

0.4

Información confidencial

0.2

Elegir un umbral personalizado

Si los umbrales predeterminados no cumplen sus requisitos, puede determinar el umbral óptimo para su carga de trabajo mediante uno de los siguientes enfoques.

Opción 1: Evalúe con un conjunto de pruebas de referencia

Utilice este enfoque cuando tenga un conjunto seleccionado de entradas de prueba con resultados esperados claros.

  1. Cree sus políticas y configure el modo de motor de políticas en LOG_ONLY.

  2. Ejecute el conjunto de pruebas a través de la puerta de enlace a la que está conectado su motor de políticas.

  3. Revise los registros de cada evaluación. Cada entrada del registro incluye el contenido evaluado y la puntuación de confianza devuelta por la barandilla.

  4. Para cada resultado, indique si la barandilla debería haber marcado el contenido o no haber hecho nada (verdadero y falso, respectivamente).

  5. Con estas etiquetas, combinadas con las puntuaciones de confianza disponibles en sus registros, cree una matriz de confusión con varios valores de umbral. Compare la precisión y la recuperación en cada umbral para seleccionar el valor que se ajuste a su tolerancia entre los falsos positivos y las detecciones omitidas.

Opción 2: Evalúe en función del tráfico de producción

Utilice este enfoque cuando no disponga de un conjunto de pruebas prediseñado y desee calibrarlo utilizando patrones de tráfico reales.

  1. Cree sus políticas y configure el modo de motor de políticas en LOG_ONLY.

  2. Permita que el motor de políticas evalúe el tráfico de producción. Cada entrada del registro incluye el contenido evaluado y la puntuación de confianza devuelta por la barandilla.

  3. Utilice an LLM-as-a-judge para etiquetar cada resultado registrado como verdadero (la barandilla debería haber marcado el contenido) o falso (la barandilla no debería haber marcado el contenido).

  4. Con estas etiquetas, cree una matriz de confusión con varios valores de umbral. Compare la precisión y la recuperación en cada umbral para seleccionar el valor que se ajuste a su tolerancia entre los falsos positivos y las detecciones omitidas.

Probar las barreras en una política

AgentCore proporciona varios mecanismos para probar las barandillas antes de aplicarlas en el tráfico de producción. Puede controlar la aplicación a nivel del motor de políticas, a nivel de políticas individuales o de ambos modos, lo que le permite validar el comportamiento de las barandillas de forma incremental. Para obtener más información, consulte Probar una política en el modo LOG_ONLY.

Cómo funcionan las barandillas en una política

Puede incluir una barrera de protección en una política en cualquier destino de puerta de enlace. Las barandillas funcionan en:

  • Objetivos del MCP: acción<TargetName>___<ToolName>, alcanzada mediante () POST /mcp JSON-RPC tools/call

  • AgentCore Objetivos de tiempo de ejecución: acción <TargetName>___POST:/invocations

  • Objetivos de inferencia: un objetivo por forma de API, es decir, una acción por API:

    • <TargetName>___POST:/v1/chat/completions

    • <TargetName>___POST:/v1/responses

    • <TargetName>___POST:/v1/messages

    • <TargetName>___GET:/v1/models

  • Objetivos del proxy HTTP: acción <TargetName>___<METHOD>:<uri>

Cuando llega una llamada a su puerta de enlace, el evaluador de políticas realiza lo siguiente:

  1. Coincide con el alcance: identifica qué políticas con barreras se aplican a esta solicitud

  2. Extrae el contenido: extrae el campo especificado por dataPath (por ejemplo,context.input.message) del cuerpo de la solicitud

  3. Llama a la InvokeGuardrailChecks API Bedrock: evalúa el contenido e introduce las puntuaciones de confianza devueltas en el contexto de la evaluación de políticas

  4. Evalúa la política utilizando puntuaciones de protección: compara las puntuaciones de confianza devueltas con el umbral definido en la política

  5. Devuelve una decisión (ALLOWo DENY con las anotaciones de la política) a la pasarela

Nota: Las barandillas no son deterministas, por lo que la misma entrada puede generar salidas diferentes. Las políticas son deterministas; el mismo contexto de evaluación siempre dará como resultado la misma decisión política.

Limitaciones

  • No se admite la coincidencia de patrones o expresiones regulares: las barandillas utilizan puntuaciones de aprendizaje automático, no expresiones regulares

  • Se requiere una barandilla en un when guardrails {…​} bloque; los bloques de barandillas deben tener al menos una barandilla definida en su interior

  • Una llamada a guardrail no puede leer ambos lados de una solicitud; todas las rutas de datos de una llamada deben ser una de las dos. context.input.* context.output.* Una suppressOutput política puede leer ambos lados, pero no de la misma llamada

  • Las barreras no son deterministas: el mismo contenido puede puntuar de forma diferente en llamadas distintas, por lo que una solicitud cercana a tu límite puede aceptarse una vez y rechazarse la próxima vez

  • suppressOutputrequiere un estado de barandilla; su estado debe consistir únicamente en comprobar el estado de la barandilla. No es compatible con los estándares Cedar ni las condiciones temporal {…​}

  • Una ruta de datos $ -JSONPath no se valida en el momento de su creación; no se comprueba su sintaxis ni su ajuste al esquema. Si es la única ruta y el resultado es nulo, la solicitud se deniega en lugar de filtrarse, y la denegación nombra la ruta no resuelta. Si se resuelve otra ruta, la comprobación no resuelta se omite silenciosamente. Consulte Pasar el contexto a la barandilla

nota

En virtud de una autorización (permito)forbid, puede combinar una barandilla con las condiciones normales de Cedar en una sola póliza. when guardrails { E }equivale a una llanura when { E } cuyo cuerpo se llama barandilla; la guardrails etiqueta documenta la intención de la póliza en lugar de restringirla. Coloque la barandilla when e introduzca la solicitud o las condiciones principales. unless De este modo, una sola póliza puede incluir una barrera de protección, una condición de Cedar y una condición temporal: consulte Combinar una barrera de protección con las condiciones de solicitud y Combinar condiciones temporales, de barrera y de solicitud.

suppressOutputes la excepción: su estado debe consistir únicamente en comprobar las barandillas. Para obtener más información, consulte Cómo escribir barandas en las políticas.