React WebサイトからAgentCore Gatewayへ

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

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

前提条件

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

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

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

使用方法

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

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

ソースとしてWebサイトプロジェクトを、ターゲットとして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はランタイム設定のconnection.gateways.<GatewayClassName>名前空間に登録されるため、Webサイトのruntime-config.jsonに公開されます。

Webサイトユーザーへのアクセス許可

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

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
}

ローカル開発

Webサイトのdevターゲットは、Gatewayプロジェクトのdevターゲットに依存関係を持ち、ローカルゲートウェイと接続されたすべてのエージェントを起動します。Webサイトのランタイム設定は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に接続されているエージェントにWebサイトを接続します。Gatewayに別のエージェントを接続した後、コネクションジェネレーターを再実行してそのWebサイトクライアントを生成してください — 既存のクライアントはそのまま残ります。