React WebsiteからAgentCore Gatewayへ

connectionジェネレーターは、React websiteを、protocol: httpで生成されたAgentCore Gatewayによってフロントされるエージェントに接続できます。

ブラウザはGatewayとのみ通信します — <gatewayUrl>/<targetName>/invocationsへのリクエストは、その背後にあるエージェントランタイムにプロキシされます。WebsiteがランタイムへのアクセスをWebsiteが直接必要としないため、エージェントはVPC内にデプロイでき、Gatewayが認証と可観測性を提供する単一の管理されたエントリーポイントとなります。

前提条件

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

React websiteプロジェクト
protocol: httpで生成されたagentcore-gatewayプロジェクト
GatewayからエージェントへのConnectionジェネレーターを介してGatewayに接続された少なくとも1つのAG-UIまたはHTTPエージェント

ジェネレーターは、Gatewayに接続された各AG-UIまたはHTTPエージェントに対してWebsiteクライアントを作成します（A2Aターゲットはスキップされます — これらはブラウザプロトコルではなく、エージェント間JSON-RPCを使用します）。Websiteを各エージェントに直接接続する場合と同じクライアント（AG-UIエージェントにはAG-UI/CopilotKit、Python HTTPエージェントにはOpenAPIクライアント）を生成しますが、ランタイムではなくGatewayを経由してルーティングされます。

使用方法

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

bunx nx g @aws/nx-plugin:connection

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

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

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

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

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

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

ソースとしてWebsiteプロジェクトを、ターゲットとしてGatewayプロジェクトを選択します。

オプション

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

ジェネレーターの出力

フロントされた各AG-UIエージェントに対して、ReactからAG-UIエージェントへの接続と同じファイル（AguiProvider、useAgui<Agent>フック、テーマ付きCopilotKitコンポーネントモジュール）が生成され、フックはランタイム設定からGatewayのURLを読み取ります：

Directorypackages/<website>/src
- Directorycomponents
  - AguiProvider.tsx 各エージェントを登録するCopilotKitプロバイダー
  - Directorycopilot/ テーマ付きチャットコンポーネント
    …
- Directoryhooks
  - useAgui<Agent>.tsx Gatewayの/<targetName>/invocationsルートを介してエージェントに接続

フロントされた各Python HTTPエージェントに対して、ReactからPythonエージェントへの接続と同じファイル（型安全なOpenAPIクライアント、フック、プロバイダー）が生成され、クライアントのベースURLはGatewayを経由してルーティングされます。

GatewayのURLはRuntime Configurationのconnection.gateways.<GatewayClassName>名前空間に登録されるため、Websiteのruntime-config.jsonに公開されます。

Websiteユーザーへのアクセス許可

IAM Gatewayの場合、Websiteの認証済みユーザーに呼び出し権限を付与します（Cognito Gatewayでは付与は不要です — ブラウザは代わりにJWT bearerトークンで認証します）：

CDK
Terraform

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

const myGateway = new MyGateway(this, 'MyGateway');
myGateway.addAgent(myAgent);
myGateway.grantInvokeAccess(identity.identityPool.authenticatedRole);

resource "aws_iam_policy" "gateway_invoke_policy" {
  name = "GatewayInvokePolicy"

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect   = "Allow"
        Action   = ["bedrock-agentcore:InvokeGateway"]
        Resource = [module.my_gateway.gateway_arn]
      }
    ]
  })
}

resource "aws_iam_role_policy_attachment" "authenticated_gateway_access" {
  role       = module.user_identity.authenticated_role_name
  policy_arn = aws_iam_policy.gateway_invoke_policy.arn
}

ローカル開発

WebsiteのdevターゲットはGatewayプロジェクトのdevターゲットに依存関係を持ち、ローカルゲートウェイと接続されたすべてのエージェントを起動します。Websiteのランタイム設定はlocal-devモードでオーバーライドされ、GatewayのURLがローカルゲートウェイを指すようになるため、ブラウザはローカルで同じ/<targetName>/invocationsルートを実行します：

pnpm nx dev <website-name>

yarn nx dev <website-name>

npx nx dev <website-name>

bunx nx dev <website-name>

新しいエージェントの接続

ジェネレーターは、実行時にGatewayに接続されているエージェントにWebsiteを接続します。Gatewayに別のエージェントを接続した後、Connectionジェネレーターを再実行してそのWebsiteクライアントを生成します — 既存のクライアントはそのまま残ります。