Agente Python a Agente A2A

El generador connection puede conectar tu Python Agent 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 al 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:

1. Un proyecto Python con un componente Python Agent (Strands o LangChain)
2. Un proyecto con un componente Agent generado con --protocol=A2A y --auth=IAM (ya sea ts#agent o py#agent)
3. Ambos componentes creados con infra: agentcore

Uso

Ejecutar el generador

VSCode

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

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

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

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

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 proyecto Python compartido agent_connection en packages/common/agent_connection/ (si aún no existe). Los módulos de cliente por conexión se generan en este proyecto compartido:

• Directoriopackages/common/agent_connection

  • Directorio<scope>_agent_connection

    • __init__.py Re-exporta clientes por conexión
    • Directoriocore

      • agentcore_endpoints.py Resolución de ARN/URL independiente del framework
      • agentcore_a2a_client_config.py Configuración de cliente A2A independiente del framework (ClientConfig firmado)
      • agentcore_a2a_client_<framework>.py Cliente A2A que envuelve la configuración para el framework de tu agente
      • Directorioauth/ httpx.Auth independiente del framework para SigV4 / reenvío de sesión

        • …
    • Directorioapp

      • <target_agent_name>_client_<framework>.py Cliente A2A por conexión para cada agente A2A

El sufijo del cliente coincide con el framework de tu agente (_strands o _langchain). Ambos envuelven el mismo ClientConfig firmado independiente del framework: el cliente Strands envuelve un A2AAgent de Strands, mientras que el cliente LangChain utiliza el a2a SDK directamente, por lo que un agente LangChain no incluye ninguna dependencia de Strands.

Además, el generador:

• Transforma el agent.py de tu agente para registrar el agente A2A remoto como una herramienta usando @tool
• Agrega el proyecto agent_connection como una dependencia de espacio de trabajo de tu proyecto de agente
• Actualiza el objetivo serve-local del agente para que dependa del objetivo serve-local del agente de destino

Usar el agente A2A conectado

El generador transforma el agent.py de tu agente para envolver el agente A2A remoto como una herramienta. El agente remoto se registra con un delegado decorado con @tool — la importación del decorador y el constructor del agente difieren según el framework:

Strands

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

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

LangChain

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

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

Ambos clientes son directamente invocables, devolviendo la respuesta del agente remoto, y envuelven un httpx.AsyncClient que firma solicitudes con SigV4 cuando se despliega en AWS y utiliza un endpoint simple http://localhost:<port>/ cuando SERVE_LOCAL=true. El cliente Strands envuelve un A2AAgent de Strands; el cliente LangChain utiliza el a2a SDK directamente.

El ID de sesión de AgentCore se propaga automáticamente al agente remoto a través del encabezado X-Amzn-Bedrock-AgentCore-Runtime-Session-Id, independientemente del framework: el servidor del agente vincula la sesión de la solicitud entrante en un contexto asíncrono, y el httpx.Auth firmado del cliente de conexión lo estampa en cada llamada saliente — asegurando consistencia para Bedrock AgentCore Observability.

Infraestructura

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

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

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 espacio de nombres agentcore de Runtime Configuration por el constructo CDK generado, para que el agente anfitrión pueda descubrirlo en tiempo de ejecución.

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
}

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

Desarrollo local

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

1. Iniciar los agentes A2A conectados automáticamente
2. 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

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>

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. gnados.