AgentCore Gateway

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

使用方法

AgentCore Gatewayの生成

VSCode

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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 | cognito	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 認証された呼び出し元を許可するデフォルトのCedarポリシー（同じAWSアカウントからのIAM呼び出し元、または任意のCognitoユーザー — 認証を参照）
    • README.md Cedarポリシーの記述に関するリファレンス
  • local-dev.ts ローカル開発用にアタッチされたMCPサーバーを集約するローカルゲートウェイ
  • project.json serveおよびdevターゲットを追加

インフラストラクチャ

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

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

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

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ プロジェクト/ジェネレータ固有のインフラストラクチャ用コンストラクト

      • …
    • Directorycore/ app 内のコンストラクトで再利用される汎用コンストラクト

      • …
    • index.ts app からコンストラクトをエクスポートするエントリーポイント
  • project.json プロジェクトのビルドターゲットと設定

生成されたプロジェクト

このプロジェクトは ts#project ジェネレータを使用して生成されているため、同じビルドターゲットを設定します。

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ プロジェクト/ジェネレータ固有のインフラストラクチャ用Terraformモジュール

      • …
    • Directorycore/ app 内のモジュールで再利用される汎用モジュール

      • …
  • project.json プロジェクトのビルドターゲットと設定

生成されたプロジェクト

このプロジェクトは terraform#project ジェネレータを使用して生成されているため、同じビルドターゲットを設定します。

CDK

• Directorypackages/common/constructs/src

  • Directorycore

    • Directoryagentcore-gateway/ 共有ゲートウェイコンストラクト（readinessプローブ、Cedarポリシーロード）

      • …
  • Directoryapp

    • Directorygateways

      • Directory<name>/

        • <name>.ts GatewayをデプロイするためのCDKコンストラクト

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directorygateways

      • Directory<name>/

        • <name>.tf GatewayをデプロイするためのTerraformモジュール

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

• インバウンドIAM認証（デフォルト）またはCognito JWT認証（認証を参照）を使用してMCPプロトコル用に構成されたAgentCore::Gateway
• ENFORCEモードで実行され、GatewayにアタッチされたAgentCore::PolicyEngine（cedarPolicy: falseの場合は省略）
• policies/内の.cedarファイルごとに1つのAgentCore::Policy
• Gatewayに関連付けられたAWS WAFv2 Web ACLで、CloudWatchへのリクエストログ記録が有効（デフォルトで有効 — AWS WAFを参照）

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

アーキテクチャ

デプロイされたGatewayは以下のアーキテクチャを持ち、Gatewayの前にAWS WAFv2 Web ACLがあり、下流のMCPサーバーターゲットにルーティングします：

認証

authオプションは、Gatewayがインバウンドリクエストを認証する方法を設定します。IAM（デフォルト）とCognitoから選択します。

IAM

デフォルトでは、GatewayはGatewayAuthorizer.usingAwsIam()で構成されています。呼び出し元はSigV4でリクエストに署名し、呼び出し元のIAMアイデンティティはAgentCore::IamEntityプリンシパルとしてCedarポリシーで利用できます。これは、呼び出し元がAWSで実行されているエージェントまたはサービスである場合に推奨されるオプションです — 例えば、エージェントからGatewayへの接続ジェネレーターを介して接続されたエージェントは、独自の実行ロールで呼び出しに署名します。

Cognito

cognitoを選択すると、GatewayはCognitoユーザープールを指すカスタムJWTオーソライザーで構成されます。呼び出し元はJWTベアラートークンを提示して認証し、トークンのsubクレームはAgentCore::OAuthUserプリンシパルとしてCedarポリシーで利用できます。呼び出し元がCognitoを介して認証する場合に使用します — 例えば、ウェブサイトやts#dcr-proxyジェネレーターを介して接続するコーディングエージェントなどです。

生成されたインフラストラクチャは、既存のCognitoユーザープールとクライアントを使用します — それらを作成しません。ts#website#authジェネレーターを使用してUserIdentityを生成するか、独自のものを提供できます。

CDK

生成されたコンストラクトには、ユーザープールとクライアントを提供するidentityプロパティが必要です：

packages/infra/src/stacks/application-stack.ts

import { MyGateway, UserIdentity } from ':my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const identity = new UserIdentity(this, 'Identity');

    new MyGateway(this, 'MyGateway', {
      identity: {
        userPool: identity.userPool,
        userPoolClient: identity.userPoolClient,
      },
    });
  }
}

Terraform

生成されたモジュールには、user_pool_idおよびuser_pool_client_ids変数が必要です：

packages/infra/src/main.tf

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "my_gateway" {
  source               = "../../common/terraform/src/app/gateways/my-gateway"
  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

カスタムOIDCプロバイダー

Cognito以外のOIDCプロバイダーで認証するには、生成されたGatewayコンストラクトまたはTerraformモジュールを直接変更します — オーソライザーのディスカバリーURLと許可されたクライアントをプロバイダーのものに交換します。エージェントからGatewayへの接続ジェネレーターは、エージェントがSigV4で呼び出しに署名するため、IAM認証されたゲートウェイのみをサポートします。

ポリシーの記述

cedarPolicy = true

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'エラーを生成します — それらを別々のファイルに分割してください。

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

packages/<name>/policies/ts-agent-divide.cedar

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

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),
  },
});

Terraform

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の認証タイプに応じたデフォルトポリシーを提供します。

IAM Gatewayの場合、Gatewayがデプロイされる先のAWSアカウントからの任意のIAM呼び出し元を許可します：

packages/<name>/policies/permit-all.cedar

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

Cognito Gatewayの場合、認証された任意のOAuthユーザーを許可します（JWTオーソライザーは、ポリシーが評価される前にトークンのユーザープールとクライアントを既に検証しています）：

packages/<name>/policies/permit-all.cedar

permit (
  principal is AgentCore::OAuthUser,
  action,
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

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

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

プリンシパルタイプは、Gatewayが呼び出し元を認証する方法によって異なります（認証を参照）。

IAM Gatewayの場合、呼び出し元はIAMプリンシパルです：

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のアカウント全体の一致など、真のパターンのために予約してください。

Cognito Gatewayの場合、呼び出し元はJWTトークンのsubクレームから構築されたOAuthユーザーであり、JWTクレーム（ユーザー名、スコープなど）はプリンシパルタグとして利用できます：

principal is AgentCore::OAuthUser

when句で個々のクレームを一致させます — 例えば、スコープを要求するには：

permit (
  principal is AgentCore::OAuthUser,
  action,
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
) when {
  principal.scope == "gateway/invoke"
};

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

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よりも優先して評価します）：

packages/<name>/policies/forbid-divide-for-py-agent.cedar

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

pnpm nx dev <name>

yarn

yarn nx dev <name>

npm

npx nx dev <name>

bun

bunx nx dev <name>

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

AgentCore Gatewayのデプロイ

AgentCore Gatewayジェネレーターは、選択したiacに基づいてCDKまたはTerraformのインフラストラクチャコードを作成します。これを使用してGatewayをデプロイできます。

CDK

GatewayをデプロイするためのCDKコンストラクトは、common/constructsフォルダーにあります。これをCDKアプリケーションで使用できます。例えば：

packages/infra/src/stacks/application-stack.ts

import { MyGateway } from '@my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    new MyGateway(this, 'MyGateway');
  }
}

これにより、AgentCore::Gateway、そのCedar PolicyEngine、およびAWS WAF Web ACL（以下のAWS WAFを参照）を含むGatewayインフラストラクチャがセットアップされます。MCPサーバーターゲットをgateway.addMcpServer(...)で登録します — MCPサーバー接続ガイドを参照してください。

Terraform

GatewayをデプロイするためのTerraformモジュールは、common/terraformフォルダーにあります。これをTerraform設定で使用できます。例えば：

packages/infra/src/main.tf

module "my_gateway" {
  source = "../../common/terraform/src/app/gateways/my-gateway"
}

これにより、aws_bedrockagentcore_gateway、そのCedarポリシーエンジン、およびAWS WAF Web ACL（以下のAWS WAFを参照）を含むGatewayインフラストラクチャがセットアップされます。MCPサーバーターゲットをaws_bedrockagentcore_gateway_targetリソースで登録します — MCPサーバー接続ガイドを参照してください。

AWS WAF

デフォルトでは、生成されたコンストラクトはAWS WAFv2 Web ACLをGatewayに関連付けます。AWS WAFは、ターゲットに到達する_前_にすべてのインバウンドリクエストをインラインで検査し、Webエクスプロイト、ボットトラフィック、ボリューメトリック攻撃からGatewayを保護します。Web ACLは、AWSマネージドデフォルトルールセット（AWSManagedRulesCommonRuleSetおよびAWSManagedRulesKnownBadInputsRuleSet）を使用し、OWASP Top 10を含む一般的なWebエクスプロイトに対する保護を提供します。WAFリクエストログはCloudWatch Logsグループに書き込まれます。

Web ACLはREGIONALであり、AgentCore Gatewayの関連付けに必要なGatewayのリージョンに作成されます。

デフォルトからのSizeRestrictions_BODYの逸脱

AWSManagedRulesCommonRuleSetのSizeRestrictions_BODYルールは、BlockではなくCountにオーバーライドされます。これは、ルールの8 KB制限が典型的なMCPツールペイロードには制限が厳しすぎるためです。オーバーサイズのリクエストは引き続きメトリクスとして記録されるため、監視できます。詳細については、AWS WAFボディサイズ制限ガイドを参照してください。

生成されたGatewayコンストラクトを編集して、ルールを追加、削除、または調整できます（例えば、レートベースルールや追加のマネージドルールグループを追加するなど）。

CDK

オプトアウトするには（例えば、独自のWeb ACLをアタッチする場合）、Gatewayコンストラクトをインスタンス化する際にenableWafをfalseに設定します：

new MyGateway(this, 'MyGateway', {
  enableWaf: false,
});

コンストラクトは、さらなる設定のために作成されたWeb ACLをwebAclとして公開します。

Terraform

オプトアウトするには（例えば、独自のWeb ACLをアタッチする場合）、Gatewayモジュールでenable_wafをfalseに設定します：

module "my_gateway" {
  enable_waf = false
}

モジュールは、さらなる設定のために作成されたWeb ACL ARNをwaf_web_acl_arnとして出力します。

接続

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

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

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

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

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