Python Agent para A2A Agent

O gerador connection pode conectar seu Python Agent a um agente A2A remoto — seja TypeScript ou Python — para que seu agente possa delegar a outro agente como uma ferramenta.

O gerador configura toda a conexão necessária para que seu agente possa descobrir e invocar o agente A2A remoto, tanto quando implantado na AWS (via Bedrock AgentCore) quanto quando executado localmente.

Pré-requisitos

Antes de usar este gerador, certifique-se de ter:

Um projeto Python com um componente Python Agent (Strands ou LangChain)
Um projeto com um componente Agent gerado com --protocol=a2a e --auth=iam (seja ts#agent ou py#agent)
Ambos os componentes criados com 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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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 o Nx Console VSCode Plugin se ainda não o fez
Abra o console Nx no VSCode
Clique em Generate (UI) na seção "Common Nx Commands"
Procure por @aws/nx-plugin - connection
Preencha os parâmetros obrigatórios
Clique em Generate

Selecione seu projeto de agente host como origem e seu projeto de agente A2A como destino. Se seus projetos contiverem múltiplos componentes, especifique as opções sourceComponent e targetComponent para desambiguar.

Opções

Parâmetro	Tipo	Padrão	Descrição
sourceProject Obrigatório	string	-	O projeto de origem
targetProject Obrigatório	string	-	O projeto de destino para conectar
sourceComponent	string	-	O componente de origem para conectar (nome do componente, caminho relativo à raiz do projeto de origem, ou id do gerador). Use '.' para selecionar explicitamente o projeto como origem.
targetComponent	string	-	O componente de destino para conectar (nome do componente, caminho relativo à raiz do projeto de destino, ou id do gerador). Use '.' para selecionar explicitamente o projeto como destino.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que os geradores subsequentes possam calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

O gerador cria um projeto Python compartilhado agent_connection em packages/common/agent_connection/ (se ainda não existir). Módulos de cliente por conexão são gerados neste projeto compartilhado:

Directorypackages/common/agent_connection
- Directory<scope>_agent_connection
  - __init__.py Re-exporta clientes por conexão
  - Directorycore
    agentcore_endpoints.py Resolução de ARN/URL independente de framework
    agentcore_a2a_client_config.py Configuração de cliente A2A independente de framework (ClientConfig assinado)
    agentcore_a2a_client_<framework>.py Cliente A2A envolvendo a configuração para o framework do seu agente
    Directoryauth/ httpx.Auth SigV4 / encaminhamento de sessão independente de framework
    …
  - Directoryapp
    <target_agent_name>_client_<framework>.py Cliente A2A por conexão para cada agente A2A

O sufixo do cliente corresponde ao framework do seu agente (_strands ou _langchain). Ambos envolvem o mesmo ClientConfig assinado independente de framework: o cliente Strands envolve um A2AAgent Strands, enquanto o cliente LangChain aciona o a2a SDK diretamente.

Além disso, o gerador:

Transforma o agent.py do seu agente para registrar o agente A2A remoto como uma ferramenta usando @tool
Adiciona o projeto agent_connection como uma dependência de workspace do seu projeto de agente
Atualiza o target dev do agente para depender do target dev do agente de destino

Usando o A2A Agent Conectado

O gerador transforma o agent.py do seu agente para envolver o agente A2A remoto como uma ferramenta. O agente remoto é registrado com um delegado decorado com @tool — a importação do decorador e o construtor do agente diferem por framework:

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

Ambos os clientes são diretamente chamáveis, retornando a resposta do agente remoto, e envolvem um httpx.AsyncClient que assina requisições com SigV4 quando implantado na AWS e usa um endpoint simples http://localhost:<port>/ quando LOCAL_DEV=true. O cliente Strands envolve um A2AAgent Strands; o cliente LangChain aciona o a2a SDK diretamente.

O ID de sessão do AgentCore é propagado para o agente remoto automaticamente via cabeçalho X-Amzn-Bedrock-AgentCore-Runtime-Session-Id, independentemente do framework: o servidor do agente vincula a sessão da requisição de entrada em um contexto assíncrono, e o httpx.Auth assinado do cliente de conexão o carimba em cada chamada de saída — garantindo consistência para Bedrock AgentCore Observability.

Infraestrutura

Após executar o gerador de conexão, você precisa conceder ao agente host permissão para invocar o 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 em um agente A2A configura tanto bedrock-agentcore:InvokeAgentRuntime quanto bedrock-agentcore:GetAgentCard — o cliente A2A precisa de ambos para buscar o cartão do agente e enviar mensagens.

O ARN do runtime AgentCore do agente remoto é automaticamente registrado no namespace agentcore da Configuração de Runtime pelo construto CDK gerado, para que o agente host possa descobri-lo em tempo de execução.

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
}

O ARN do runtime AgentCore do agente remoto é automaticamente registrado no namespace agentcore da Configuração de Runtime pelo módulo Terraform gerado, para que o agente host possa descobri-lo em tempo de execução.

Desenvolvimento Local

O gerador configura o target dev do agente host para:

Iniciar o(s) agente(s) A2A conectado(s) automaticamente
Definir LOCAL_DEV=true para que o cliente gerado se conecte diretamente a http://localhost:<port>/ em vez do AgentCore

Execute o agente localmente com:

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>

Isso iniciará tanto o agente host quanto todos os agentes A2A conectados, com o agente host chamando os agentes remotos via HTTP simples em suas portas locais atribuídas.