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.
Temas
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
VIOLENCEoHATE. 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
JAILBREAKoPROMPT_INJECTION. Devuelve una puntuación de confianza para cada categoría que nombre. -
SensitiveInformation -
Entidades sensibles como
EMAILoUS_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 |
|
|
|
Detección rápida de ataques |
|
|
|
Información confidencial |
|
Identidad personal: |
|
Financiero — |
||
|
Identificadores gubernamentales y de salud: |
||
|
Credenciales y red: |
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")) };
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
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.
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 |
|
|
Ataque rápido |
|
|
Información confidencial |
|
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 };
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 leerforbidsolo las rutas.context.input.*ElsuppressOutputefecto puede leer solocontext.output.*las rutas. Si se usacontext.outputconpermitoforbidse 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 mismasuppressOutputpolí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>ocontext.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.
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.
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.
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 |
|---|---|
|
|
Puntuación > umbral |
|
|
Puntuación ≥ umbral |
|
|
Puntuación < umbral |
|
|
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 |
|---|---|---|
|
|
Acceda a la puntuación de confianza de una categoría específica (decimal |
|
|
|
Máxima confianza en todas las categorías escaneadas (decimal |
|
|
|
Confianza mínima en todas las categorías escaneadas (decimal |
|
|
|
Número de hallazgos detectados (largo |
|
|
|
El conjunto de categorías que detectó la barandilla (conjunto de cadenas |
|
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.
-
Cree sus políticas y configure el modo de motor de políticas en LOG_ONLY.
-
Ejecute el conjunto de pruebas a través de la puerta de enlace a la que está conectado su motor de políticas.
-
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.
-
Para cada resultado, indique si la barandilla debería haber marcado el contenido o no haber hecho nada (verdadero y falso, respectivamente).
-
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.
-
Cree sus políticas y configure el modo de motor de políticas en LOG_ONLY.
-
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.
-
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).
-
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 /mcpJSON-RPCtools/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:
-
Coincide con el alcance: identifica qué políticas con barreras se aplican a esta solicitud
-
Extrae el contenido: extrae el campo especificado por
dataPath(por ejemplo,context.input.message) del cuerpo de la solicitud -
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
-
Evalúa la política utilizando puntuaciones de protección: compara las puntuaciones de confianza devueltas con el umbral definido en la política
-
Devuelve una decisión (
ALLOWoDENYcon 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.*UnasuppressOutputpolí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 condicionestemporal {…} -
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
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.