TypeScript Agent para A2A Agent

O gerador connection pode conectar seu TypeScript 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 estrutura 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 TypeScript com um componente Strands Agent (qualquer protocolo)
2. Um projeto com um componente Agent gerado com --protocol=a2a e --auth=iam (seja ts#agent ou py#agent)
3. Ambos os componentes criados com infra: agentcore

Uso

Execute o Gerador

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

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

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 pacote compartilhado agent-connection e modifica o código do seu agente:

• Directorypackages/common/agent-connection

  • Directorysrc

    • Directoryapp

      • <target-agent-name>-client-strands.ts High-level Strands client for the connected A2A agent
    • Directorycore

      • 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

Além disso, ele:

• Transforma o agent.ts do seu agente para registrar o agente A2A remoto como uma tool do Strands
• Atualiza o target dev do agente para depender do target dev do agente de destino
• Instala as dependências necessárias

Usando o A2A Agent Conectado

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

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

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

Internamente, RemoteAgentClientStrands.create(sessionId) retorna um A2AAgent do Strands configurado com um clientFactory que assina com SigV4 quando implantado na AWS, e um endpoint simples http://localhost:<port>/ quando LOCAL_DEV=true. A assinatura e a resolução de endpoint residem no agentcore-a2a-client-config.ts agnóstico de framework; apenas o fino agentcore-a2a-client-strands.ts depende do Strands.

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 Configuração de Runtime 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"

  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:

1. Iniciar o(s) agente(s) A2A conectado(s) automaticamente
2. 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

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>

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.