Commencer à utiliser Policy dans AgentCore

Dans ce didacticiel, vous allez apprendre à configurer une politique AgentCore et à l'intégrer à une AgentCore passerelle Amazon Bedrock à l'aide de la AgentCore CLI. Vous allez créer un outil de traitement des remboursements avec les politiques de Cedar qui appliquent les règles commerciales relatives aux montants des remboursements.

Conditions préalables

Avant de commencer, assurez-vous que vous disposez des éléments suivants :

Étape 1 : Configuration et installation

Installez la AgentCore CLI :

npm install -g @aws/agentcore

Créez un nouveau AgentCore projet :

Étape 2 : Ajouter une passerelle avec un moteur de politiques

Utilisez la AgentCore CLI pour ajouter une passerelle, une cible de fonction Lambda et un moteur de politiques à votre projet.

Ajouter une passerelle

Créez une passerelle sans autorisation entrante (pour des raisons de simplicité dans ce didacticiel) et associez-y votre agent :

Ajouter une cible de fonction Lambda à l'aide d'un outil de remboursement

Enregistrez votre fonction Lambda en tant que cible de passerelle avec un schéma d'outil qui définit un outil de traitement des remboursements :

Ajouter un moteur de politiques

Créez un moteur de politiques et attachez-le à la passerelle en mode ENFORCE :

Créez une politique Cedar

Fournissez directement un fichier de politique Cedar :

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

Sinon, après avoir déployé vos ressources à l'étape 3, vous pouvez générer une politique Cedar à partir d'une description en langage naturel :

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

L'--generateindicateur nécessite que la passerelle soit d'abord déployée, car il appelle une AWS API qui a besoin de l'ARN de la passerelle pour convertir le langage naturel en Cedar. Cette approche résout automatiquement les ARN des passerelles, ce qui en fait le moyen le plus simple de créer des politiques.

Compréhension de la configuration

Les commandes CLI ci-dessus configurent plusieurs ressources de votre AgentCore projet. Voici une explication détaillée de chaque composant.

Création d'une passerelle

La commande agentcore add gateway crée une passerelle qui agit comme point de terminaison de votre serveur MCP. Le réglage --authorizer-type NONE désactive l'autorisation entrante pour des raisons de simplicité dans ce didacticiel. En production, utilisez l'autorisation IAM ou JWT pour sécuriser votre passerelle.

Ajouter une cible Lambda

La commande agentcore add gateway-target enregistre une fonction Lambda en tant que cible dans la passerelle. Le fichier de schéma de l'outil définit les entrées que les agents peuvent transmettre à la fonction, telles que le montant du remboursement.

Création d'un moteur de politiques

La commande agentcore add policy-engine crée un moteur de politiques, c'est-à-dire un ensemble de politiques Cedar qui évalue et autorise les appels aux outils des agents. Le moteur de politiques intercepte toutes les demandes à la limite de la passerelle et détermine s'il convient d'autoriser ou de refuser chaque action en fonction des politiques définies. Cela fournit une autorisation déterministe en dehors du code de l'agent, garantissant ainsi une application cohérente de la sécurité, quelle que soit la manière dont l'agent est implémenté.

Créer une politique sur le cèdre

Cedar est un langage de politique open source développé par AWS pour la rédaction de politiques d'autorisation. La commande agentcore add policy crée une politique Cedar qui régit les appels aux outils via la passerelle. Vous pouvez soit générer une politique à partir d'une description en langage naturel à l'aide de--generate, soit fournir un fichier de politique Cedar directement à l'aide de. --source

Voici un exemple de politique de Cedar qui autorise les remboursements inférieurs à 1 000$ :

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

La politique utilise :

Attacher la politique à la passerelle

Les --attach-mode ENFORCE drapeaux --attach-to-gateways and de la commande agentcore add policy-engine attachent le moteur de politique à la passerelle en mode ENFORCE. Dans ce mode :

Cela garantit que toutes les opérations des agents via la passerelle sont régies par vos politiques de sécurité.

Étape 3 : Déploiement

Déployez toutes les ressources pour AWS :

agentcore deploy

La AgentCore CLI crée la passerelle, enregistre la cible Lambda, approvisionne le moteur de politiques et attache la politique Cedar. Ce processus prend environ 2 à 3 minutes.

Une fois le déploiement terminé, vous pouvez vérifier l'état de vos ressources :

agentcore status

Étape 4 : tester la politique

Testez la politique en envoyant des demandes à la passerelle. Comme la passerelle l'utilise--authorizer-type NONE, vous pouvez envoyer des demandes directement avec curl.

Test 1 : Remboursement de 500$ (devrait être autorisé)

Le montant du remboursement de 500$ étant inférieur à la limite de 1 000$, le moteur de politiques autorise la demande :

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}}}'

Test 2 : Remboursement de 2000$ (devrait être refusé)

Le montant du remboursement de 2 000$ dépasse la limite de 1 000$. Le moteur de politiques refuse donc la demande :

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}}}'

Ce que vous avez construit

Grâce à ce didacticiel, vous avez créé :

Résolution des problèmes

Si vous rencontrez des problèmes lors de l'installation ou des tests, consultez les problèmes courants et les solutions suivants :

Nettoyage

Pour supprimer les ressources créées dans ce didacticiel, supprimez à la fois la passerelle et le moteur de politiques, puis redéployez :

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

La suppression d'une passerelle ne supprime pas automatiquement le moteur de politique qui lui est attaché. Vous devez supprimer le moteur de politiques séparément à l'aide deagentcore remove policy-engine.