AgentCore Gateway から Agent へ

connection ジェネレーターは、エージェント（TypeScript または Python）を、protocol: http で生成された AgentCore Gateway の AgentCore Runtime ターゲットとして登録できます。

接続されると、Gateway は <gatewayUrl>/<targetName>/invocations 配下でエージェントへのリクエストをプロキシし、ランタイムへのアウトバウンドトラフィックに IAM SigV4 で署名します。これにより、エージェントに単一の管理されたエントリーポイントが提供されます。また、呼び出し元は Gateway にのみ到達すればよいため、エージェントランタイム自体は Gateway の背後にある VPC 内にデプロイできます。

前提条件

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

1. protocol: http で生成された agentcore-gateway プロジェクト
2. infra: agentcore で作成されたエージェントコンポーネント（ts#agent または py#agent）。auth: iam（Gateway が自身のロールで呼び出す）または auth: cognito（Gateway が呼び出し元の JWT を転送する — 呼び出し元の ID をランタイムに転送するを参照）のいずれかが機能します。

TypeScript HTTP エージェント

TypeScript http エージェントは WebSocket 経由で tRPC を提供しますが、AgentCore Gateway は WebSocket や双方向ストリーミングをサポートしていません。ジェネレーターはこの組み合わせを拒否します。代わりに ag-ui プロトコルでエージェントを生成してください。

使用方法

ジェネレーターの実行

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 プロジェクトを、ターゲットとしてエージェントプロジェクトを選択します。エージェントプロジェクトに複数のコンポーネントが含まれている場合は、targetComponent を指定して明確にします。

オプション

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

ジェネレーターの出力

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

• Directorypackages/<gateway>

  • project.json Gateway の dev ターゲットがエージェントの <agent>-dev への依存関係を取得
  • local-dev.ts ATTACHED_AGENTS が更新され、ローカル gateway がエージェントにプロキシする

スタックへのエージェントターゲットの追加

ジェネレーターは、Gateway をインスタンス化するスタックやモジュールを認識していないため、エージェントターゲットをインフラストラクチャに自動的に接続できません。gateway.addAgent(agent) の呼び出しを自分で追加してください。

CDK

Gateway をインスタンス化するスタックで、エージェントをターゲットとして登録します：

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

const myAgent = new MyAgent(this, 'MyAgent');
const myGateway = new MyGateway(this, 'MyGateway');

// Register the agent as a runtime target of the Gateway. The target name
// defaults to the agent's `agentName` (its class name in kebab-case,
// e.g. `MyAgent` -> `my-agent`), and forms the target's invocation path:
// <gatewayUrl>/my-agent/invocations
myGateway.addAgent(myAgent);

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

myGateway.addAgent(myAgent, { gatewayTargetName: 'my-target' });

コンストラクトは、Gateway の実行ロールにエージェントランタイムへの呼び出しアクセスを付与し、GATEWAY_IAM_ROLE 認証情報プロバイダーでターゲットを構成するため、Gateway は自身のロールでアウトバウンド呼び出しに署名します。

VPC へのエージェントのデプロイ

Gateway でエージェントをフロントすることで、VPC にデプロイされたエージェントが到達可能になります：呼び出し元は Gateway のパブリックエンドポイントと通信し、Gateway は内部的にランタイムに到達します。エージェントコンストラクトに VPC ネットワーク構成を渡します：

import { RuntimeNetworkConfiguration } from 'aws-cdk-lib/aws-bedrockagentcore';

const myAgent = new MyAgent(this, 'MyAgent', {
  // Give each agent its own scope for the network configuration — usingVpc
  // creates a security group named `SecurityGroup` under the scope you pass,
  // so passing `this` for more than one agent collides on the construct id.
  networkConfiguration: RuntimeNetworkConfiguration.usingVpc(
    new Construct(this, 'MyAgentNetwork'),
    {
      vpc,
      vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
    },
  ),
});

プライベート分離サブネットではなく、エグレス付きのプライベートサブネットを使用してください：ランタイムは Bedrock に到達し、AWS AppConfig から構成を読み取るためにアウトバウンドインターネットアクセスが必要です。

AgentCore Runtime の VPC デプロイは、特定のアベイラビリティーゾーンでのみサポートされています。subnets are in unsupported availability zones でデプロイが失敗する場合は、VPC（またはサブネット選択）をリージョンのサポートされているゾーンに制限してください。

Terraform

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

packages/infra/src/main.tf

module "my_agent" {
  source = "../../common/terraform/src/app/agents/my-agent"
  # ...
}

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

  # The Gateway signs outbound calls to the runtime with its own role and
  # validates access at target creation, so it needs invoke access first.
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
        # A2A targets additionally serve their agent card via the gateway
        "bedrock-agentcore:GetAgentCard",
      ]
      Resource = [
        module.my_agent.agent_core_runtime_arn,
        "${module.my_agent.agent_core_runtime_arn}/*",
      ]
    }
  ]
}

# Register the agent as a runtime target of the Gateway. The target name
# forms the invocation path: <gatewayUrl>/my-agent/invocations
resource "aws_bedrockagentcore_gateway_target" "my_agent" {
  gateway_identifier = module.my_gateway.gateway_id
  name               = "my-agent"
  # AgentCore fills in a description when none is set, which the provider
  # reports as an inconsistent result after apply — so always set one.
  description = "Agent runtime target my-agent"

  target_configuration {
    http {
      agentcore_runtime {
        arn = module.my_agent.agent_core_runtime_arn
      }
    }
  }

  credential_provider_configuration {
    gateway_iam_role {}
  }
}

VPC へのエージェントのデプロイ

Gateway でエージェントをフロントすることで、VPC にデプロイされたエージェントが到達可能になります：呼び出し元は Gateway のパブリックエンドポイントと通信し、Gateway は内部的にランタイムに到達します。エージェントモジュールの VPC 変数を設定します：

module "my_agent" {
  source = "../../common/terraform/src/app/agents/my-agent"

  enable_vpc = true
  vpc_id     = aws_vpc.my_vpc.id
  subnet_ids = [aws_subnet.private_a.id, aws_subnet.private_b.id]
}

プライベート分離サブネットではなく、エグレス付きのプライベートサブネット（NAT ゲートウェイへのルート）を使用してください：ランタイムは Bedrock に到達し、AWS AppConfig から構成を読み取るためにアウトバウンドインターネットアクセスが必要です。

Gateway 経由でのエージェントの呼び出し

<gatewayUrl origin>/<targetName>/invocations へのリクエストは、プロトコル変換なしでエージェントランタイムに転送されるため、呼び出し元はランタイムに直接使用するのと同じリクエスト形式を使用します — SSE ストリーム（AG-UI）、JSON ストリーミング（Python HTTP）、A2A JSON-RPC はすべてプロキシされます。呼び出し元は、エージェントではなく Gateway で認証します（Gateway の auth に応じて IAM SigV4 または Cognito JWT）。

Web サイトを Gateway のエージェントに接続するには、connection ジェネレーターを使用します。

呼び出し元の ID をランタイムに転送する

デフォルトでは、Gateway は自身の IAM ロールでアウトバウンド呼び出しに署名するため（GATEWAY_IAM_ROLE 認証情報プロバイダー）、ランタイムは呼び出し元ではなく Gateway の ID を認識します。代わりに、エージェントが呼び出し元で認可するようにしたい場合（たとえば、ユーザーの sub や scope クレームを読み取る場合）、Cognito エージェントを Cognito Gateway でフロントします。Gateway は呼び出し元の JWT を変更せずにランタイムに転送し（JWT_PASSTHROUGH 認証情報プロバイダー）、ランタイムはそれを再検証します。

両端を auth: cognito で生成し、上記のように接続します：

• auth: cognito で作成されたエージェント（ts#agent または py#agent）、および
• 同じ Cognito ユーザープールをフロントする auth: cognito で作成された Gateway。

それ以外はすべて自動です — gateway.addAgent(agent)（CDK）と生成された Terraform ランタイムモジュールは、エージェントの auth に基づいて配線を処理します：

• ターゲットは（GATEWAY_IAM_ROLE ではなく）JWT_PASSTHROUGH 認証情報プロバイダーで作成され、
• ランタイムは Authorization ヘッダーを許可リストに追加するため、転送されたトークンがエージェントコードに到達します。この許可リストがないと、AgentCore はトークンを検証しますが、コンテナの前にヘッダーを削除します。

呼び出し元は Authorization: Bearer <jwt>（SigV4 なし）で Gateway を呼び出し、エージェントは Authorization ヘッダーからクレームを読み取ります — 署名検証をスキップします。ランタイムのインバウンドオーソライザーがすでにトークンを検証しているためです：

packages/py_project/.../my_agent/main.py

import jwt  # PyJWT

@app.post('/invocations')
async def invoke(input: InvokeInput, request: Request):
    token = request.headers['authorization'].removeprefix('Bearer ')
    claims = jwt.decode(token, options={'verify_signature': False})
    # authorize on claims['sub'], claims['scope'], ...

Note

JWT パススルーは、トークンオーディエンスがすでにランタイムをカバーしている単一の ID プロバイダーに適しています。1 つの Gateway が複数のテナントまたはオーディエンスにわたってエージェントをフロントする場合は、代わりに OAuth on-behalf-of トークン交換を使用してください。

ローカル開発

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

pnpm

pnpm nx dev <gateway-name>

yarn

yarn nx dev <gateway-name>

npm

npx nx dev <gateway-name>

bun

bunx nx dev <gateway-name>

ローカル gateway と、割り当てられたローカルポート上のすべての接続されたエージェントを起動します。ローカル gateway は /<targetName>/... パスを各エージェントのローカルサーバーにプロキシし、デプロイされた Gateway のパスベースルーティングと一致します。