TypeScript Agent to A2A Agent

Il generatore connection può connettere il tuo TypeScript Agent a un agente A2A remoto — sia TypeScript che Python — in modo che il tuo agente possa delegare a un altro agente come strumento.

Il generatore configura tutto il cablaggio necessario affinché il tuo agente possa scoprire e invocare l’agente A2A remoto, sia quando viene distribuito su AWS (tramite Bedrock AgentCore) sia quando viene eseguito localmente.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

1. Un progetto TypeScript con un componente Strands Agent (qualsiasi protocollo)
2. Un progetto con un componente Agent generato con --protocol=a2a e --auth=iam (sia ts#agent che py#agent)
3. Entrambi i componenti creati con infra: agentcore

Utilizzo

Esegui il Generatore

Esegui questo generatore@aws/nx-plugin:connection

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

VSCode

1. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - connection
5. Compila i parametri richiesti
6. Clicca su Generate

Componi il tuo comando5

sourceProjectObbligatorio

targetProjectObbligatorio

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-runPuoi anche eseguire una prova per vedere quali file verrebbero modificati

Seleziona il progetto del tuo agente host come sorgente e il progetto del tuo agente A2A come destinazione. Se i tuoi progetti contengono più componenti, specifica le opzioni sourceComponent e targetComponent per disambiguare.

Opzioni

Opzioni del generatore5 opzioni

sourceProjectObbligatoriostring

Il progetto sorgente

targetProjectObbligatoriostring

Il progetto di destinazione a cui connettersi

sourceComponentstring

Il componente sorgente da cui connettersi (nome del componente, percorso relativo alla radice del progetto sorgente, o id del generatore). Usa '.' per selezionare esplicitamente il progetto come sorgente.

targetComponentstring

Il componente destinazione a cui connettersi (nome del componente, percorso relativo alla radice del progetto destinazione, o id del generatore). Usa '.' per selezionare esplicitamente il progetto come destinazione.

preferInstallDependenciesbooleanPredefinito: true

Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

Il generatore crea un pacchetto condiviso agent-connection e modifica il codice del tuo 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

Inoltre:

• Trasforma il file agent.ts del tuo agente per registrare l’agente A2A remoto come tool di Strands
• Aggiorna il target dev dell’agente per dipendere dal target dev dell’agente di destinazione
• Installa le dipendenze richieste

Utilizzo dell’Agente A2A Connesso

Il generatore trasforma il file agent.ts del tuo agente per avvolgere l’agente A2A remoto come strumento:

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 () => {
  const remoteAgent = await RemoteAgentClientStrands.create();
  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],
  });
};

L’ID di sessione AgentCore viene propagato automaticamente all’agente remoto tramite l’header X-Amzn-Bedrock-AgentCore-Runtime-Session-Id, quindi create() non richiede argomenti: il server dell’agente associa la sessione della richiesta in entrata in un contesto AsyncLocalStorage (enterSessionContext nel router.ts generato, o runWithSessionId nel middleware di sessione A2A/AG-UI), e il fetch del client di connessione in agentcore-fetch.ts lo applica su ogni chiamata in uscita — garantendo coerenza per Bedrock AgentCore Observability.

Internamente, RemoteAgentClientStrands.create() restituisce un A2AAgent di Strands configurato con un clientFactory che firma con SigV4 quando distribuito su AWS, e un semplice endpoint http://localhost:<port>/ quando LOCAL_DEV=true. La firma e la risoluzione degli endpoint risiedono nel file framework-agnostic agentcore-a2a-client-config.ts; solo il sottile agentcore-a2a-client-strands.ts dipende da Strands.

Infrastruttura

Dopo aver eseguito il generatore di connessioni, è necessario concedere all’agente host il permesso di invocare l’agente A2A remoto.

Progetto di infrastruttura richiesto

I generatori agent, MCP server e Gateway forniscono i loro costrutti e moduli in packages/common, ma non creano un’applicazione da cui distribuirli — quindi packages/infra non esiste finché non lo generi. Esegui il generatore ts#infra (CDK) o il generatore terraform#project (Terraform) prima di modificare il file sottostante.

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 su un agente A2A collega sia bedrock-agentcore:InvokeAgentRuntime che bedrock-agentcore:GetAgentCard — il client A2A ha bisogno di entrambi per recuperare la scheda dell’agente e inviare messaggi.

L’ARN del runtime AgentCore dell’agente remoto viene automaticamente registrato nel namespace agentcore della Configurazione Runtime dal costrutto CDK generato, in modo che l’agente host possa scoprirlo a runtime.

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
}

L’ARN del runtime AgentCore dell’agente remoto viene automaticamente registrato nel namespace agentcore della Configurazione Runtime dal modulo Terraform generato, in modo che l’agente host possa scoprirlo a runtime.

Sviluppo Locale

Il generatore configura il target dev dell’agente host per:

1. Avviare automaticamente gli agenti A2A connessi
2. Impostare LOCAL_DEV=true in modo che il client generato si connetta direttamente a http://localhost:<port>/ invece che ad AgentCore

Esegui l’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>

Questo avvierà sia l’agente host che tutti gli agenti A2A connessi, con l’agente host che chiama gli agenti remoti tramite HTTP semplice sulle loro porte locali assegnate.