Skip to content
@aws/nx-plugin
Blog

TypeScript Agent から Gateway へ

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

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

前提条件

Section titled “前提条件”

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

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

Gateway は IAM 認証を使用する必要があります — エージェントは自身の実行ロールを使用して SigV4 でリクエストに署名します。ジェネレーターは Cognito 認証のゲートウェイを拒否します。

使用方法

Section titled “使用方法”

ジェネレーターの実行

Section titled “ジェネレーターの実行”
Terminal window
pnpm nx g @aws/nx-plugin:connection
変更されるファイルを確認するためにドライランを実行することもできます
Terminal window
pnpm nx g @aws/nx-plugin:connection --dry-run

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

オプション

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

ジェネレーターの出力

Section titled “ジェネレーターの出力”

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

  • Directorypackages/common/agent-connection
    • Directorysrc
      • Directorycore/
        • agentcore-endpoints.ts Framework-agnostic ARN/URL resolution
        • agentcore-gateway-mcp-transport.ts Framework-agnostic Gateway MCP transport
        • agentcore-gateway-mcp-client-strands.ts Strands MCP client for the deployed Gateway
      • Directoryapp/
        • <gateway-kebab>-client-strands.ts Per-Gateway Strands client wrapper
      • index.ts Re-exports the Gateway client

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

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

接続された Gateway の使用

Section titled “接続された Gateway の使用”

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

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],
  });
};

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

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

インフラストラクチャ

Section titled “インフラストラクチャ”

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

packages/infra/src/stacks/application-stack.ts
const gateway = new MyGateway(this, 'MyGateway');
const myAgent = new MyAgent(this, 'MyAgent');


// Grant the agent permissions to invoke the Gateway
gateway.grantInvokeAccess(myAgent);

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

ローカル開発

Section titled “ローカル開発”

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

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

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

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

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

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

ローカルの忠実性

Section titled “ローカルの忠実性”

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

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