AgentCore Gateway

Amazon Bedrock AgentCore Gatewayプロジェクトを生成します。AgentCore Gatewayは、MCPサーバーまたはエージェントの前に配置されるマネージドエントリーポイントで、インバウンドリクエストを認証し（IAMまたはCognito）、ターゲットへのアウトバウンドトラフィックにIAM SigV4で署名します。

protocolオプションは、Gatewayが何をフロントするかを選択します：

• mcp（デフォルト）— 1つ以上のMCPサーバーターゲットを単一のMCPエンドポイントの背後に集約し、すべてのツール呼び出しをCedarポリシーエンジンに対して評価します。
• http — リクエストをAgentCore Runtimeターゲット（あなたのエージェント）にパスベースのルーティング（/<targetName>/invocations）を介して直接プロキシし、集約やプロトコル変換は行いません。これを使用して、単一のガバナンスされたエンドポイントでエージェントをフロントします — たとえば、ウェブサイトがGatewayを通じてVPC内にデプロイされたエージェントに到達できるようにします。

使用方法

AgentCore Gatewayを生成する

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

VSCode

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

オプション

パラメータ	型	デフォルト	説明
name 必須	string	-	AgentCore Gateway プロジェクトの名前
directory	string	packages	ゲートウェイプロジェクトが配置される親ディレクトリ。
subDirectory	string	-	プロジェクトが配置されるサブディレクトリ。デフォルトではプロジェクト名になります。
protocol	mcp | http	mcp	ゲートウェイが公開する受信プロトコル。mcp ゲートウェイは複数の MCP サーバーターゲットを単一の MCP エンドポイントに集約します。http ゲートウェイはパスベースのルーティングを介してエージェントランタイムターゲットへのリクエストをプロキシするため、呼び出し元（例：ウェブサイト）はゲートウェイを通じてエージェントに到達できます。
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ポリシーソースファイル（mcpプロトコルのみ；cedarPolicy: falseの場合は省略）

    • permit-all.cedar 認証された呼び出し元を許可するデフォルトのCedarポリシー
    • README.md Cedarポリシーを書くためのリファレンス
  • local-dev.ts ローカル開発用のローカルゲートウェイ — 接続されたMCPサーバー（mcp）を集約するか、接続されたエージェント（http）をプロキシします
  • project.json serveおよびdevターゲットを追加します

インフラストラクチャ

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

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

共通のインフラストラクチャコードプロジェクトは、次のように構成されています：

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/ 共有ゲートウェイコンストラクト（レディネスプローブ、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認証（認証を参照）を持つAgentCore::Gateway。mcpゲートウェイはMCPプロトコル用に構成されます；httpゲートウェイにはプロトコルタイプがなく、これはAgentCoreがランタイムターゲットに必要とするものです
• ENFORCEモードで実行され、Gatewayに接続されたAgentCore::PolicyEngine（mcpゲートウェイのみ；cedarPolicy: falseの場合は省略）
• policies/内の.cedarファイルごとに1つのAgentCore::Policy（mcpゲートウェイのみ）
• Gatewayに関連付けられたAWS WAFv2 Web ACL、CloudWatchへのリクエストログ記録付き（デフォルトで有効 — AWS WAFを参照）

Gateway URLは、Runtime Configurationのagentcore.gateways.<ClassName>名前空間に自動的に登録され、エージェントが実行時にそれを検出できるようになります。

アーキテクチャ

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

認証

authオプションは、Gatewayがインバウンドリクエストをどのように認証するかを設定します。iam（デフォルト）とcognitoから選択します。

IAM

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

Cognito

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

生成されたインフラストラクチャは既存のCognitoユーザープールとクライアントを使用します — それらを作成しません。ts#website#auth generatorを使用して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,
    });
  }
}

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と許可されたクライアントをプロバイダーのものに交換します。Agent to Gateway connection generatorsはIAM認証されたゲートウェイのみをサポートします。エージェントがSigV4で呼び出しに署名するためです。

ポリシーの記述

cedarPolicy = true

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

完全なリファレンスについては、AWS documentation on AgentCore Gateway policiesを参照してください。common policy patternsも含まれています。

ポリシーの追加

ポリシーを追加するには、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プロジェクトのクラス名からkebab-caseで派生します — 例：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を取得します。

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

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

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を実行します。これを実行すると、ローカルゲートウェイとすべての接続されたターゲットが一緒に起動します：

pnpm

pnpm nx dev <name>

yarn

yarn nx dev <name>

npm

npx nx dev <name>

bun

bunx nx dev <name>

protocol = mcp

ローカルゲートウェイは、接続されたすべてのMCPサーバー（agentcore-gateway#mcp-connection generatorを介して接続）を集約する単一のMCPエンドポイントを公開し、ツールには<target>___<tool>のプレフィックスが付けられ、デプロイされたGatewayと一致します。

protocol = http

ローカルゲートウェイは、/<targetName>/...パスを各接続されたエージェントのローカルサーバー（agentcore-gateway#agent-connection generatorを介して接続）にプロキシし、デプロイされたGatewayのパスベースのルーティングと一致します。

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

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インフラストラクチャがセットアップされます。gateway.addMcpServer(...)でMCPサーバーターゲットを登録します — MCP server connection guideを参照してください。

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インフラストラクチャがセットアップされます。aws_bedrockagentcore_gateway_targetリソースでMCPサーバーターゲットを登録します — MCP server connection guideを参照してください。

AWS WAF

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

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

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

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

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

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に接続する

AgentCore Gateway to AgentランタイムターゲットとしてAgentCore Gatewayでエージェントをフロントする

React Website to AgentCore GatewayAgentCore Gatewayを通じてReactウェブサイトをエージェントに接続する