TypeScript Agent to Gateway

connectionジェネレーターは、TypeScript AgentをAgentCore Gatewayに接続できます。

このジェネレーターは、デプロイ時にIAM SigV4でGatewayに認証し、ローカル実行時にはGatewayプロジェクトによって起動されたローカルゲートウェイに接続するようにエージェントを構成します。

前提条件

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

1. Agentコンポーネント（infra: agentcore）を持つTypeScriptプロジェクト
2. agentcore-gatewayプロジェクト

使用方法

ジェネレーターの実行

VSCode

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

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

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

オプション

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

ジェネレーターの出力

ジェネレーターは、共有コアクライアントファイルをagent-connectionパッケージに出力し、Gateway毎のラッパーを追加し、エージェントを変更します：

• Directorypackages/common/agent-connection

  • Directorysrc

    • Directorycore/

      • agentcore-endpoints.ts フレームワークに依存しないARN/URL解決
      • agentcore-gateway-mcp-transport.ts フレームワークに依存しないGateway MCPトランスポート
      • agentcore-gateway-mcp-client-strands.ts デプロイされたGateway用のStrands MCPクライアント
    • Directoryapp/

      • <gateway-kebab>-client-strands.ts Gateway毎のStrandsクライアントラッパー
    • index.ts Gatewayクライアントを再エクスポート

さらに、ジェネレーターは：

• エージェントのagent.tsを変更して、Gatewayクライアントクラスをインポートし、<Gateway>ClientStrands.create()を呼び出し、返されたクライアントをtools配列に登録します
• エージェントの<agent>-devターゲットをGatewayのdevターゲットに依存するように構成します
• 必要なSigV4 / MCP依存関係をインストールします

接続されたGatewayの使用

ジェネレーターは、エージェントのagent.tsをGatewayクライアントを使用するように変換します：

packages/example/src/my-agent/agent.ts

import { Agent } from '@strands-agents/sdk';
import { MyGatewayClientStrands } from ':my-scope/agent-connection';

export const getAgent = async () => {
  const myGateway = await MyGatewayClientStrands.create();
  return new Agent({
    systemPrompt: '...',
    tools: [myGateway],
  });
};

デプロイ時（SERVE_LOCALが未設定）、クライアントはGatewayのMCPエンドポイントを指し、SigV4で認証します。SERVE_LOCAL=trueの場合、それはGatewayプロジェクトのserve-localターゲットによって起動されたローカルゲートウェイを指すため、同じagent.tsが両方のモードで統一的に動作します。

セッションIDはX-Amzn-Bedrock-AgentCore-Runtime-Session-Idヘッダーを介して下流のMCPサーバーに自動的に伝播されます。

インフラストラクチャ

ジェネレーターの実行後、エージェントにGatewayを呼び出す権限を付与する必要があります。

CDK

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

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

// エージェントにGatewayを呼び出す権限を付与
gateway.grantInvokeAccess(myAgent);

Gateway URLは、生成されたCDKコンストラクトによってRuntime Configurationのagentcore.gateways.<ClassName>名前空間に自動的に登録されるため、エージェントは実行時にそれを検出できます。

Terraform

packages/infra/src/main.tf

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

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

# エージェントにGatewayを呼び出す権限を付与
resource "aws_iam_policy" "agent_invoke_gateway" {
  name = "AgentInvokeGatewayPolicy"
  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" "agent_invoke_gateway" {
  role       = module.my_agent.agent_core_runtime_role_arn
  policy_arn = aws_iam_policy.agent_invoke_gateway.arn
}

Gateway URLは、生成されたTerraformモジュールによってRuntime Configurationのagentcore.gateways.<ClassName>名前空間に自動的に登録されるため、エージェントは実行時にそれを検出できます。

ローカル開発

ジェネレーターは、エージェントのdevターゲットを次のように構成します：

1. 接続されたGatewayのローカルゲートウェイとすべての接続されたMCPサーバーを起動
2. LOCAL_DEV=trueを設定して、生成されたクライアントがデプロイされたGatewayの代わりにローカルゲートウェイを指すようにします

エージェントをローカルで実行するには：

pnpm

pnpm nx <agent-name>-dev <project-name>

yarn

yarn nx <agent-name>-dev <project-name>

npm

npx nx <agent-name>-dev <project-name>

bun

bunx nx <agent-name>-dev <project-name>

エージェントをローカルでデプロイされたGatewayに対して実行するには（例えば、Cedarポリシーを実行するため）、エージェントのserveターゲットを使用します。LOCAL_DEVが設定されていない場合、クライアントはランタイム設定からデプロイされたGateway URLを解決し、ローカルのAWS認証情報でリクエストにSigV4署名します：

pnpm

pnpm nx <agent-name>-serve <project-name>

yarn

yarn nx <agent-name>-serve <project-name>

npm

npx nx <agent-name>-serve <project-name>

bun

bunx nx <agent-name>-serve <project-name>

ローカルの忠実性

ローカルゲートウェイはデプロイされたGatewayの代わりとなるため：

• Cedarポリシー評価なし。 ポリシーに関係なく、すべてのツールがエージェントに表示されます。デプロイされたGatewayに対してポリシーを実行するには、serveターゲットを使用してください。
• ツール名のプレフィックスは保持されます。 各ローカルMCPサーバーのツールは、<target-name>___<tool-name>の形式の名前を公開するようにラップされ、デプロイされたGatewayが出力するものと一致します。これにより、エージェントのシステムプロンプトと参照するCedarアクション名がローカル実行とデプロイ実行で一貫性を保ちます。