Agente Python ad Agente A2A

Il generatore connection può connettere il tuo Python 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) che quando viene eseguito localmente.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

1. Un progetto Python con un componente Python Agent (Strands o LangChain)
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

Eseguire il Generatore

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

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

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

Opzioni

Parametro	Tipo	Predefinito	Descrizione
sourceProject Obbligatorio	string	-	Il progetto sorgente
targetProject Obbligatorio	string	-	Il progetto di destinazione a cui connettersi
sourceComponent	string	-	Il componente sorgente da cui connettersi (nome del componente, percorso relativo alla radice del progetto sorgente, o id del generatore). Usare '.' per selezionare esplicitamente il progetto come sorgente.
targetComponent	string	-	Il componente di destinazione a cui connettersi (nome del componente, percorso relativo alla radice del progetto di destinazione, o id del generatore). Usare '.' per selezionare esplicitamente il progetto come destinazione.
preferInstallDependencies	boolean	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 progetto Python condiviso agent_connection in packages/common/agent_connection/ (se non esiste già). I moduli client per-connessione vengono generati in questo progetto condiviso:

• Directorypackages/common/agent_connection

  • Directory<scope>_agent_connection

    • __init__.py Ri-esporta i client per-connessione
    • Directorycore

      • agentcore_endpoints.py Risoluzione ARN/URL indipendente dal framework
      • agentcore_a2a_client_config.py Configurazione client A2A indipendente dal framework (ClientConfig firmato)
      • agentcore_a2a_client_<framework>.py Client A2A che avvolge la configurazione per il framework del tuo agente
      • Directoryauth/ httpx.Auth SigV4 / session-forwarding indipendente dal framework

        • …
    • Directoryapp

      • <target_agent_name>_client_<framework>.py Client A2A per-connessione per ogni agente A2A

Il suffisso del client corrisponde al framework del tuo agente (_strands o _langchain). Entrambi avvolgono lo stesso ClientConfig firmato indipendente dal framework: il client Strands avvolge uno Strands A2AAgent, mentre il client LangChain utilizza direttamente l’a2a SDK in modo che un agente LangChain non includa alcuna dipendenza da Strands.

Inoltre, il generatore:

• Trasforma il file agent.py del tuo agente per registrare l’agente A2A remoto come strumento utilizzando @tool
• Aggiunge il progetto agent_connection come dipendenza workspace del progetto del tuo agente
• Aggiorna il target serve-local dell’agente per dipendere dal target serve-local dell’agente di destinazione

Utilizzo dell’Agente A2A Connesso

Il generatore trasforma il file agent.py del tuo agente per avvolgere l’agente A2A remoto come strumento. L’agente remoto viene registrato con un delegato decorato con @tool — l’importazione del decoratore e il costruttore dell’agente differiscono per 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],
    )

Entrambi i client sono direttamente invocabili, restituendo la risposta dell’agente remoto, e avvolgono un httpx.AsyncClient che firma le richieste con SigV4 quando distribuito su AWS e utilizza un endpoint semplice http://localhost:<port>/ quando LOCAL_DEV=true. Il client Strands avvolge uno Strands A2AAgent; il client LangChain utilizza direttamente l’a2a SDK.

L’ID di sessione AgentCore viene propagato automaticamente all’agente remoto tramite l’header X-Amzn-Bedrock-AgentCore-Runtime-Session-Id, indipendentemente dal framework: il server dell’agente associa la sessione della richiesta in entrata a un contesto asincrono, e l’httpx.Auth firmato del client di connessione lo applica su ogni chiamata in uscita — garantendo coerenza per Bedrock AgentCore Observability.

Infrastruttura

Dopo aver eseguito il generatore di connessioni, è necessario concedere all’agente host il permesso di invocare l’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 su un agente A2A configura 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 Runtime Configuration 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 Runtime Configuration dal modulo Terraform generato, in modo che l’agente host possa scoprirlo a runtime.

Sviluppo Locale

Il generatore configura il target serve-local dell’agente host per:

1. Avviare automaticamente gli agenti A2A connessi
2. Impostare SERVE_LOCAL=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.