Cómo empezar con Policy en AgentCore

En este tutorial, aprenderá a configurar una política AgentCore e integrarla con Amazon Bedrock AgentCore Gateway mediante la AgentCore CLI. Creará una herramienta de procesamiento de reembolsos con las políticas de Cedar que hagan cumplir las normas comerciales sobre los montos de los reembolsos.

Requisitos previos

Antes de empezar, asegúrate de tener lo siguiente:

Paso 1: Configurar e instalar

Instale la AgentCore CLI:

npm install -g @aws/agentcore

Cree un AgentCore proyecto nuevo:

Paso 2: Añadir una pasarela con un motor de políticas

Utilice la AgentCore CLI para añadir una puerta de enlace, un objetivo de función Lambda y un motor de políticas a su proyecto.

Agregue una puerta de enlace

Cree una puerta de enlace sin autorización de entrada (para simplificar este tutorial) y adjunte su agente a ella:

Agregue un objetivo de función Lambda con una herramienta de reembolso

Registre su función Lambda como destino de puerta de enlace con un esquema de herramientas que defina una herramienta de procesamiento de reembolsos:

Agregue un motor de políticas

Cree un motor de políticas y conéctelo a la puerta de enlace en el modo ENFORCE:

Cree una política de Cedar

Proporcione directamente un archivo de política de Cedar:

agentcore add policy --name RefundLimit \
  --engine RefundPolicyEngine \
  --source refund_policy.cedar

Como alternativa, después de implementar los recursos en el paso 3, puede generar una política de Cedar a partir de una descripción en lenguaje natural:

agentcore add policy --name RefundLimit \
  --engine RefundPolicyEngine \
  --generate "Only allow refunds under 1000 dollars" \
  --gateway PolicyGateway

El --generate indicador requiere que la puerta de enlace se implemente primero, ya que llama a una AWS API que necesita el ARN de la puerta de enlace para convertir el lenguaje natural en Cedar. Este enfoque resuelve automáticamente los ARN de las puertas de enlace, lo que lo convierte en la forma más sencilla de crear políticas.

Comprender la configuración

Los comandos CLI anteriores configuran varios recursos AgentCore del proyecto. Esta es una explicación detallada de cada componente.

Cree una puerta de enlace

El comando agentcore add gateway crea una puerta de enlace que actúa como punto final del servidor MCP. La configuración --authorizer-type NONE deshabilita la autorización entrante para simplificar este tutorial. En producción, utilice la autorización de IAM o JWT para proteger su puerta de enlace.

Añadir objetivo Lambda

El comando agentcore add gateway-target registra una función Lambda como destino en la puerta de enlace. El archivo de esquema de la herramienta define los datos que los agentes pueden transferir a la función, como el importe del reembolso.

Cree un motor de políticas

El comando agentcore add policy-engine crea un motor de políticas: un conjunto de políticas de Cedar que evalúa y autoriza las llamadas de los agentes a las herramientas. El motor de políticas intercepta todas las solicitudes en el límite de la puerta de enlace y determina si se permite o deniega cada acción en función de las políticas definidas. Esto proporciona una autorización determinista fuera del código del agente, lo que garantiza una aplicación coherente de la seguridad independientemente de cómo se implemente el agente.

Cree una política de Cedar

Cedar es un lenguaje de políticas de código abierto desarrollado por AWS para redactar políticas de autorización. El comando agentcore add policy crea una política de Cedar que rige las llamadas a las herramientas a través de la puerta de enlace. Puede generar una política a partir de una descripción en lenguaje natural utilizando --generate o proporcionar un archivo de política de Cedar directamente utilizando. --source

El siguiente es un ejemplo de una política de Cedar que permite reembolsos de menos de 1000$:

permit(principal,
  action == AgentCore::Action::"RefundTarget___process_refund",
  resource == AgentCore::Gateway::"<gateway-arn>")
when {
  context.input.amount < 1000
};

La política utiliza:

Adjunte la política a Gateway

Los --attach-mode ENFORCE indicadores --attach-to-gateways y del comando agentcore add policy-engine conectan el motor de políticas a la puerta de enlace en modo ENFORCE. En este modo:

Esto garantiza que todas las operaciones de los agentes a través de la puerta de enlace se rijan por sus políticas de seguridad.

Paso 3: Implementar

Despliegue todos los recursos para AWS:

agentcore deploy

La AgentCore CLI crea la puerta de enlace, registra el objetivo Lambda, aprovisiona el motor de políticas y adjunta la política de Cedar. Este proceso tarda aproximadamente de 2 a 3 minutos.

Una vez completada la implementación, puede verificar el estado de sus recursos:

agentcore status

Paso 4: Probar la política

Pruebe la política enviando solicitudes a la pasarela. Como la pasarela lo usa--authorizer-type NONE, puedes enviar solicitudes directamente con curl.

Prueba 1: reembolsar 500$ (debería permitirse)

El importe del reembolso de 500$ está por debajo del límite de 1000$, por lo que el motor de políticas permite la solicitud:

curl -X POST ++<GATEWAY_URL>++ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"RefundTarget___process_refund","arguments":{"amount":500}}}'

Prueba 2: Reembolso de 2000$ (si se deniega)

El importe del reembolso de 2000$ supera el límite de 1000$, por lo que el motor de políticas deniega la solicitud:

curl -X POST ++<GATEWAY_URL>++ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"RefundTarget___process_refund","arguments":{"amount":2000}}}'

Lo que has creado

A través de este tutorial, has creado:

Resolución de problemas

Si encuentra problemas durante la configuración o las pruebas, consulte los siguientes problemas y soluciones comunes:

Limpieza

Para eliminar los recursos creados en este tutorial, elimine tanto la puerta de enlace como el motor de políticas y, a continuación, vuelva a desplegarlos:

agentcore remove gateway --name PolicyGateway
agentcore remove policy-engine --name RefundPolicyEngine
agentcore deploy

Al eliminar una puerta de enlace, no se elimina automáticamente el motor de políticas asociado. Debe eliminar el motor de políticas por separado utilizandoagentcore remove policy-engine.