Agente TypeScript a Agente A2A

El generador connection puede conectar tu Agente TypeScript a un agente A2A remoto — ya sea TypeScript o Python — para que tu agente pueda delegar a otro agente como una herramienta.

El generador configura todo el cableado necesario para que tu agente pueda descubrir e invocar el agente A2A remoto, tanto cuando se despliega en AWS (a través de Bedrock AgentCore) como cuando se ejecuta localmente.

Requisitos previos

Antes de usar este generador, asegúrate de tener:

Un proyecto TypeScript con un componente Strands Agent (cualquier protocolo)
Un proyecto con un componente Agent generado con --protocol=a2a y --auth=iam (ya sea ts#agent o py#agent)
Ambos componentes creados con infra: agentcore

Uso

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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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

Instale el Nx Console VSCode Plugin si aún no lo ha hecho
Abra la consola Nx en VSCode
Haga clic en Generate (UI) en la sección "Common Nx Commands"
Busque @aws/nx-plugin - connection
Complete los parámetros requeridos
Haga clic en Generate

Selecciona tu proyecto de agente anfitrión como origen y tu proyecto de agente A2A como destino. Si tus proyectos contienen múltiples componentes, especifica las opciones sourceComponent y targetComponent para desambiguar.

Opciones

Parámetro	Tipo	Predeterminado	Descripción
sourceProject Requerido	string	-	El proyecto de origen
targetProject Requerido	string	-	El proyecto de destino al que conectar
sourceComponent	string	-	El componente de origen desde el que conectar (nombre del componente, ruta relativa a la raíz del proyecto de origen, o id del generador). Use '.' para seleccionar explícitamente el proyecto como origen.
targetComponent	string	-	El componente de destino al que conectar (nombre del componente, ruta relativa a la raíz del proyecto de destino, o id del generador). Use '.' para seleccionar explícitamente el proyecto como destino.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al ejecutar múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsiguientes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Salida del Generador

El generador crea un paquete compartido agent-connection y modifica el código de tu agente:

Directoriopackages/common/agent-connection
- Directoriosrc
  - Directorioapp
    <target-agent-name>-client-strands.ts High-level Strands client for the connected A2A agent
  - Directoriocore
    agentcore-endpoints.ts Framework-agnostic ARN/URL resolution
    agentcore-fetch.ts Framework-agnostic SigV4 / JWT / session-forwarding fetch
    agentcore-a2a-client-config.ts Framework-agnostic A2A client config (signed clientFactory)
    agentcore-a2a-client-strands.ts Strands A2A client wrapping the config
  - index.ts Exports all clients
- project.json
- tsconfig.json

Además:

Transforma el agent.ts de tu agente para registrar el agente A2A remoto como una tool de Strands
Actualiza el target dev del agente para que dependa del target dev del agente destino
Instala las dependencias requeridas

Usar el Agente A2A Conectado

El generador transforma el agent.ts de tu agente para envolver el agente A2A remoto como una herramienta:

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],
  });
};

El parámetro sessionId se transmite desde el llamador, asegurando consistencia para la Observabilidad de Bedrock AgentCore.

Internamente, RemoteAgentClientStrands.create(sessionId) devuelve un A2AAgent de Strands configurado con un clientFactory que firma con SigV4 cuando se despliega en AWS, y un endpoint simple http://localhost:<port>/ cuando LOCAL_DEV=true. La firma y la resolución de endpoints residen en el agentcore-a2a-client-config.ts independiente del framework; solo el delgado agentcore-a2a-client-strands.ts depende de Strands.

Infraestructura

Después de ejecutar el generador de conexión, necesitas otorgar al agente host permiso para invocar el agente A2A remoto.

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);

grantInvokeAccess en un agente A2A configura tanto bedrock-agentcore:InvokeAgentRuntime como bedrock-agentcore:GetAgentCard — el cliente A2A necesita ambos para obtener la tarjeta del agente y enviar mensajes.

El ARN del runtime AgentCore del agente remoto se registra automáticamente en el namespace agentcore de Runtime Configuration por el constructo CDK generado, para que el agente host pueda descubrirlo en tiempo de ejecución.

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
}

El ARN del runtime AgentCore del agente remoto se registra automáticamente en el namespace agentcore de Runtime Configuration por el módulo Terraform generado, para que el agente host pueda descubrirlo en tiempo de ejecución.

Desarrollo Local

El generador configura el target dev del agente anfitrión para:

Iniciar los agentes A2A conectados automáticamente
Establecer LOCAL_DEV=true para que el cliente generado se conecte directamente a http://localhost:<port>/ en lugar de AgentCore

Ejecuta el agente localmente con:

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>

Esto iniciará tanto el agente anfitrión como todos los agentes A2A conectados, con el agente anfitrión llamando a los agentes remotos a través de HTTP simple en sus puertos locales asignados.