TypeScript Agent から A2A Agent へ

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

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

前提条件

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

1. Strands Agent コンポーネント（任意のプロトコル）を持つ TypeScript プロジェクト
2. --protocol=a2a および --auth=iam で生成された Agent コンポーネントを持つプロジェクト（ts#agent または py#agent）
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

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

オプション

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

ジェネレーターの出力

ジェネレーターは共有の agent-connection パッケージを作成し、エージェントコードを変更します：

• Directorypackages/common/agent-connection

  • Directorysrc

    • Directoryapp

      • <target-agent-name>-client-strands.ts 接続された A2A エージェント用の高レベル Strands クライアント
    • Directorycore

      • agentcore-endpoints.ts フレームワーク非依存の ARN/URL 解決
      • agentcore-fetch.ts フレームワーク非依存の SigV4 / JWT / セッション転送 fetch
      • agentcore-a2a-client-config.ts フレームワーク非依存の A2A クライアント設定（署名付き clientFactory）
      • agentcore-a2a-client-strands.ts 設定をラップする Strands A2A クライアント
    • index.ts すべてのクライアントをエクスポート
  • project.json
  • tsconfig.json

さらに、以下を行います：

• エージェントの agent.ts を変換して、リモート A2A エージェントを Strands tool として登録
• エージェントの dev ターゲットを更新して、ターゲットエージェントの dev ターゲットに依存するように設定
• 必要な依存関係をインストール

接続された A2A Agent の使用

ジェネレーターは、エージェントの agent.ts を変換して、リモート A2A エージェントをツールとしてラップします：

packages/example/src/my-agent/agent.ts

import { Agent, tool } from '@strands-agents/sdk';
import { RemoteAgentClientStrands } from '@my-scope/agent-connection';
import { z } from 'zod';

export const getAgent = async (sessionId: string) => {
  const remoteAgent = await RemoteAgentClientStrands.create(sessionId);
  const remoteAgentTool = tool({
    name: 'askRemoteAgent',
    description: 'Delegate a question to the remote RemoteAgent A2A agent and return its reply.',
    inputSchema: z.object({ prompt: z.string() }),
    callback: async ({ prompt }) => (await remoteAgent.invoke(prompt)).toString(),
  });
  return new Agent({
    systemPrompt: '...',
    tools: [remoteAgentTool],
  });
};

sessionId パラメーターは呼び出し元から渡され、Bedrock AgentCore Observability の一貫性を保証します。

内部的には、RemoteAgentClientStrands.create(sessionId) は、AWS にデプロイされた場合は SigV4 署名付きの clientFactory で構成された Strands A2AAgent を返し、LOCAL_DEV=true の場合はプレーンな http://localhost:<port>/ エンドポイントを返します。署名とエンドポイント解決はフレームワーク非依存の agentcore-a2a-client-config.ts に存在し、薄い agentcore-a2a-client-strands.ts のみが Strands に依存します。

インフラストラクチャ

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

CDK

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

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

Terraform

packages/infra/src/main.tf

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 ターゲットを次のように構成します：

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

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

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>

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