View a markdown version of this page

Erste Schritte mit Policy in AgentCore - Amazon Grundgestein AgentCore
VoraussetzungenSchritt 1: Einrichtung und InstallationSchritt 2: Fügen Sie ein Gateway mit einer Policy-Engine hinzuSchritt 3: BereitstellenSchritt 4: Testen Sie die RichtlinieWas du gebaut hastFehlerbehebungBereinigen

Erste Schritte mit Policy in AgentCore

In diesem Tutorial erfahren Sie, wie Sie Policy in einem Amazon Bedrock AgentCore Gateway mithilfe der AgentCore CLI einrichten AgentCore und in dieses integrieren. Sie erstellen ein Tool zur Bearbeitung von Rückerstattungen mit Cedar-Richtlinien, die Geschäftsregeln für Rückerstattungsbeträge durchsetzen.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie über Folgendes verfügen:

  • AWS Konto mit konfigurierten Anmeldeinformationen. Um Anmeldeinformationen zu konfigurieren, können Sie die AWS Befehlszeilenschnittstelle installieren und verwenden, indem Sie die Schritte unter Erste Schritte mit der AWS CLI ausführen.

  • Node.js 18+ installiert

  • IAM-Berechtigungen für die Erstellung von Rollen, Lambda-Funktionen, Policy-Engines und die Verwendung von Amazon Bedrock AgentCore

  • Eine Lambda-Funktion, die Rückerstattungsanträge verarbeitet. Sie können eine vorhandene Funktion verwenden oder eine für dieses Tutorial erstellen. Notieren Sie sich die Funktion ARN zur Verwendung in Schritt 2.

Schritt 1: Einrichtung und Installation

Installieren Sie die AgentCore CLI:

npm install -g @aws/agentcore

Erstellen Sie ein neues AgentCore Projekt:

Beispiel
AgentCore CLI

  1. agentcore create --name PolicyDemo --defaults
cd PolicyDemo

    Das --defaults Flag erstellt ein Projekt mit einem standardmäßigen Python Strings-Agenten. Der Befehl cd wird in das Projektverzeichnis verschoben, wo nachfolgende Befehle ausgeführt werden müssen.

Interactive

  1. Sie können auch agentcore create ohne Flags ausführen, um den interaktiven Assistenten zu verwenden. Der Assistent führt Sie durch die Auswahl eines Projektnamens, eines Agent-Frameworks, eines Modellanbieters und anderer Optionen. Wechseln Sie nach der Projekterstellung mit cd in das Projektverzeichnis PolicyDemo.

Schritt 2: Fügen Sie ein Gateway mit einer Policy-Engine hinzu

Verwenden Sie die AgentCore CLI, um Ihrem Projekt ein Gateway, ein Lambda-Funktionsziel und eine Policy-Engine hinzuzufügen.

Fügen Sie ein Gateway hinzu

Erstellen Sie ein Gateway ohne eingehende Autorisierung (der Einfachheit halber in diesem Tutorial) und hängen Sie Ihren Agenten daran an:

Beispiel
AgentCore CLI

  1. agentcore add gateway --name PolicyGateway --authorizer-type NONE --runtimes PolicyDemo
Interactive

  1. Führen Sie den Befehl aus, agentcore um die TUI zu öffnen, wählen Sie dann Hinzufügen und dann Gateway aus:

  2. Geben Sie den Gateway-Namen ein:

    Gateway-Assistent: Geben Sie den Namen ein

  3. Wählen Sie den Autorisierungstyp aus. Wählen Sie für dieses Tutorial NONE:

    Gateway-Assistent: Wählen Sie NONE Authorizer

  4. Konfigurieren Sie erweiterte Optionen oder akzeptieren Sie die Standardeinstellungen:

    Gateway-Assistent: erweiterte Konfiguration

  5. Überprüfen Sie die Konfiguration und drücken Sie die Eingabetaste, um Folgendes zu bestätigen:

    Gateway-Assistent: Konfiguration überprüfen

Fügen Sie ein Lambda-Funktionsziel mit einem Rückerstattungstool hinzu

Registrieren Sie Ihre Lambda-Funktion als Gateway-Ziel mit einem Toolschema, das ein Tool zur Bearbeitung von Rückerstattungen definiert:

Beispiel
AgentCore CLI

  1. agentcore add gateway-target --name RefundTarget --type lambda-function-arn \
  --lambda-arn ++<YOUR_LAMBDA_ARN>++ \
  --tool-schema-file refund_tools.json \
  --gateway PolicyGateway

    <YOUR_LAMBDA_ARN>Ersetzen Sie es durch den ARN Ihrer Lambda-Funktion. Die refund_tools.json Datei definiert das Toolschema für das Rückerstattungstool.

Interactive

  1. Führen Sie den Befehl aus, agentcore um die TUI zu öffnen, wählen Sie dann Hinzufügen und anschließend Gateway Target aus:

  2. Geben Sie den Namen des Ziels ein.

  3. Wählen Sie die Lambda-Funktion als Zieltyp aus:

    Gateway-Zielassistent: Lambda-Funktion auswählen

  4. Geben Sie den Lambda-ARN und den Dateipfad für das Tool-Schema ein und bestätigen Sie dann.

Fügen Sie eine Policy-Engine hinzu

Erstellen Sie eine Policy-Engine und hängen Sie sie im ENFORCE-Modus an das Gateway an:

Beispiel
AgentCore CLI

  1. agentcore add policy-engine --name RefundPolicyEngine \
  --attach-to-gateways PolicyGateway \
  --attach-mode ENFORCE
Interactive

  1. Führen Sie den Befehl aus, agentcore um die TUI zu öffnen, wählen Sie dann Hinzufügen und anschließend Policy Engine aus:

  2. Geben Sie den Namen der Policy-Engine ein:

    Assistent für die Policy-Engine: Geben Sie den Namen ein

  3. Wählen Sie die Gateways aus, an die die Policy-Engine angehängt werden soll:

    Assistent für die Policy-Engine: Gateways anhängen

  4. Wählen Sie den Erzwingungsmodus. Wählen Sie ERZWINGEN:

    Policy Engine-Assistent: Wählen Sie den Erzwingungsmodus

Erstellen Sie eine Cedar-Richtlinie

Stellen Sie direkt eine Cedar-Richtliniendatei bereit:

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

Cedar-Richtlinien, die auf bestimmte Gateway-ARNs im resource Feld verweisen (wie im Beispiel unten gezeigt), erfordern eine Bereitstellung in zwei Phasen: zuerst ohne die Richtlinie zur Erstellung des Gateways bereitstellen, dann den Gateway-ARN aus dem Agentcore-Status abrufen, die Cedar-Datei aktualisieren und die Richtlinie hinzufügen, bevor die erneute Bereitstellung erfolgt. Cedar erlaubt keine Wildcard-Ressourcen in Richtlinienerklärungen.

Alternativ können Sie nach der Bereitstellung Ihrer Ressourcen in Schritt 3 eine Cedar-Richtlinie anhand einer Beschreibung in natürlicher Sprache generieren:

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

Das --generate Flag erfordert, dass das Gateway zuerst bereitgestellt wird, da es eine AWS API aufruft, die den Gateway-ARN benötigt, um natürliche Sprache in Cedar zu konvertieren. Dieser Ansatz löst Gateway-ARNs automatisch auf und ist damit der einfachste Weg zur Erstellung von Richtlinien.

Das Setup verstehen

Die obigen CLI-Befehle konfigurieren mehrere Ressourcen in Ihrem AgentCore Projekt. Hier finden Sie eine detaillierte Erklärung der einzelnen Komponenten.

Erstellen Sie ein Gateway

Der Befehl agentcore add gateway erstellt ein Gateway, das als Ihr MCP-Serverendpunkt fungiert. Die Einstellung --authorizer-type NONE deaktiviert der Einfachheit halber in diesem Tutorial die Autorisierung eingehender Nachrichten. Verwenden Sie in der Produktion die IAM- oder JWT-Autorisierung, um Ihr Gateway zu sichern.

Lambda-Ziel hinzufügen

Der Befehl agentcore add gateway-target registriert eine Lambda-Funktion als Ziel im Gateway. Die Tool-Schemadatei definiert die Eingaben, die Agenten an die Funktion weitergeben können, z. B. einen Rückerstattungsbetrag.

Erstellen Sie eine Policy-Engine

Der Befehl agentcore add policy-engine erstellt eine Policy-Engine — eine Sammlung von Cedar-Richtlinien, die Aufrufe von Agententools auswertet und autorisiert. Die Policy-Engine fängt alle Anfragen an der Gateway-Grenze ab und bestimmt auf der Grundlage der definierten Richtlinien, ob jede Aktion zugelassen oder verweigert werden soll. Dies ermöglicht eine deterministische Autorisierung außerhalb des Agentencodes und gewährleistet so eine konsistente Durchsetzung der Sicherheitsvorkehrungen, unabhängig davon, wie der Agent implementiert ist.

Erstellen Sie eine Cedar-Richtlinie

Cedar ist eine Open-Source-Richtliniensprache, die von AWS zum Schreiben von Autorisierungsrichtlinien entwickelt wurde. Der Befehl agentcore add policy erstellt eine Cedar-Richtlinie, die Tool-Aufrufe über das Gateway steuert. Sie können entweder mithilfe einer Beschreibung in natürlicher Sprache eine Richtlinie generieren oder eine --generate Cedar-Richtliniendatei direkt mithilfe von. --source

Im Folgenden finden Sie ein Beispiel für eine Cedar-Richtlinie, die Rückerstattungen unter 1000 USD ermöglicht:

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

Die Richtlinie verwendet:

  • permit— Erlaubt die Aktion (Cedar unterstützt auch forbid das Ablehnen von Aktionen)

  • principal— Die Entität, die die Anfrage stellt

  • action— Das spezifische Tool, das aufgerufen wird (RefundTarget___process_refund)

  • resource— Die Gateway-Instanz, für die die Richtlinie gilt

  • whenBedingung — Zusätzliche Anforderungen (der Betrag muss unter 1000$ liegen)

Richtlinie an Gateway anhängen

Mit den --attach-mode ENFORCE Flags --attach-to-gateways und im Befehl agentcore add policy-engine wird die Policy-Engine im ENFORCE-Modus an das Gateway angehängt. In diesem Modus:

  • Jeder Tool-Aufruf wird abgefangen und anhand aller Richtlinien bewertet

  • Standardmäßig werden alle Aktionen verweigert, sofern sie nicht ausdrücklich erlaubt sind

  • Wenn eine forbid Richtlinie zutrifft, wird der Zugriff verweigert (Forbid-Wins-Semantik)

  • Richtlinienentscheidungen werden zur Überwachung und Einhaltung CloudWatch protokolliert

Dadurch wird sichergestellt, dass alle Agentenoperationen über das Gateway Ihren Sicherheitsrichtlinien unterliegen.

Schritt 3: Bereitstellen

Stellen Sie alle Ressourcen bereit für AWS:

agentcore deploy

Die AgentCore CLI erstellt das Gateway, registriert das Lambda-Ziel, stellt die Policy-Engine bereit und fügt die Cedar-Richtlinie an. Dieser Vorgang dauert ungefähr 2—3 Minuten.

Nach Abschluss der Bereitstellung können Sie den Status Ihrer Ressourcen überprüfen:

agentcore status

Schritt 4: Testen Sie die Richtlinie

Testen Sie die Richtlinie, indem Sie Anfragen an das Gateway senden. Da das Gateway verwendet--authorizer-type NONE, können Sie Anfragen direkt mit curl senden.

Test 1: Rückerstattung von 500$ (sollte erlaubt sein)

Der Rückerstattungsbetrag von 500 USD liegt unter dem Limit von 1000 USD, sodass die Policy-Engine die Anfrage zulässt:

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: Rückerstattung von 2000$ (sollte abgelehnt werden)

Der Rückerstattungsbetrag von 2000$ überschreitet das Limit von 1000$, sodass die Policy-Engine die Anfrage ablehnt:

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

<GATEWAY_URL>Ersetzen Sie es durch die Gateway-URL, die in der Ausgabe des Agentcore-Status angezeigt wird.

Was du gebaut hast

In diesem Tutorial haben Sie Folgendes erstellt:

  • MCP Server (Gateway) — Ein verwalteter Endpunkt für Tools

  • Lambda-Target — Ein im Gateway registriertes Tool zur Bearbeitung von Rückerstattungen

  • Policy Engine — System Cedar-based zur Bewertung von Richtlinien

  • Zedernholzpolitik — Verwaltungsregel, die Rückerstattungen unter 1000$ ermöglicht

Fehlerbehebung

Wenn Sie bei der Installation oder beim Testen auf Probleme stoßen, finden Sie Informationen zu den folgenden häufig auftretenden Problemen und Lösungen:

Problem Lösung

"AccessDeniedException"

Überprüfen Sie die IAM-Berechtigungen für bedrock-agentcore: *

Gateway reagiert nicht

Warten Sie nach der Bereitstellung 30—60 Sekunden auf die DNS-Propagierung

Die Bereitstellung schlägt fehl

Führen Sie agentcore status aus, um den Ressourcenstatus und die Fehlermeldungen zu überprüfen

Die Richtlinie wurde nicht durchgesetzt

Stellen Sie sicher, dass die Policy-Engine im ENFORCE-Modus angeschlossen ist, indem Sie agentcore status ausführen

Cedar-Validierungsfehler bei der Bereitstellung

Cedar-Richtlinien müssen spezifische Ressourcen-ARNs verwenden — Wildcard-Ressourcen (z. B.permit(principal, action, resource);) werden abgelehnt. Verwenden Sie den Gateway-ARN von agentcore status im resource Feld Ihrer Cedar-Richtlinie.

Der Tool-Aufruf wurde unerwartet abgelehnt

Die Policy-Engine wird durchgesetzt und die Cedar-Richtlinie hat die Anfrage abgelehnt. Stellen Sie sicher, dass die Richtlinien action und resource Felder mit dem Tool-Aufruf übereinstimmen.

Die Bereitstellung schlägt mit einem Fehler bei der Richtlinienvalidierung fehl

Im Standardvalidierungsmodus werden sowohl Schemaprüfungen als auch semantische Validierungen FAIL_ON_ANY_FINDINGS ausgeführt, wobei die Richtlinie zurückgewiesen wird, wenn einer der beiden zu Ergebnissen führt. Sie können den Validierungsmodus so einstellen, IGNORE_ALL_FINDINGS dass nur Schemaprüfungen ausgeführt werden, wenn Sie keine semantische Validierung benötigen. Passen Sie für die Produktion die Cedar-Richtlinie so an, dass sie sowohl Schemaprüfungen als auch die semantische Validierung besteht.

Bereinigen

Um die in diesem Tutorial erstellten Ressourcen zu entfernen, entfernen Sie sowohl das Gateway als auch die Policy-Engine und stellen Sie sie dann erneut bereit:

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

Durch das Entfernen eines Gateways wird nicht automatisch die zugehörige Policy-Engine entfernt. Sie müssen die Policy-Engine separat mithilfe von entfernenagentcore remove policy-engine.