AgentCore Gateway ad Agent

Il generatore connection può registrare un agent (sia TypeScript che Python) come target di runtime AgentCore di un AgentCore Gateway generato con protocol: http.

Una volta connesso, il Gateway inoltra le richieste per l’agent sotto <gatewayUrl>/<targetName>/invocations, firmando il traffico in uscita verso il runtime con IAM SigV4. Questo fornisce ai tuoi agent un singolo punto di ingresso governato — e poiché i chiamanti devono solo raggiungere il Gateway, i runtime degli agent stessi possono essere distribuiti all’interno di un VPC dietro di esso.

Prerequisiti

Prima di utilizzare questo generatore, assicurati di avere:

1. Un progetto agentcore-gateway generato con protocol: http
2. Un componente agent (ts#agent o py#agent) creato con infra: agentcore. Funziona sia auth: iam (il Gateway lo invoca con il proprio ruolo) che auth: cognito (il Gateway inoltra il JWT del chiamante — vedi Inoltrare l’identità del chiamante al runtime).

Agent HTTP TypeScript

Un agent TypeScript http serve tRPC su WebSocket, e AgentCore Gateway non supporta WebSocket o streaming bidirezionale — il generatore rifiuta questa combinazione. Genera invece l’agent con il protocollo ag-ui.

Utilizzo

Esegui 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 Gateway come sorgente e il progetto agent come target. Se il progetto agent contiene più componenti, specifica 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 collega i progetti esistenti insieme piuttosto che emettere nuovi file sorgente. I seguenti file vengono modificati:

• Directorypackages/<gateway>

  • project.json il target dev del Gateway acquisisce una dipendenza dal <agent>-dev dell’agent
  • local-dev.ts ATTACHED_AGENTS aggiornato in modo che il gateway locale inoltri all’agent

Aggiungere il target agent al tuo stack

Il generatore non può collegare automaticamente il target agent nella tua infrastruttura perché non sa quale stack o modulo istanzia il Gateway. Aggiungi tu stesso una singola chiamata a gateway.addAgent(agent).

CDK

Nello stack in cui istanzi il Gateway, registra l’agent come target:

packages/infra/src/stacks/application-stack.ts

const myAgent = new MyAgent(this, 'MyAgent');
const myGateway = new MyGateway(this, 'MyGateway');

// Register the agent as a runtime target of the Gateway. The target name
// defaults to the agent's `agentName` (its class name in kebab-case,
// e.g. `MyAgent` -> `my-agent`), and forms the target's invocation path:
// <gatewayUrl>/my-agent/invocations
myGateway.addAgent(myAgent);

Per sovrascrivere il nome del target predefinito, passa gatewayTargetName:

myGateway.addAgent(myAgent, { gatewayTargetName: 'my-target' });

Il costrutto concede al ruolo di esecuzione del Gateway l’accesso di invocazione al runtime dell’agent e configura il target con il provider di credenziali GATEWAY_IAM_ROLE, in modo che il Gateway firmi le chiamate in uscita con il proprio ruolo.

Distribuire agent in un VPC

Mettere un agent dietro un Gateway è ciò che rende raggiungibile un agent distribuito in un VPC: i chiamanti parlano con l’endpoint pubblico del Gateway, e il Gateway raggiunge il runtime internamente. Passa una configurazione di rete VPC al costrutto dell’agent:

import { RuntimeNetworkConfiguration } from 'aws-cdk-lib/aws-bedrockagentcore';

const myAgent = new MyAgent(this, 'MyAgent', {
  // Give each agent its own scope for the network configuration — usingVpc
  // creates a security group named `SecurityGroup` under the scope you pass,
  // so passing `this` for more than one agent collides on the construct id.
  networkConfiguration: RuntimeNetworkConfiguration.usingVpc(
    new Construct(this, 'MyAgentNetwork'),
    {
      vpc,
      vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
    },
  ),
});

Usa una subnet privata con egress, non una subnet privata isolata: il runtime necessita di accesso internet in uscita per raggiungere Bedrock e leggere la sua configurazione da AWS AppConfig.

Le distribuzioni VPC di AgentCore Runtime sono supportate solo in determinate zone di disponibilità. Se una distribuzione fallisce con subnets are in unsupported availability zones, limita il VPC (o la selezione delle subnet) alle zone supportate per la tua regione.

Terraform

Nel file Terraform in cui istanzi il Gateway, collega il target agent:

packages/infra/src/main.tf

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

module "my_gateway" {
  source = "../../common/terraform/src/app/gateways/my-gateway"

  # The Gateway signs outbound calls to the runtime with its own role and
  # validates access at target creation, so it needs invoke access first.
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
        # A2A targets additionally serve their agent card via the gateway
        "bedrock-agentcore:GetAgentCard",
      ]
      Resource = [
        module.my_agent.agent_core_runtime_arn,
        "${module.my_agent.agent_core_runtime_arn}/*",
      ]
    }
  ]
}

# Register the agent as a runtime target of the Gateway. The target name
# forms the invocation path: <gatewayUrl>/my-agent/invocations
resource "aws_bedrockagentcore_gateway_target" "my_agent" {
  gateway_identifier = module.my_gateway.gateway_id
  name               = "my-agent"
  # AgentCore fills in a description when none is set, which the provider
  # reports as an inconsistent result after apply — so always set one.
  description = "Agent runtime target my-agent"

  target_configuration {
    http {
      agentcore_runtime {
        arn = module.my_agent.agent_core_runtime_arn
      }
    }
  }

  credential_provider_configuration {
    gateway_iam_role {}
  }
}

Distribuire agent in un VPC

Mettere un agent dietro un Gateway è ciò che rende raggiungibile un agent distribuito in un VPC: i chiamanti parlano con l’endpoint pubblico del Gateway, e il Gateway raggiunge il runtime internamente. Imposta le variabili VPC del modulo agent:

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

  enable_vpc = true
  vpc_id     = aws_vpc.my_vpc.id
  subnet_ids = [aws_subnet.private_a.id, aws_subnet.private_b.id]
}

Usa subnet private con egress (una route verso un NAT gateway), non subnet private isolate: il runtime necessita di accesso internet in uscita per raggiungere Bedrock e leggere la sua configurazione da AWS AppConfig.

Invocare l’agent attraverso il Gateway

Le richieste a <gatewayUrl origin>/<targetName>/invocations vengono inoltrate al runtime dell’agent senza traduzione del protocollo, quindi i chiamanti utilizzano la stessa forma di richiesta che userebbero direttamente contro il runtime — stream SSE (AG-UI), streaming JSON (Python HTTP) e A2A JSON-RPC passano tutti attraverso il proxy. I chiamanti si autenticano con il Gateway (IAM SigV4 o Cognito JWT a seconda dell’auth del Gateway) piuttosto che con l’agent.

Per connettere un sito web agli agent del Gateway, utilizza il generatore di connessione da sito web React ad AgentCore Gateway.

Inoltrare l’identità del chiamante al runtime

Per impostazione predefinita, il Gateway firma le chiamate in uscita con il proprio ruolo IAM (il provider di credenziali GATEWAY_IAM_ROLE), quindi il runtime vede l’identità del Gateway, non quella del chiamante. Se invece vuoi che l’agent autorizzi in base al chiamante — ad esempio per leggere i claim sub o scope dell’utente — metti un agent Cognito dietro un Gateway Cognito. Il Gateway inoltra quindi il JWT del chiamante al runtime senza modifiche (il provider di credenziali JWT_PASSTHROUGH), e il runtime lo rivalidata.

Genera entrambe le estremità con auth: cognito e collegale come sopra:

• un agent (ts#agent o py#agent) creato con auth: cognito, e
• un Gateway creato con auth: cognito che si trova davanti allo stesso user pool Cognito.

Tutto il resto è automatico — gateway.addAgent(agent) (CDK) e il modulo runtime Terraform generato gestiscono il cablaggio per te in base all’auth dell’agent:

• il target viene creato con il provider di credenziali JWT_PASSTHROUGH (anziché GATEWAY_IAM_ROLE), e
• il runtime inserisce l’header Authorization nella allowlist in modo che il token inoltrato raggiunga il codice del tuo agent. Senza questa allowlist AgentCore valida il token ma rimuove l’header prima del tuo container.

I chiamanti invocano il Gateway con Authorization: Bearer <jwt> (senza SigV4), e l’agent legge i claim dall’header Authorization — saltando la validazione della firma, poiché l’authorizer in ingresso del runtime ha già verificato il token:

packages/py_project/.../my_agent/main.py

import jwt  # PyJWT

@app.post('/invocations')
async def invoke(input: InvokeInput, request: Request):
    token = request.headers['authorization'].removeprefix('Bearer ')
    claims = jwt.decode(token, options={'verify_signature': False})
    # authorize on claims['sub'], claims['scope'], ...

Nota

Il passthrough JWT è adatto per un singolo provider di identità il cui audience del token copre già il runtime. Se un Gateway si trova davanti ad agent su più tenant o audience, utilizza invece lo scambio di token on-behalf-of OAuth.

Sviluppo Locale

Eseguendo il Gateway localmente con:

pnpm

pnpm nx dev <gateway-name>

yarn

yarn nx dev <gateway-name>

npm

npx nx dev <gateway-name>

bun

bunx nx dev <gateway-name>

avvia un gateway locale più ogni agent collegato sulla sua porta locale assegnata. Il gateway locale inoltra i percorsi /<targetName>/... al server locale di ciascun agent, corrispondendo al routing basato su percorso del Gateway distribuito.