Python Agent から Gateway への接続

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

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

前提条件

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

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

Gateway は mcp プロトコルを提供する必要があります — エージェントは MCP クライアントとして Gateway に到達するため、そのターゲットはツールとして公開されます。Gateway は IAM 認証も使用する必要があります：エージェントは自身の実行ロールを使用して SigV4 でリクエストに署名します。ジェネレーターは Cognito 認証のゲートウェイを拒否します。

使用方法

ジェネレーターの実行

このジェネレーターを実行@aws/nx-plugin:connection

CLI
VSCode

$ 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

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

コマンドを組み立てる5

sourceProject必須

targetProject必須

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-run変更されるファイルを確認するためにドライランを実行することもできます

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

オプション

ジェネレーターオプション5 オプション

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

ジェネレーターの出力

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

Directorypackages/common/agent_connection
- Directory<scope>_agent_connection
  - Directorycore/
    __init__.py Python package initialization
    agentcore_endpoints.py Framework-agnostic ARN/URL resolution
    agentcore_transport.py Shared AgentCore transport plumbing
    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/
    __init__.py Python package initialization
    <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 アクション名が、ローカル実行とデプロイ実行の間で一貫性を保ちます。