Python Agent から MCP へ

connection ジェネレーターは、Python Agent を MCP サーバー（TypeScript または Python）に接続できます。

このジェネレーターは、エージェントが MCP サーバーのツールを検出して呼び出すために必要なすべての配線を設定します。これは AWS にデプロイされた場合（Bedrock AgentCore 経由）とローカルで実行する場合の両方で機能します。

前提条件

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

1. Python Agent コンポーネント（Strands または LangChain）を持つ Python プロジェクト
2. MCP サーバーコンポーネント（ts#mcp-server または py#mcp-server）を持つプロジェクト
3. 両方のコンポーネントが infra: agentcore で作成されていること

使用方法

ジェネレーターの実行

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

VSCode

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

ソースとしてエージェントプロジェクトを選択し、ターゲットとして MCP サーバープロジェクトを選択します。プロジェクトに複数のコンポーネントが含まれている場合は、sourceComponent と targetComponent オプションを指定して明確にしてください。

オプション

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

ジェネレーターの出力

ジェネレーターは、packages/common/agent_connection/ に共有の agent_connection Python プロジェクトを作成します（まだ存在しない場合）。接続ごとのクライアントモジュールは、この共有プロジェクトに生成されます：

• Directorypackages/common/agent_connection

  • Directory<scope>_agent_connection

    • __init__.py 接続ごとのクライアントを再エクスポート
    • Directorycore

      • agentcore_endpoints.py フレームワークに依存しない ARN/URL 解決
      • agentcore_mcp_transport.py フレームワークに依存しない MCP トランスポート
      • agentcore_mcp_client_<framework>.py エージェントのフレームワーク用のトランスポートをラップする MCP クライアント
      • Directoryauth/ フレームワークに依存しない SigV4 / セッション転送 httpx.Auth

        • …
    • Directoryapp

      • <mcp_server_name>_client_<framework>.py 各 MCP サーバー用の接続ごとのクライアント

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

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

• エージェントの agent.py を変換して、クラスベースのクライアント経由で MCP サーバーのツールをインポートして使用する
• エージェントプロジェクトのワークスペース依存関係として agent_connection プロジェクトを追加する
• エージェントの dev ターゲットを更新して、MCP サーバーの serve ターゲットに依存するようにする

接続された MCP サーバーの使用

ジェネレーターは、エージェントの agent.py を変換して MCP サーバーのツールを使用します：

Strands

packages/my-project/my_module/agent/agent.py

from contextlib import contextmanager
from strands import Agent

from my_scope_agent_connection import MyMcpServerClientStrands

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

Strands クライアントはコンテキストマネージャーであり、エージェントを囲む with ブロック内で入力されます。

LangChain

packages/my-project/my_module/agent/agent.py

from langchain.agents import create_agent
from langchain_aws import ChatBedrockConverse

from my_scope_agent_connection import MyMcpServerClientLangChain

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

LangChain クライアントは、langchain-mcp-adapters 経由でロードされたツールのリストを返します。各ツールは呼び出しごとに新しい MCP セッションを開くため、ツールはエージェントの存続期間中使用可能な状態を維持します — with ブロックは不要です。

AgentCore セッション ID は、両方のフレームワークで X-Amzn-Bedrock-AgentCore-Runtime-Session-Id ヘッダーを介して MCP サーバーに自動的に伝播され、Bedrock AgentCore Observability の一貫性を確保します。

インフラストラクチャ

CDK

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

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

const mcpServer = new MyMcpServer(this, 'MyMcpServer');
const myAgent = new MyAgent(this, 'MyAgent');

// Grant the agent permissions to invoke the MCP server
mcpServer.grantInvokeAccess(myAgent);

MCP サーバーの AgentCore ランタイム ARN は、生成された CDK コンストラクトによって Runtime Configuration の agentcore 名前空間に自動的に登録されるため、エージェントは実行時にそれを検出できます。

Terraform

接続ジェネレーターを実行した後、Terraform 設定でエージェントに MCP サーバーを呼び出す権限を付与する必要があります：

packages/infra/src/main.tf

module "inventory_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/inventory-mcp"
}

module "story_agent" {
  source = "../../common/terraform/src/app/agents/story-agent"
}

# Grant the agent permissions to invoke the MCP server
resource "aws_iam_policy" "agent_invoke_mcp" {
  name = "AgentInvokeMcpPolicy"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect   = "Allow"
      Action   = "bedrock-agentcore:InvokeAgent"
      Resource = module.inventory_mcp_server.agent_core_runtime_arn
    }]
  })
}

resource "aws_iam_role_policy_attachment" "agent_invoke_mcp" {
  role       = module.story_agent.agent_core_runtime_role_arn
  policy_arn = aws_iam_policy.agent_invoke_mcp.arn
}

MCP サーバーの AgentCore ランタイム ARN は、生成された Terraform モジュールによって Runtime Configuration の agentcore 名前空間に自動的に登録されるため、エージェントは実行時にそれを検出できます。

ローカル開発

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

1. 接続された MCP サーバーを自動的に起動する
2. LOCAL_DEV=true を設定して、生成されたクライアントが AgentCore の代わりに直接 HTTP トランスポートを使用するようにする

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

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>

これにより、エージェントとすべての接続された MCP サーバーが起動し、エージェントは割り当てられたローカルポートで HTTP 経由で MCP サーバーに直接接続します。