AgentCore での ポリシーの開始方法

このチュートリアルでは、AgentCore でポリシーを設定し、AgentCore CLI を使用して Amazon Bedrock AgentCore Gateway と統合する方法について説明します。Cedar ポリシーを使用して返金処理ツールを作成し、返金金額のビジネスルールを適用します。

前提条件

開始する前に、以下があることを確認してください。

ステップ 1: のセットアップとインストール

AgentCore CLI をインストールします。

npm install -g @aws/agentcore

新しい AgentCore プロジェクトを作成します。

ステップ 2: ポリシーエンジンを使用してゲートウェイを追加する

AgentCore CLI を使用して、ゲートウェイ、Lambda 関数ターゲット、ポリシーエンジンをプロジェクトに追加します。

ゲートウェイを追加する

インバウンド認可なしでゲートウェイを作成し (このチュートリアルではわかりやすくするため）、エージェントをアタッチします。

返金ツールを使用して Lambda 関数ターゲットを追加する

返金処理ツールを定義するツールスキーマを使用して、Lambda 関数をゲートウェイターゲットとして登録します。

ポリシーエンジンを追加する

ポリシーエンジンを作成し、ENFORCE モードでゲートウェイにアタッチします。

Cedar ポリシーを作成する

Cedar ポリシーファイルを直接指定します。

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

または、ステップ 3 でリソースをデプロイした後、自然言語の説明から Cedar ポリシーを生成することもできます。

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

この--generateフラグでは、自然言語を Cedar に変換するためにゲートウェイ ARN を必要とする AWS API を呼び出すため、ゲートウェイを最初にデプロイする必要があります。このアプローチでは、ゲートウェイ ARNs、ポリシーを作成するための最も簡単なパスになります。

セットアップについて

上記の CLI コマンドは、AgentCore プロジェクトで複数のリソースを設定します。各コンポーネントの詳細な説明を次に示します。

ゲートウェイを作成する

エージェントコアのゲートウェイ追加コマンドは、MCP サーバーエンドポイントとして機能するゲートウェイを作成します。を設定すると、このチュートリアルでわかりやすいようにインバウンド認可--authorizer-type NONEが無効になります。本番環境では、IAM または JWT 認可を使用してゲートウェイを保護します。

Lambda ターゲットを追加する

エージェントコア add gateway-target コマンドは、Lambda 関数をゲートウェイのターゲットとして登録します。ツールスキーマファイルは、返金額など、エージェントが関数に渡すことができる入力を定義します。

ポリシーエンジンを作成する

エージェントコア add policy-engine コマンドは、エージェントツール呼び出しを評価および認可する Cedar ポリシーのコレクションであるポリシーエンジンを作成します。ポリシーエンジンは、ゲートウェイの境界にあるすべてのリクエストを傍受し、定義されたポリシーに基づいて各アクションを許可するか拒否するかを決定します。これにより、エージェントのコード外で決定的な認可が提供され、エージェントの実装方法に関係なく一貫したセキュリティ適用が保証されます。

Cedar ポリシーの作成

Cedar は、認可ポリシーを記述 AWS するために によって開発されたオープンソースのポリシー言語です。エージェントコアのポリシー追加コマンドは、ゲートウェイを介したツール呼び出しを管理する Cedar ポリシーを作成します。を使用して自然言語の説明からポリシーを生成するか、 を使用して Cedar --generate ポリシーファイルを直接指定できます--source。

以下は、1,000 USD 未満の返金を許可する Cedar ポリシーの例です。

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

ポリシーは以下を使用します。

ポリシーをゲートウェイにアタッチする

agentcore add policy-engine コマンドの --attach-to-gatewaysおよび --attach-mode ENFORCEフラグは、ポリシーエンジンを ENFORCE モードでゲートウェイにアタッチします。このモードでは、次のようになります。

これにより、ゲートウェイ経由のすべてのエージェントオペレーションがセキュリティポリシーによって管理されます。

ステップ 3: デプロイ

すべてのリソースを次の場所にデプロイします AWS。

agentcore deploy

AgentCore CLI はゲートウェイを作成し、Lambda ターゲットを登録し、ポリシーエンジンをプロビジョニングして、Cedar ポリシーをアタッチします。このプロセスには約 2～3 分かかります。

デプロイが完了したら、リソースのステータスを確認できます。

agentcore status

ステップ 4: ポリシーをテストする

ゲートウェイにリクエストを送信してポリシーをテストします。ゲートウェイは を使用するため--authorizer-type NONE、curl を使用してリクエストを直接送信できます。

テスト 1: 500 USD の返金 (許可)

500 USD の返金額は 1000 USD の制限を下回っているため、ポリシーエンジンはリクエストを許可します。

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

テスト 2: 2,000 USD の返金 (拒否)

2,000 USD の返金金額が 1,000 USD の制限を超えているため、ポリシーエンジンはリクエストを拒否します。

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

構築したもの

このチュートリアルでは、以下を作成しました。

トラブルシューティング

セットアップまたはテスト中に問題が発生した場合は、以下の一般的な問題と解決策を参照してください。

クリーンアップ

このチュートリアルで作成したリソースを削除するには、ゲートウェイとポリシーエンジンの両方を削除してから再デプロイします。

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

ゲートウェイを削除しても、アタッチされたポリシーエンジンは自動的に削除されません。ポリシーエンジンは、 を使用して個別に削除する必要がありますagentcore remove policy-engine。