# AgentCore での ポリシーの開始方法
このチュートリアルでは、AgentCore でポリシーを設定し、AgentCore CLI を使用して Amazon Bedrock AgentCore Gateway と統合する方法について説明します。Cedar ポリシーを使用して返金処理ツールを作成し、返金金額のビジネスルールを適用します。
**Topics**
+ [前提条件](#policy-getting-started-prerequisites)
+ [ステップ 1: のセットアップとインストール](#policy-getting-started-setup)
+ [ステップ 2: ポリシーエンジンを使用してゲートウェイを追加する](#policy-getting-started-create-script)
+ [ステップ 3: デプロイ](#policy-getting-started-run-setup)
+ [ステップ 4: ポリシーをテストする](#policy-getting-started-test)
+ [構築したもの](#policy-getting-started-results)
+ [トラブルシューティング](#policy-getting-started-troubleshooting)
+ [クリーンアップ](#policy-getting-started-cleanup)
## 前提条件
開始する前に、以下があることを確認してください。
+ ** AWS 認証情報が設定されたアカウント**。認証情報を設定するには、「 [AWS CLI の開始方法](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)」の手順に従って AWS コマンドラインインターフェイスをインストールして使用できます。
+ **Node.js 18 以降**がインストールされている
+ ロール、Lambda 関数、ポリシーエンジンを作成し、Amazon Bedrock AgentCore を使用するための **IAM アクセス許可**
+ 返金リクエストを処理する **Lambda 関数**。このチュートリアルでは、既存の 関数を使用するか、作成できます。ステップ 2 で使用する関数 ARN を書き留めます。
## ステップ 1: のセットアップとインストール
AgentCore CLI をインストールします。
```
npm install -g @aws/agentcore
```
新しい AgentCore プロジェクトを作成します。
**Example**
1.
```
agentcore create --name PolicyDemo --defaults
cd PolicyDemo
```
`--defaults` フラグは、デフォルトの Python Strands エージェントを使用してプロジェクトを作成します。**cd** コマンドはプロジェクトディレクトリに移動し、後続のコマンドを実行する必要があります。
1. フラグ`agentcore create`なしで を実行して、インタラクティブウィザードを使用することもできます。このウィザードでは、プロジェクト名、エージェントフレームワーク、モデルプロバイダー、その他のオプションを選択する手順を説明します。プロジェクトの作成後、**cd PolicyDemo** を使用してプロジェクトディレクトリに変更します。
## ステップ 2: ポリシーエンジンを使用してゲートウェイを追加する
AgentCore CLI を使用して、ゲートウェイ、Lambda 関数ターゲット、ポリシーエンジンをプロジェクトに追加します。
**ゲートウェイを追加する**
インバウンド認可なしでゲートウェイを作成し (このチュートリアルではわかりやすくするため）、エージェントをアタッチします。
**Example**
1.
```
agentcore add gateway --name PolicyGateway --authorizer-type NONE --runtimes PolicyDemo
```
1. `agentcore` を実行して TUI を開き、**追加**を選択して**ゲートウェイ** を選択します。
1. ゲートウェイ名を入力します。
1. オーソライザータイプを選択します。このチュートリアルでは、**NONE** を選択します。
1. 詳細オプションを設定するか、デフォルトを受け入れます。
1. 設定を確認し、**Enter** キーを押して以下を確認します。
**返金ツールを使用して Lambda 関数ターゲットを追加する**
返金処理ツールを定義するツールスキーマを使用して、Lambda 関数をゲートウェイターゲットとして登録します。
**Example**
1.
```
agentcore add gateway-target --name RefundTarget --type lambda-function-arn \
--lambda-arn ++++ \
--tool-schema-file refund_tools.json \
--gateway PolicyGateway
```
を Lambda 関数の ARN ``に置き換えます。`refund_tools.json` ファイルは、返金ツールのツールスキーマを定義します。
1. `agentcore` を実行して TUI を開き、**ゲートウェイターゲット** **を追加して**選択します。
1. ターゲット名を入力します。
1. ターゲットタイプとして **Lambda 関数**を選択します。
1. Lambda ARN とツールスキーマファイルパスを入力し、確認します。
**ポリシーエンジンを追加する**
ポリシーエンジンを作成し、ENFORCE モードでゲートウェイにアタッチします。
**Example**
1.
```
agentcore add policy-engine --name RefundPolicyEngine \
--attach-to-gateways PolicyGateway \
--attach-mode ENFORCE
```
1. `agentcore` を実行して TUI を開き、**追加**を選択して**ポリシーエンジン** を選択します。
1. ポリシーエンジン名を入力します。
1. ポリシーエンジンをアタッチするゲートウェイを選択します。
1. エンフォースメントモードを選択します。**ENFORCE** を選択します。
**Cedar ポリシーを作成する**
Cedar ポリシーファイルを直接指定します。
```
agentcore add policy --name RefundLimit \
--engine RefundPolicyEngine \
--source refund_policy.cedar
```
**注記**
`resource` フィールド内の特定のゲートウェイ ARNs を参照する Cedar ポリシー (以下の例を参照) には、2 つのフェーズのデプロイが必要です。まずゲートウェイを作成するポリシーなしでデプロイし、次に**エージェントコアステータス** からゲートウェイ ARN を取得し、Cedar ファイルを更新して、再デプロイする前にポリシーを追加します。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 プロジェクトで複数のリソースを設定します。各コンポーネントの詳細な説明を次に示します。
**Topics**
+ [ゲートウェイを作成する](#policy-create-gateway)
+ [Lambda ターゲットを追加する](#policy-add-lambda-target)
+ [ポリシーエンジンを作成する](#policy-create-policy-engine)
+ [Cedar ポリシーの作成](#policy-create-cedar-policy)
+ [ポリシーをゲートウェイにアタッチする](#policy-attach-to-gateway)
#### ゲートウェイを作成する
**エージェントコアのゲートウェイ追加**コマンドは、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::"")
when {
context.input.amount < 1000
};
```
ポリシーは以下を使用します。
+ `permit` – アクションを許可します (Cedar はアクションを拒否`forbid`することもできます)
+ `principal` – リクエストを行うエンティティ
+ `action` – 呼び出される特定のツール (RefundTarget\_\_process\_refund)
+ `resource` – ポリシーが適用されるゲートウェイインスタンス
+ `when` 条件 – 追加要件 (金額は < 1000 USD である必要があります)
#### ポリシーをゲートウェイにアタッチする
**agentcore add policy-engine** コマンドの `--attach-to-gateways`および `--attach-mode ENFORCE`フラグは、ポリシーエンジンを ENFORCE モードでゲートウェイにアタッチします。このモードでは、次のようになります。
+ すべてのツール呼び出しが傍受され、すべてのポリシーに対して評価されます。
+ デフォルトでは、明示的に許可されていない限り、すべてのアクションは拒否されます。
+ いずれかの`forbid`ポリシーが一致した場合、アクセスは拒否されます (forbid-wins セマンティクス)
+ ポリシーの決定は、モニタリングとコンプライアンスのために CloudWatch に記録されます。
これにより、ゲートウェイ経由のすべてのエージェントオペレーションがセキュリティポリシーによって管理されます。
## ステップ 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 ++++ \
-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 ++++ \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"RefundTarget___process_refund","arguments":{"amount":2000}}}'
```
**注記**
を、**エージェントコアステータス**の出力に表示されるゲートウェイ URL ``に置き換えます。
## 構築したもの
このチュートリアルでは、以下を作成しました。
+ **MCP サーバー (ゲートウェイ)** – ツールのマネージドエンドポイント
+ **Lambda ターゲット** – ゲートウェイに登録された返金処理ツール
+ **ポリシーエンジン** – Cedar ベースのポリシー評価システム
+ **Cedar ポリシー** – 1,000 USD 未満の返金を許可するガバナンスルール
## トラブルシューティング
セットアップまたはテスト中に問題が発生した場合は、以下の一般的な問題と解決策を参照してください。
| 問題 | ソリューション |
| --- | --- |
| 「AccessDeniedException」 | bedrock-agentcore の IAM アクセス許可を確認する:\* |
| ゲートウェイが応答しない | DNS 伝播のデプロイ後 30～60 秒待機する |
| デプロイが失敗する | **エージェントコアステータス**を実行してリソースの状態をチェックし、エラーメッセージを確認する |
| ポリシーが適用されない | **エージェントコアステータス**を実行して、ポリシーエンジンが ENFORCE モードでアタッチされていることを確認します。 |
| デプロイ中の Cedar 検証エラー | Cedar ポリシーは特定のリソース ARNs を使用する必要があります。ワイルドカードリソース ( など) `permit(principal, action, resource);` は拒否されます。Cedar ポリシーの `resource`フィールドで、**エージェントコアステータス**のゲートウェイ ARN を使用します。 |
| ツール呼び出しが予期せず拒否されました | ポリシーエンジンが強制しており、Cedar ポリシーがリクエストを拒否しました。ポリシーの フィールド`action`と `resource`フィールドが、実行されるツール呼び出しと一致していることを確認します。 |
| デプロイがポリシー検証エラーで失敗する | デフォルトの検証モードでは、スキーマチェックとセマンティック検証の両方`FAIL_ON_ANY_FINDINGS`が実行され、いずれかの が検出結果を生成する場合、ポリシーは拒否されます。セマンティック検証が必要ない場合は、スキーマチェックのみを実行する`IGNORE_ALL_FINDINGS`ように検証モードを に設定できます。本番環境では、スキーマチェックとセマンティック検証の両方に合格するように Cedar ポリシーを修正します。 |
## クリーンアップ
このチュートリアルで作成したリソースを削除するには、ゲートウェイとポリシーエンジンの両方を削除してから再デプロイします。
```
agentcore remove gateway --name PolicyGateway
agentcore remove policy-engine --name RefundPolicyEngine
agentcore deploy
```
ゲートウェイを削除しても、アタッチされたポリシーエンジンは自動的に削除されません。ポリシーエンジンは、 を使用して個別に削除する必要があります`agentcore remove policy-engine`。