Python Agent から A2A Agent への接続

connection ジェネレーターは、Python Agent をリモートの A2A エージェント（TypeScript または Python）に接続し、エージェントが別のエージェントをツールとして委譲できるようにします。

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

前提条件

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

Python Agent コンポーネント（Strands または LangChain）を含む Python プロジェクト
--protocol=a2a および --auth=iam で生成された Agent コンポーネントを含むプロジェクト（ts#agent または py#agent）
両方のコンポーネントが infra: agentcore で作成されていること

使用方法

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

ソースとしてホストエージェントプロジェクトを選択し、ターゲットとして A2A エージェントプロジェクトを選択します。プロジェクトに複数のコンポーネントが含まれている場合は、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_a2a_client_config.py フレームワークに依存しない A2A クライアント設定（署名済み ClientConfig）
    agentcore_a2a_client_<framework>.py エージェントのフレームワーク用の設定をラップする A2A クライアント
    Directoryauth/ フレームワークに依存しない SigV4 / セッション転送 httpx.Auth
    …
  - Directoryapp
    <target_agent_name>_client_<framework>.py 各 A2A エージェント用の接続ごとの A2A クライアント

クライアントのサフィックスは、エージェントのフレームワーク（_strands または _langchain）に一致します。両方とも同じフレームワークに依存しない署名済み ClientConfig をラップします：Strands クライアントは Strands A2AAgent をラップし、LangChain クライアントは a2a SDK を直接駆動します。

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

エージェントの agent.py を変換して、@tool を使用してリモート A2A エージェントをツールとして登録
agent_connection プロジェクトをエージェントプロジェクトのワークスペース依存関係として追加
エージェントの dev ターゲットを更新して、ターゲットエージェントの dev ターゲットに依存するように設定

接続された A2A Agent の使用

ジェネレーターは、エージェントの agent.py を変換して、リモート A2A エージェントをツールとしてラップします。リモートエージェントは @tool で装飾されたデリゲートで登録されます。デコレーターのインポートとエージェントコンストラクターはフレームワークによって異なります：

Strands
LangChain

from contextlib import contextmanager
from strands import Agent, tool

from my_scope_agent_connection import RemoteAgentClientStrands

@contextmanager
def get_agent():
    remote_agent = RemoteAgentClientStrands.create()

    @tool
    def ask_remote_agent(prompt: str) -> str:
        """Delegate a question to the remote RemoteAgent A2A agent and return its reply."""
        return str(remote_agent(prompt))

    yield Agent(
        system_prompt="...",
        tools=[ask_remote_agent],
    )

from langchain.agents import create_agent
from langchain_aws import ChatBedrockConverse
from langchain_core.tools import tool

from my_scope_agent_connection import RemoteAgentClientLangChain

def get_agent():
    remote_agent = RemoteAgentClientLangChain.create()

    @tool
    def ask_remote_agent(prompt: str) -> str:
        """Delegate a question to the remote RemoteAgent A2A agent and return its reply."""
        return str(remote_agent(prompt))

    return create_agent(
        model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
        system_prompt="...",
        tools=[ask_remote_agent],
    )

両方のクライアントは直接呼び出し可能で、リモートエージェントの応答を返します。また、AWS にデプロイされた場合は SigV4 でリクエストに署名し、LOCAL_DEV=true の場合はプレーンな http://localhost:<port>/ エンドポイントを使用する httpx.AsyncClient をラップします。Strands クライアントは Strands A2AAgent をラップし、LangChain クライアントは a2a SDK を直接駆動します。

AgentCore セッション ID は、フレームワークに関係なく X-Amzn-Bedrock-AgentCore-Runtime-Session-Id ヘッダーを介してリモートエージェントに自動的に伝播されます：エージェントサーバーは受信リクエストのセッションを非同期コンテキストにバインドし、接続クライアントの署名済み httpx.Auth がすべての送信呼び出しにスタンプします。これにより、Bedrock AgentCore Observability の一貫性が保証されます。

インフラストラクチャ

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

CDK
Terraform

const remoteAgent = new RemoteAgent(this, 'RemoteAgent');
const myAgent = new MyAgent(this, 'MyAgent');

// Grant the host agent permission to invoke the remote A2A agent
remoteAgent.grantInvokeAccess(myAgent);

A2AエージェントのgrantInvokeAccessは、bedrock-agentcore:InvokeAgentRuntimeとbedrock-agentcore:GetAgentCardの両方を設定します。A2Aクライアントは、エージェントカードを取得してメッセージを送信するために両方が必要です。

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

module "remote_agent" {
  source = "../../common/terraform/src/app/agents/remote-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

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

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

# Grant the host agent permission to invoke the remote A2A agent
resource "aws_iam_policy" "agent_invoke_a2a" {
  name = "AgentInvokeA2aPolicy"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:GetAgentCard",
      ]
      Resource = module.remote_agent.agent_core_runtime_arn
    }]
  })
}

resource "aws_iam_role_policy_attachment" "agent_invoke_a2a" {
  role       = module.my_agent.agent_core_runtime_role_arn
  policy_arn = aws_iam_policy.agent_invoke_a2a.arn
}

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

ローカル開発

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

接続された A2A エージェントを自動的に起動
LOCAL_DEV=true を設定して、生成されたクライアントが AgentCore の代わりに http://localhost:<port>/ に直接接続するようにする

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

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>

これにより、ホストエージェントとすべての接続された A2A エージェントが起動し、ホストエージェントは割り当てられたローカルポートでプレーン HTTP を介してリモートエージェントを呼び出します。