AgentCore Gateway から AgentCore Gateway へ

connection ジェネレーターは、AgentCore Gateway を別の AgentCore Gateway のターゲットとして登録できます。これにより、ゲートウェイを階層的に構成できます。たとえば、チームレベルのゲートウェイが複数のドメインゲートウェイを集約し、各ドメインゲートウェイが独自の MCP サーバーをフロントするような構成が可能です。

接続されると、ソース Gateway はターゲット Gateway のツールを単一の MCP エンドポイントに集約します。ターゲット Gateway は既に独自のターゲット名でツールにプレフィックスを付けているため、ソース Gateway を通じてツールは <gateway-target-name>___<target-name>___<tool-name> として表示されます。チェーン内の各ゲートウェイが 1 つのプレフィックスを追加します。両方のゲートウェイは独自の Cedar ポリシーを評価します。ソース Gateway は呼び出し元に対してプレフィックス付きアクションを認可し、次にターゲット Gateway は内部アクションに対してソース Gateway の実行ロールを認可します。

前提条件

このジェネレーターを使用する前に、以下を確認してください：

1. 2 つの agentcore-gateway プロジェクト

両方のゲートウェイは protocol: mcp を持つ必要があり、ターゲットゲートウェイは auth: iam を持つ必要があります。ソースゲートウェイは独自の実行ロールで署名してターゲットを呼び出すため、ターゲットのインバウンド認証のみが IAM である必要があります。ジェネレーターはこれを検証し、ゲートウェイ間でサイクルを作成する接続も拒否します。サイクルがあると tools/list で無限に再帰してしまいます。

使用方法

ジェネレーターの実行

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

VSCode

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

集約する Gateway プロジェクトをソースとして選択し、集約される Gateway をターゲットとして選択します。

オプション

パラメータ	型	デフォルト	説明
sourceProject 必須	string	-	ソース プロジェクト
targetProject 必須	string	-	接続先のターゲット プロジェクト
sourceComponent	string	-	接続元のソース コンポーネント (コンポーネント名、ソース プロジェクト ルートからの相対パス、またはジェネレーター ID)。プロジェクトをソースとして明示的に選択するには '.' を使用します。
targetComponent	string	-	接続先のターゲット コンポーネント (コンポーネント名、ターゲット プロジェクト ルートからの相対パス、またはジェネレーター ID)。プロジェクトをターゲットとして明示的に選択するには '.' を使用します。
preferInstallDependencies	boolean	true	ジェネレーター実行後に依存関係のインストールを優先するかどうか。複数のジェネレーターをバッチ処理する際にインストールを延期する場合はfalseに設定します（後続のジェネレーターがNxプロジェクトグラフを計算できるよう、必要に応じてインストールは実行されます）。最後に一度だけインストールします。

ジェネレーターの出力

ジェネレーターは新しいソースファイルを生成するのではなく、既存のプロジェクトを接続します。以下のファイルが変更されます：

• Directorypackages/<source-gateway>

  • project.json ソース Gateway の dev ターゲットがターゲットゲートウェイの dev ターゲットへの依存関係を取得
  • local-dev.ts ATTACHED_MCP_SERVERS が更新され、ローカルゲートウェイがターゲットゲートウェイを集約

ソース Gateway プロジェクトの dev ターゲットはターゲット Gateway の dev ターゲットへの依存関係を取得するため、ソース Gateway をローカルで実行すると、ターゲットゲートウェイ（およびそれに接続されているすべての MCP サーバー）も起動します。ターゲットゲートウェイはソース Gateway プロジェクトの local-dev.ts にも登録され、ローカルゲートウェイがそのツールを集約します。

スタックへのゲートウェイターゲットの追加

ジェネレーターは、どのスタックまたはモジュールが Gateways をインスタンス化するかを知らないため、ゲートウェイターゲットをインフラストラクチャに自動的に接続できません。gateway.addGateway(targetGateway) の呼び出しを 1 回、自分で追加してください。

CDK

Gateways をインスタンス化するスタックで、ターゲットゲートウェイをソースゲートウェイのターゲットとして登録します：

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

const innerGateway = new InnerGateway(this, 'InnerGateway');
const outerGateway = new OuterGateway(this, 'OuterGateway');

// Register the inner gateway as a target of the outer gateway. The target
// name defaults to the inner gateway's `gatewayName` (its class name in
// kebab-case, e.g. `InnerGateway` -> `inner-gateway`).
outerGateway.addGateway(innerGateway);

Gateway ターゲット名（デフォルトではターゲットゲートウェイの gatewayName）は、ソースゲートウェイの Cedar アクション名にプレフィックスを付けます。アクション形式は AgentCore::Action::"<gatewayTargetName>___<targetName>___<toolName>" です。ポリシーの記述セクションを参照してください。ターゲット名は短く安定したものにしてください。後で変更すると、古い名前を参照する Cedar ポリシーが無効になります。

デフォルトのターゲット名を上書きするには、gatewayTargetName を渡します：

outerGateway.addGateway(innerGateway, { gatewayTargetName: 'inner' });

コンストラクトは、ソースゲートウェイの実行ロールにターゲットゲートウェイへの bedrock-agentcore:InvokeGateway アクセスを付与し、ソースゲートウェイが独自の実行ロールを使用してアウトバウンド呼び出しに署名できるように、ターゲットを iamCredentialProvider.service = 'bedrock-agentcore' で構成します。ターゲットは、ターゲットゲートウェイとそのすべてのターゲットの後に作成されます。これは、AgentCore が作成時にターゲットのツールを取得するためです。

Terraform

Gateways をインスタンス化する Terraform ファイルで、ゲートウェイターゲットを接続します：

packages/infra/src/main.tf

module "inner_gateway" {
  source = "../../common/terraform/src/app/gateways/inner-gateway"

  # Target ids of the inner gateway's own targets (e.g. its MCP servers), so
  # its gateway_url is not consumed until it serves their tools.
  tool_dependencies = [aws_bedrockagentcore_gateway_target.my_mcp_server.target_id]
}

module "outer_gateway" {
  source              = "../../common/terraform/src/app/gateways/outer-gateway"
  policy_dependencies = [aws_bedrockagentcore_gateway_target.inner_gateway.target_id]

  additional_iam_policy_statements = [
    {
      Effect   = "Allow"
      Action   = ["bedrock-agentcore:InvokeGateway"]
      Resource = [module.inner_gateway.gateway_arn]
    }
  ]
}

# Register the inner gateway as a target of the outer gateway
resource "aws_bedrockagentcore_gateway_target" "inner_gateway" {
  gateway_identifier = module.outer_gateway.gateway_id
  name               = "inner-gateway"

  target_configuration {
    mcp {
      mcp_server {
        endpoint = module.inner_gateway.gateway_url
      }
    }
  }

  credential_provider_configuration {
    gateway_iam_role {
      service = "bedrock-agentcore"
    }
  }
}

ターゲット name（上記の inner-gateway）は、外部ゲートウェイの Cedar アクション名にプレフィックスを付けます。ポリシーの記述セクションを参照してください。additional_iam_policy_statements エントリは、外部ゲートウェイの実行ロールに内部ゲートウェイへの呼び出しアクセスを付与します。これは、ターゲット作成時に内部ゲートウェイのツールを取得する場合と、実行時に呼び出しをルーティングする場合の両方で必要です。policy_dependencies は、このターゲットのアクションを参照する Cedar ポリシーが、ターゲットがそれらを登録した後に作成されることを保証します。

ターゲットの順序

AgentCore は aws_bedrockagentcore_gateway_target が作成されるときに内部ゲートウェイのツールを取得するため、内部ゲートウェイは既にそれらを提供している必要があります。内部ゲートウェイの tool_dependencies を独自のターゲットの ID に設定します。その gateway_url は、それらのツールが提供されるまで tools/list をポーリングする準備プローブを通過するため、外部ゲートウェイのターゲットは内部ゲートウェイの準備が整うまで待機します。

チェーンされたゲートウェイ間の Cedar ポリシー

チェーン内の各ゲートウェイは独自のポリシーセットを評価します：

1. ソースゲートウェイは、元の呼び出し元（エージェントの実行ロールなど）をプレフィックス付きアクション（例：AgentCore::Action::"inner-gateway___my-mcp___add"）に対して評価します。
2. ターゲットゲートウェイは、ソースゲートウェイの実行ロールを内部アクション（例：AgentCore::Action::"my-mcp___add"）に対して評価します。

これは、ゲートウェイチェーンを通じたツール呼び出しが、すべてのホップで許可される必要があることを意味します。デフォルトの permit-all.cedar は同じ AWS アカウント内の任意の呼び出し元を許可し、これにはソースゲートウェイのロールが含まれます。ターゲットゲートウェイでより狭いポリシーを記述する場合は、それが見るプリンシパルは元の呼び出し元ではなく、ソースゲートウェイのロールであることを忘れないでください。

ローカル開発

ソース Gateway をローカルで実行するには：

pnpm

pnpm nx dev <source-gateway-name>

yarn

yarn nx dev <source-gateway-name>

npm

npx nx dev <source-gateway-name>

bun

bunx nx dev <source-gateway-name>

ローカルソースゲートウェイ、ローカルターゲットゲートウェイ、およびいずれかに接続されているすべての MCP サーバーが、それぞれ割り当てられたローカルポートで起動します。ツール名は、デプロイされた場合とまったく同じように各ホップでプレフィックスが付けられます（<gateway-target-name>___<target-name>___<tool-name>）。そのため、エージェントのプロンプトと Cedar アクション名は、ローカル実行とデプロイ実行の間で一貫性が保たれます。

ローカルの忠実性

ローカル開発ではローカルスタンドインゲートウェイを使用します。これは、各 Gateway プロジェクトによって起動される軽量な MCP アグリゲーターであり、AgentCore Gateway サービスではありません。その結果、Cedar ポリシーはどちらのホップでもローカルで評価されません。Cedar ポリシーを実行するには、代わりにエージェントの serve ターゲットを実行してください（TypeScript / Python エージェント接続ガイドを参照）。これにより、ローカルで実行されているエージェントがデプロイされた Gateway を呼び出します。