Python Agent から Gateway への接続

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

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

前提条件

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

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

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

使用方法

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

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

オプション

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

ジェネレーターの出力

ジェネレーターは、agent_connection Python プロジェクトに共有コアゲートウェイモジュールと Gateway ごとのラッパーを生成し、エージェントを変更します：

Directorypackages/common/agent_connection
- Directory<scope>_agent_connection
  - Directorycore/
    agentcore_endpoints.py Framework-agnostic ARN/URL resolution
    agentcore_gateway_mcp_transport.py Framework-agnostic Gateway MCP transport
    agentcore_gateway_mcp_client_<framework>.py Gateway MCP client for your agent’s framework
    Directoryauth/ Framework-agnostic SigV4 / session-forwarding httpx.Auth
    …
  - Directoryapp/
    <gateway_snake>_client_<framework>.py Per-Gateway client wrapper
  - __init__.py Re-exports the Gateway client

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

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

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

接続された Gateway の使用

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

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 コンストラクトによってランタイム設定の 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
  additional_iam_policy_statements = [{
    Effect   = "Allow"
    Action   = ["bedrock-agentcore:InvokeGateway"]
    Resource = [module.my_gateway.gateway_arn]
  }]
}

Gateway URL は、生成された Terraform モジュールによってランタイム設定の 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 アクション名が、ローカル実行とデプロイ実行の間で一貫性を保ちます。