Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Commencer à utiliser Policy dans AgentCore

Dans ce didacticiel, vous allez apprendre à configurer Policy in AgentCore et à l'intégrer à Amazon Bedrock AgentCore Gateway à l'aide de l' AgentCore interface de ligne de commande. 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 de disposer des éléments suivants :

La AgentCore CLI vérifie la pile d'amorçage du CDK pendant le déploiement. Si le bootstrap est requis, le déploiement interactif demande une confirmation. agentcore deploy --yesUtilisez-le pour l'autoriser automatiquement.

É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 l' AgentCore interface de ligne de commande 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 simplifier ce didacticiel) et associez-y votre agent :

Ajouter une cible de fonction Lambda avec 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. Créez un refund_tools.json fichier dans le répertoire de votre projet avec le contenu suivant :

[
  {
    "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"]
    }
  }
]

Ajouter un moteur de politiques

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

Créez une politique Cedar

Fournissez directement un fichier de politique Cedar. Cedar n'autorise pas les ressources génériques dans les déclarations de politique. Cela nécessite un déploiement en deux phases : d'abord déployer sans la politique de création de la passerelle, puis récupérer l'ARN de la passerelle. Ajoutez ensuite la politique et redéployez.

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éployée en premier, 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 la méthode la plus simple pour créer des politiques.

Comprendre 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 fait office de point de terminaison de votre serveur MCP. Ce paramètre --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, comme le montant du remboursement.

Création d'un moteur de politiques

La commande agentcore add policy-engine crée un moteur de politiques, 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 faut autoriser ou 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 d'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 USD :

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 indicateurs --attach-to-gateways et de la commande agentcore add policy-engine associent 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 et provisionne le moteur de politique. Si vous avez fourni un fichier de politique ARN-based Cedar, ajoutez-le après ce déploiement et exécutez à nouveau agentcore deploy pour le joindre. Ce processus prend environ 2 à 3 minutes par déploiement.

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

agentcore status

Étape 4 : Testez la politique

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

L'URL de la passerelle affichée dans la sortie de l'état agentcore est le point de terminaison de base. Les requêtes MCP pointent vers le /mcp chemin de ce point de terminaison, ajoutez-les donc /mcp à l'URL avant d'envoyer des requêtes.

Test 1 : remboursement de 500 USD (devrait être autorisé)

Le montant du remboursement de 500 USD est inférieur à la limite de 1 000 USD. Le moteur de politique autorise donc la demande :

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

Test 2 : remboursement de 2 000 USD (doit être refusé)

Le montant du remboursement de 2 000 dollars américains dépasse la limite de 1 000 dollars américains. Le moteur de politique refuse donc la demande :

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

Ce que tu as construit

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

Résolution des problèmes

Si vous rencontrez des problèmes lors de la configuration ou des tests, consultez les solutions et problèmes courants 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 y est associé. Vous devez supprimer le moteur de politiques séparément à l'aide deagentcore remove policy-engine.