AgentCore Gateway

Amazon Bedrock AgentCore Gatewayプロジェクトを生成します。AgentCore Gatewayは、1つ以上のMCPサーバーターゲットを単一のMCPエンドポイントの背後に集約し、すべてのツール呼び出しをCedarポリシーエンジンに対して評価し、MCPサーバーへのアウトバウンドトラフィックにIAM SigV4で署名するマネージドエントリーポイントです。

使用方法

AgentCore Gatewayの生成

VSCode
CLI

インストール Nx Console VSCode Plugin まだインストールしていない場合
VSCodeでNxコンソールを開く
クリック Generate (UI) "Common Nx Commands"セクションで
検索 @aws/nx-plugin - agentcore-gateway
必須パラメータを入力
クリック Generate

pnpm nx g @aws/nx-plugin:agentcore-gateway

yarn nx g @aws/nx-plugin:agentcore-gateway

npx nx g @aws/nx-plugin:agentcore-gateway

bunx nx g @aws/nx-plugin:agentcore-gateway

変更されるファイルを確認するためにドライランを実行することもできます

pnpm nx g @aws/nx-plugin:agentcore-gateway --dry-run

yarn nx g @aws/nx-plugin:agentcore-gateway --dry-run

npx nx g @aws/nx-plugin:agentcore-gateway --dry-run

bunx nx g @aws/nx-plugin:agentcore-gateway --dry-run

オプション

パラメータ	型	デフォルト	説明
name 必須	string	-	AgentCore Gateway プロジェクトの名前
directory	string	packages	ゲートウェイプロジェクトが配置される親ディレクトリ。
subDirectory	string	-	プロジェクトが配置されるサブディレクトリ。デフォルトではプロジェクト名になります。
protocol	mcp	mcp	ゲートウェイが公開するインバウンドプロトコル。現在は mcp のみがサポートされています。将来的に追加のプロトコルが追加される可能性があります。
auth	iam	iam	ゲートウェイへのインバウンドリクエストを認証するために使用される方法。現在は iam のみがサポートされています。将来的に cognito と custom-jwt が追加される可能性があります。
cedarPolicy	boolean	true	ゲートウェイで詳細な認可を実施する Cedar ポリシーエンジンを含めるかどうか。
infra	agentcore \| none	agentcore	ゲートウェイをホストするインフラストラクチャのタイプ。ホスティングなしの場合は none を選択してください。
iac	inherit \| cdk \| terraform	inherit	優先される IaC プロバイダー。デフォルトでは初期選択から継承されます。
preferInstallDependencies	boolean	true	ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します（後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレーターの出力

ジェネレーターは、packages/<name>/に新しいプロジェクトを作成し、さらにインフラストラクチャ用のCDKコンストラクトまたはTerraformモジュールを追加します：

Directorypackages/<name>/
- Directorypolicies/ Cedarポリシーソースファイル（cedarPolicy: falseの場合は省略）
  - permit-all.cedar 同じAWSアカウント内の認証された呼び出し元を許可するデフォルトのCedarポリシー
  - README.md Cedarポリシーの記述に関するリファレンス
- local-dev.ts ローカル開発用にアタッチされたMCPサーバーを集約するローカルゲートウェイ
- project.json serveおよびdevターゲットを追加

インフラストラクチャ

インフラストラクチャは、infraがagentcore（デフォルト）の場合に生成されます。infra: noneの場合、インフラストラクチャは生成されません — 後でinfra: agentcoreでジェネレーターを再実行して追加できます。

このジェネレータは選択した iacProvider に基づいてInfrastructure as Codeを生成するため、packages/common に関連するCDKコンストラクトまたはTerraformモジュールを含むプロジェクトを作成します。

共通のInfrastructure as Codeプロジェクトは以下の構造を持ちます：

CDK
Terraform

Directorypackages/common/constructs
- Directorysrc
  - Directoryapp/ プロジェクト/ジェネレータ固有のインフラストラクチャ用コンストラクト
    …
  - Directorycore/ app 内のコンストラクトで再利用される汎用コンストラクト
    …
  - index.ts app からコンストラクトをエクスポートするエントリーポイント
- project.json プロジェクトのビルドターゲットと設定

Directorypackages/common/terraform
- Directorysrc
  - Directoryapp/ プロジェクト/ジェネレータ固有のインフラストラクチャ用Terraformモジュール
    …
  - Directorycore/ app 内のモジュールで再利用される汎用モジュール
    …
- project.json プロジェクトのビルドターゲットと設定

CDK
Terraform

Directorypackages/common/constructs/src
- Directorycore
  - Directoryagentcore-gateway/ 共有ゲートウェイコンストラクト（readinessプローブ、Cedarポリシーロード）
    …
- Directoryapp
  - Directorygateways
    Directory<name>/
    <name>.ts GatewayをデプロイするためのCDKコンストラクト

生成されたコンストラクトは、以下のAWSリソースを作成します：

GatewayAuthorizer.usingAwsIam()（インバウンドIAM認証）を使用してMCPプロトコル用に構成されたAgentCore::Gateway
ENFORCEモードで実行され、GatewayにアタッチされたAgentCore::PolicyEngine（cedarPolicy: falseの場合は省略）
policies/内の.cedarファイルごとに1つのAgentCore::Policy

Gateway URLは、ランタイム設定のagentcore.gateways.<ClassName>名前空間に自動的に登録されるため、エージェントは実行時にそれを検出できます。

ポリシーの記述

Cedarは、AgentCore Gatewayがツール呼び出しを認可するために使用するポリシー言語です。Gatewayを通過するすべてのtools/listおよびtools/callリクエストは、アタッチされたポリシーセットに対して評価され、呼び出し元はリクエストが成功するために少なくとも1つの一致するpermitステートメント（および一致するforbidがないこと）を持つ必要があります。

完全なリファレンスについては、AgentCore Gatewayポリシーに関するAWSドキュメントを参照してください。一般的なポリシーパターンも含まれています。

ポリシーの追加

ポリシーを追加するには、permit-all.cedarと並んで新しい.cedarファイルを作成します。policies/内の各.cedarファイルは、正確に1つのpermitまたはforbidステートメントを含む必要があり、単一のAWS::BedrockAgentCore::Policyリソースとしてデプロイされます。ポリシーリソースの名前はファイル名から派生します：permit-all.cedarはPermitAllになります（kebab/snake-caseはPascalCaseに変換されます）。複数のステートメントを含むファイルは、デプロイ時にunexpected token 'forbid'エラーを生成します — それらを別々のファイルに分割してください。

例えば、特定のエージェントロールのみが特定のツールを呼び出すことを許可するには、以下を作成します：

permit (
  principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= tsAgentRoleName %>",
  action == AgentCore::Action::"ts-mcp___divide",
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

ロール名をハードコーディングするのではなく、テンプレート変数として渡します（以下のテンプレート変数を参照）。新しいポリシーをデプロイするには、再synthまたは再planを実行します。

テンプレート変数

ポリシーはEJSテンプレートであり、synth/plan時にレンダリングされるため、アカウント間およびGatewayの再デプロイ間で移植可能なままです：

変数	置換される値
`<%= gatewayArn %>`	デプロイされたGatewayのARN
`<%= accountId %>`	このGatewayがデプロイされるAWSアカウント

値をハードコーディングするのではなく、常にこれらの変数を参照してください。

独自の変数の追加

新しい変数を追加するには、ポリシーがレンダリングされる場所で追加します。例えば、上記のts-agent-divide.cedarの例にエージェントの実行ロール名を渡すには：

CDK
Terraform

packages/common/constructs/src/app/gateways/<name>/<name>.tsで、cedarPolicyVariablesを共有コンストラクトに渡します：

super(scope, id, {
  cedarPolicyPath: path.join(
    ...
  ),
  cedarPolicyVariables: {
    tsAgentRoleName: cdk.Token.asString(tsAgent.agentCoreRuntime.role.roleName),
  },
});

packages/common/terraform/src/app/gateways/<name>/<name>.tfで、rendered_policiesデータソースのqueryに追加します：

query = {
  template        = "${local.policies_dir}/${each.value}"
  gatewayArn      = aws_bedrockagentcore_gateway.this.gateway_arn
  tsAgentRoleName = var.ts_agent_role_name
  # ...
}

ENFORCEモードとデフォルト拒否

PolicyEngineはENFORCEモードで実行されます。これはデフォルト拒否セマンティクスが適用されることを意味します：(principal, action, resource)タプルに一致するpermitステートメントがない場合、リクエストは拒否されます。拒否されたツール呼び出しは以下を返します：

Tool Execution Denied: Tool call not allowed due to policy enforcement
[No policy applies to the request (denied by default).]

さらに、Gatewayはtools/listのレスポンスをフィルタリングし、呼び出し元が少なくとも1つの一致するpermitを持つツールのみを表示します：エージェントが特定のツールの権限を持たない場合、ツールは呼び出し時に表示されて失敗するのではなく、完全に非表示になります。

デフォルトの`permit-all.cedar`

ジェネレーターは、Gatewayがデプロイされる先のAWSアカウントからの任意のIAM呼び出し元を許可するデフォルトポリシーを提供します：

permit (
  principal is AgentCore::IamEntity,
  action,
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
) when {
  principal.id like "arn:aws:*::<%= accountId %>:*"
};

さらにロックダウンするには、その横により狭いポリシーを追加します。ポリシーセット内に少なくとも1つの一致するpermitを常に保持してください。そうしないと、デフォルト拒否がすべての呼び出しをブロックします。

ポリシースコープリファレンス

このプラグインによって生成されたGatewayの場合、すべての呼び出し元はIAMプリンシパルです（GatewayはGatewayAuthorizer.usingAwsIam()で構成されています）：

principal is AgentCore::IamEntity

呼び出し元はセッション名が削除されたSTS assumed-role ARNとして評価されるため、ロールを正確に一致させることができます — ワイルドカードは不要です：

principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= myAgentRoleName %>"

同じ値はwhen句のprincipal.idとして利用できます。likeは、デフォルトのpermit-all.cedarのアカウント全体の一致など、真のパターンのために予約してください。

ツール呼び出しは、以下の形式のアクションとしてポリシーエンジンに到達します：

AgentCore::Action::"<target-name>___<tool-name>"

ここで、<target-name>はGatewayターゲット名（gateway.addMcpServer(...)を使用する場合、デフォルトではMCPサーバーのmcpServerNameで、MCPプロジェクトのクラス名からケバブケースで派生 — 例：TsMcp → ts-mcp）、<tool-name>はMCPツールの名前、セパレーターは___（3つのアンダースコア）です。Cedarはアクションのワイルドカードをサポートしていません — 正確なアクションを一致させるか、すべてのアクションを一致させるためにaction ==を省略します。

リソースは常にGateway自体です：

resource == AgentCore::Gateway::"<%= gatewayArn %>"

検証の考慮事項

生成されたインフラストラクチャはIGNORE_ALL_FINDINGSでポリシーを作成します：AgentCoreのCedarアナライザー（サービスのデフォルトであるFAIL_ON_ANY_FINDINGS）は、多くの正当なポリシーを拒否します — たとえば、すべての呼び出し元に対して単一のツールを無効にするforbidは、when句でスコープされている場合でも「Overly Restrictive」として拒否されます。エンフォースメントは影響を受けません。これはポリシーエンジンのENFORCEモードによって構成されます。

1つの順序制約は依然として適用されます：AgentCore::Action::"<target>___<tool>"を参照するポリシーは、ターゲットがそのツールをGatewayに登録した後にのみ検証されます。これが、生成されたインフラストラクチャがGatewayターゲットの後にポリシーを作成する理由です。

ポリシーのデプロイに失敗した場合、CloudFormationは拒否を不透明なResource stabilization failedエラーとして表示します — aws bedrock-agentcore-control list-policies --policy-engine-id <id>を実行して、実際の理由を含むバリデーターのstatusReasonsを取得してください。

例：より広い許可を維持しながら1つのツールを禁止する

狭いforbidをより広いpermitとペアにします（Cedarはforbidをpermitよりも優先して評価します）：

forbid (
  principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= pyAgentRoleName %>",
  action == AgentCore::Action::"ts-mcp___divide",
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

これにより、Pythonエージェントロールがts-mcp___divideを呼び出すことを拒否しながら、他のすべての呼び出し元に対してより広いpermit-all.cedarを残します。

ローカル開発

ジェネレーターは、Gatewayプロジェクトにdevターゲットを追加します。このターゲットはlocal-dev.tsを実行します：デプロイされたGatewayに一致するように、ツールに<target>___<tool>のプレフィックスが付けられた、アタッチされたすべてのMCPサーバー（agentcore-gateway#mcp-connectionジェネレーターを介して接続）を集約する単一のMCPエンドポイントを公開するローカルゲートウェイです。これを実行すると、ローカルゲートウェイとアタッチされたすべてのMCPサーバーが一緒に起動します：

pnpm nx dev <name>

yarn nx dev <name>

npx nx dev <name>

bunx nx dev <name>

完全なローカル開発ストーリーについては、接続ガイドを参照してください。

接続

connectionジェネレータを使用して、このプロジェクトをワークスペース内の他のプロジェクトと統合できます。このプロジェクトに関連する接続は以下の通りです：

AgentCore Gateway to MCP Server AgentCore GatewayでMCPサーバーを集約する

AgentCore Gateway to AgentCore Gateway 別のAgentCore Gatewayの背後にAgentCore Gatewayを集約する

TypeScript Agent to AgentCore Gateway TypeScript AgentをAgentCore Gatewayに接続する

Python Agent to AgentCore Gateway Python AgentをAgentCore Gatewayに接続する

AgentCore Gateway

使用方法