Python Agent to Gateway

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

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

前提条件

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

Agentコンポーネント（infra: agentcore）を持つPythonプロジェクト
agentcore-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

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

オプション

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

ジェネレーターの出力

ジェネレーターは、共有のcore-gatewayモジュールをagent_connection Pythonプロジェクトに出力し、さらにGatewayごとのラッパーを追加し、エージェントを変更します：

Directorypackages/common/agent_connection
- Directory<scope>_agent_connection
  - Directorycore/
    agentcore_endpoints.py フレームワークに依存しないARN/URL解決
    agentcore_gateway_mcp_transport.py フレームワークに依存しないGateway MCPトランスポート
    agentcore_gateway_mcp_client_<framework>.py エージェントのフレームワーク用のGateway MCPクライアント
    Directoryauth/ フレームワークに依存しないSigV4 / セッション転送 httpx.Auth
    …
  - Directoryapp/
    <gateway_snake>_client_<framework>.py Gatewayごとのクライアントラッパー
  - __init__.py Gatewayクライアントを再エクスポート

クライアントのサフィックスは、エージェントのフレームワーク（_strandsまたは_langchain）と一致します。

さらに、ジェネレーターは以下を行います：

エージェントのagent.pyを変更して、Gatewayクライアントをインポートし、そのツールをtoolsに登録します
エージェントのワークスペース依存関係としてagent_connectionを追加します
エージェントの<agent>-devターゲットをGatewayのdevターゲットに依存するように配線します

接続されたGatewayの使用

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

Strands
LangChain

from contextlib import contextmanager
from strands import Agent

from my_scope_agent_connection import MyGatewayClientStrands

@contextmanager
def get_agent():
    my_gateway = MyGatewayClientStrands.create()
    with (
        my_gateway,
    ):
        yield Agent(
            system_prompt="...",
            tools=[*my_gateway.list_tools_sync()],
        )

MyGatewayClientStrands.create()は、list_tools_sync()がGatewayを通じて利用可能なすべてのツールを生成する、単一のコンテキスト管理可能なMCPClientを返します。

from langchain.agents import create_agent
from langchain_aws import ChatBedrockConverse

from my_scope_agent_connection import MyGatewayClientLangChain

def get_agent():
    my_gateway = MyGatewayClientLangChain.create()
    return create_agent(
        model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
        system_prompt="...",
        tools=[*my_gateway],
    )

MyGatewayClientLangChain.create()は、langchain-mcp-adaptersを介して読み込まれたツールのリストを返します。各ツールは呼び出しごとに新しいセッションを開くため、withブロックは必要ありません。

どちらの場合も、クライアントはモードごとに同じように動作します：

デプロイモード（LOCAL_DEV未設定）：GatewayのMCPエンドポイントを指すツール、SigV4署名付き。
ローカルモード（LOCAL_DEV=true）：Gatewayプロジェクトのdevターゲットによって起動されたローカルゲートウェイを指すプレーンHTTPツール。

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

インフラストラクチャ

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

CDK
Terraform

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>名前空間に自動的に登録されるため、エージェントは実行時にそれを検出できます。

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

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

# Grant the agent permission to invoke the 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ターゲットを次のように設定します：

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

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

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

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

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

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

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

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

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

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

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

ローカルの忠実性

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

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