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.

Cómo empezar a usar la política en AgentCore

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

Requisitos previos

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

La AgentCore CLI comprueba la pila de arranque del CDK durante la implementación. Si se requiere el arranque, la implementación interactiva solicita una confirmación. agentcore deploy --yesUtilícelo para autorizarlo automáticamente.

Paso 1: Configurar e instalar

Instale la AgentCore CLI:

npm install -g @aws/agentcore

Cree un AgentCore proyecto nuevo:

Paso 2: Agregue una puerta de enlace con un motor de políticas

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

Agregue una puerta de enlace

Crea una puerta de enlace sin autorización de entrada (para simplificar este tutorial) y adjunta a ella a tu agente:

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

Registra tu función Lambda como objetivo de pasarela con un esquema de herramientas que defina una herramienta de procesamiento de reembolsos. Cree un refund_tools.json archivo en el directorio de su proyecto con el siguiente contenido:

[
  {
    "name": "process_refund",
    "description": "Process a customer refund request for a given dollar amount",
    "inputSchema": {
      "type": "object",
      "description": "Input for processing a refund",
      "properties": {
        "amount": {
          "type": "integer",
          "description": "The refund amount in dollars"
        }
      },
      "required": ["amount"]
    }
  }
]

Agregue un motor de políticas

Cree un motor de políticas y adjúntelo a la puerta de enlace en modo ENFORCE:

Crea una política de Cedar

Proporcione un archivo de política de Cedar directamente. Cedar no permite incluir recursos comodín en las declaraciones de política. Esto requiere una implementación en dos fases: primero, despliéguela sin la política para crear la puerta de enlace y, a continuación, recupere el ARN de la puerta de enlace. A continuación, agregue la política y vuelva a implementarla.

Como alternativa, después de implementar sus 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

La --generate bandera requiere que primero se implemente la puerta de enlace, 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 la puerta de enlace, lo que lo convierte en la ruta más sencilla para crear políticas.

Comprender la configuración

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

Crea 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 desactiva la autorización entrante para simplificar este tutorial. En producción, usa la autorización de IAM o JWT para proteger tu puerta de enlace.

Agregue un 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 las entradas que los agentes pueden transferir a la función, como el importe de un 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 a las herramientas de los agentes. 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 de seguridad coherente independientemente de cómo se implemente el agente.

Cree una política de cedro

Cedar es un lenguaje de políticas de código abierto desarrollado 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 pasarela. Puede generar una política a partir de una descripción en lenguaje natural usando --generate o proporcionar un archivo de política de Cedar directamente usando. --source

El siguiente es un ejemplo de una política de Cedar que permite reembolsos inferiores a 1000 USD:

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 de Lambda y aprovisiona el motor de políticas. Si proporcionó un archivo de políticas de ARN-based Cedar, agréguelo después de esta implementación y vuelva a ejecutar agentcore deploy para adjuntarlo. Este proceso tarda aproximadamente de 2 a 3 minutos por implementación.

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 puerta de enlace. Como la puerta de enlace usa--authorizer-type NONE, puedes enviar solicitudes directamente con curl.

La URL de la puerta de enlace que se muestra en la salida del estado de agentcore es el punto final base. Las solicitudes de MCP van a la /mcp ruta de ese punto final, así que agréguelas /mcp a la URL antes de enviar las solicitudes.

Prueba 1: reembolso de 500 USD (debería estar permitido)

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

curl -X POST ++<GATEWAY_URL>++/mcp \
  -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 USD (debería denegarse)

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

curl -X POST ++<GATEWAY_URL>++/mcp \
  -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 tiene 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 implementar:

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

La eliminación de una puerta de enlace no elimina automáticamente su motor de políticas adjunto. Debe eliminar el motor de políticas por separado medianteagentcore remove policy-engine.