AgentCore Gateway a Agent

El generador connection puede registrar un agente (ya sea TypeScript o Python) como un destino de AgentCore Runtime de un AgentCore Gateway generado con protocol: http.

Una vez conectado, el Gateway redirige las solicitudes para el agente bajo <gatewayUrl>/<targetName>/invocations, firmando el tráfico saliente al runtime con IAM SigV4. Esto proporciona a tus agentes un único punto de entrada gobernado — y dado que los llamadores solo necesitan alcanzar el Gateway, los runtimes de agentes pueden ser desplegados dentro de una VPC detrás de él.

Requisitos previos

Antes de usar este generador, asegúrate de tener:

1. Un proyecto agentcore-gateway generado con protocol: http
2. Un componente de agente (ts#agent o py#agent) creado con infra: agentcore. Funciona tanto auth: iam (el Gateway lo invoca con su propio rol) como auth: cognito (el Gateway reenvía el JWT del llamador — consulta Reenvío de identidad del llamador).

Agentes HTTP de TypeScript

Un agente http de TypeScript sirve tRPC sobre WebSocket, y AgentCore Gateway no soporta WebSocket ni streaming bidireccional — el generador rechaza esta combinación. Genera el agente con el protocolo ag-ui en su lugar.

Uso

Ejecutar el generador

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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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 el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - connection
5. Complete los parámetros requeridos
6. Haga clic en Generate

Selecciona el proyecto Gateway como origen y el proyecto de agente como destino. Si el proyecto de agente contiene múltiples componentes, especifica targetComponent para desambiguar.

Opciones

Parámetro	Tipo	Predeterminado	Descripción
sourceProject Requerido	string	-	El proyecto de origen
targetProject Requerido	string	-	El proyecto de destino al que conectar
sourceComponent	string	-	El componente de origen desde el que conectar (nombre del componente, ruta relativa a la raíz del proyecto de origen, o id del generador). Use '.' para seleccionar explícitamente el proyecto como origen.
targetComponent	string	-	El componente de destino al que conectar (nombre del componente, ruta relativa a la raíz del proyecto de destino, o id del generador). Use '.' para seleccionar explícitamente el proyecto como destino.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al ejecutar múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsiguientes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Salida del generador

El generador conecta proyectos existentes en lugar de emitir nuevos archivos fuente. Los siguientes archivos se modifican:

• Directoriopackages/<gateway>

  • project.json el destino dev del Gateway gana una dependencia en el <agent>-dev del agente
  • local-dev.ts ATTACHED_AGENTS actualizado para que el gateway local redirija al agente

Agregar el destino del agente a tu stack

El generador no puede conectar automáticamente el destino del agente en tu infraestructura porque no sabe qué stack o módulo instancia el Gateway. Agrega una única llamada a gateway.addAgent(agent) tú mismo.

CDK

En el stack donde instancias el Gateway, registra el agente como destino:

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);

Para anular el nombre de destino predeterminado, pasa gatewayTargetName:

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

El constructo otorga al rol de ejecución del Gateway acceso de invocación al runtime del agente y configura el destino con el proveedor de credenciales GATEWAY_IAM_ROLE, por lo que el Gateway firma las llamadas salientes con su propio rol.

Desplegar agentes en una VPC

Colocar un agente detrás de un Gateway es lo que hace que un agente desplegado en VPC sea alcanzable: los llamadores hablan con el endpoint público del Gateway, y el Gateway alcanza el runtime internamente. Pasa una configuración de red VPC al constructo del agente:

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 subred privada con egreso, no una subred privada aislada: el runtime necesita acceso a internet saliente para alcanzar Bedrock y leer su configuración desde AWS AppConfig.

Los despliegues de AgentCore Runtime en VPC solo están soportados en ciertas zonas de disponibilidad. Si un despliegue falla con subnets are in unsupported availability zones, restringe la VPC (o la selección de subred) a las zonas soportadas para tu región.

Terraform

En el archivo Terraform donde instancias el Gateway, conecta el destino del agente:

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 {}
  }
}

Desplegar agentes en una VPC

Colocar un agente detrás de un Gateway es lo que hace que un agente desplegado en VPC sea alcanzable: los llamadores hablan con el endpoint público del Gateway, y el Gateway alcanza el runtime internamente. Establece las variables VPC del módulo del agente:

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 subredes privadas con egreso (una ruta a un NAT gateway), no subredes privadas aisladas: el runtime necesita acceso a internet saliente para alcanzar Bedrock y leer su configuración desde AWS AppConfig.

Invocar el agente a través del Gateway

Las solicitudes a <gatewayUrl origin>/<targetName>/invocations se reenvían al runtime del agente sin traducción de protocolo, por lo que los llamadores usan la misma forma de solicitud que usarían contra el runtime directamente — streams SSE (AG-UI), streaming JSON (Python HTTP) y A2A JSON-RPC todos se redirigen a través. Los llamadores se autentican con el Gateway (IAM SigV4 o Cognito JWT dependiendo del auth del Gateway) en lugar de con el agente.

Para conectar un sitio web a los agentes del Gateway, usa el generador connection.

Reenvío de identidad del llamador al runtime

Por defecto, el Gateway firma las llamadas salientes con su propio rol IAM (el proveedor de credenciales GATEWAY_IAM_ROLE), por lo que el runtime ve la identidad del Gateway, no la del llamador. Si en cambio quieres que el agente autorice sobre el llamador — por ejemplo para leer las reclamaciones sub o scope del usuario — coloca un agente Cognito detrás de un Gateway Cognito. El Gateway entonces reenvía el JWT del llamador al runtime sin cambios (el proveedor de credenciales JWT_PASSTHROUGH), y el runtime lo revalida.

Genera ambos extremos con auth: cognito y conéctalos como se indicó anteriormente:

• un agente (ts#agent o py#agent) creado con auth: cognito, y
• un Gateway creado con auth: cognito que coloca delante del mismo user pool de Cognito.

Todo lo demás es automático — gateway.addAgent(agent) (CDK) y el módulo de runtime Terraform generado manejan la conexión por ti basándose en el auth del agente:

• el destino se crea con el proveedor de credenciales JWT_PASSTHROUGH (en lugar de GATEWAY_IAM_ROLE), y
• el runtime incluye en la lista de permitidos el encabezado Authorization para que el token reenviado llegue a tu código de agente. Sin esta lista de permitidos, AgentCore valida el token pero elimina el encabezado antes de tu contenedor.

Los llamadores invocan el Gateway con Authorization: Bearer <jwt> (sin SigV4), y el agente lee las reclamaciones del encabezado Authorization — omitiendo la validación de firma, ya que el autorizador de entrada del runtime ya ha verificado el 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

El passthrough de JWT se adapta a un único proveedor de identidad cuya audiencia de token ya cubre el runtime. Si un Gateway coloca delante de agentes a través de múltiples tenants o audiencias, usa el intercambio de tokens on-behalf-of de OAuth en su lugar.

Desarrollo local

Ejecutar el 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>

inicia un gateway local más cada agente adjunto en su puerto local asignado. El gateway local redirige las rutas /<targetName>/... al servidor local de cada agente, coincidiendo con el enrutamiento basado en rutas del Gateway desplegado.