Agente Python Strands para Agente A2A

O gerador connection pode conectar seu Python Strands 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 infraestrutura 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:

1. Um projeto Python com um componente Strands Agent (qualquer protocolo)
2. Um projeto com um componente Strands Agent gerado com --protocol=A2A e --auth=IAM (seja ts#strands-agent ou py#strands-agent)
3. Ambos os componentes criados com computeType: BedrockAgentCoreRuntime

Uso

Executar o Gerador

VSCode

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

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

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

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.

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 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_a2a_client.py Cliente A2A AgentCore principal com autenticação SigV4
    • Directoryapp

      • <target_agent_name>_client.py Cliente por conexão para cada agente A2A

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 serve-local do agente para depender do target serve-local do agente de destino

Usando o Agente A2A Conectado

O gerador transforma o agent.py do seu agente para encapsular o agente A2A remoto como uma ferramenta:

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

from contextlib import contextmanager
from strands import Agent, tool

from my_scope_agent_connection import RemoteAgentClient

@contextmanager
def get_agent(session_id: str):
    remote_agent = RemoteAgentClient.create(session_id=session_id)

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

O parâmetro session_id é propagado a partir do chamador, garantindo consistência para Bedrock AgentCore Observability.

Internamente, RemoteAgentClient.create(session_id=...) retorna um A2AAgent Strands configurado com um httpx.AsyncClient que assina requisições com SigV4 quando implantado na AWS, e um endpoint simples http://localhost:<port>/ quando SERVE_LOCAL=true.

Infraestrutura

Após executar o gerador de conexão, você precisa conceder ao agente host permissão para invocar o 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 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 Runtime Configuration pelo construto CDK gerado, para que o agente host possa descobri-lo em tempo de execução.

Terraform

packages/infra/src/main.tf

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

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

# 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 Runtime Configuration 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 serve-local do agente host para:

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

Execute o agente localmente com:

pnpm

pnpm nx <agent-name>-serve-local <project-name>

yarn

yarn nx <agent-name>-serve-local <project-name>

npm

npx nx <agent-name>-serve-local <project-name>

bun

bunx nx <agent-name>-serve-local <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.