AgentCore Gateway a Agent

El generador connection puede registrar un agente (ya sea TypeScript o Python) como un destino de tiempo de ejecución de AgentCore 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 tiempo de ejecución 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 tiempos de ejecución de los 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 — ver Reenvío de identidad del llamador al tiempo de ejecución).

Agentes HTTP de TypeScript

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

Uso

Ejecutar el generador

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

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

Selecciona el proyecto Gateway como origen y el proyecto del agente como destino. Si el proyecto del 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 son modificados:

• 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 un 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 sobrescribir 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 tiempo de ejecución 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

Anteponer un agente con 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 tiempo de ejecución 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 salida, no una subred privada aislada: el tiempo de ejecución necesita acceso saliente a internet 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 subredes) 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

Anteponer un Gateway a un agente es lo que hace accesible a un agente desplegado en una VPC: los llamadores se comunican con el endpoint público del Gateway, y el Gateway alcanza el tiempo de ejecución internamente. Establece las variables de 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 salida (una ruta a un NAT gateway), no subredes privadas aisladas: el tiempo de ejecución necesita acceso saliente a internet 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 tiempo de ejecución del agente sin traducción de protocolo, por lo que los llamadores usan la misma forma de solicitud que usarían contra el tiempo de ejecución 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 de conexión de sitio web React a AgentCore Gateway.

Reenvío de identidad del llamador al tiempo de ejecución

Por defecto, el Gateway firma las llamadas salientes con su propio rol de IAM (el proveedor de credenciales GATEWAY_IAM_ROLE), por lo que el tiempo de ejecución ve la identidad del Gateway, no la del llamador. Si en cambio deseas que el agente autorice en función del llamador — por ejemplo, para leer las reclamaciones sub o scope del usuario — antepón un Gateway Cognito a un agente Cognito. El Gateway entonces reenvía el JWT del llamador al tiempo de ejecución sin cambios (el proveedor de credenciales JWT_PASSTHROUGH), y el tiempo de ejecución 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 frontaliza el mismo grupo de usuarios de Cognito.

Todo lo demás es automático — gateway.addAgent(agent) (CDK) y el módulo de tiempo de ejecución de Terraform generado manejan el cableado por ti según el auth del agente:

• el destino se crea con el proveedor de credenciales JWT_PASSTHROUGH (en lugar de GATEWAY_IAM_ROLE), y
• el tiempo de ejecución incluye en la lista permitida el encabezado Authorization para que el token reenviado llegue a tu código de agente. Sin esta lista permitida, 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 tiempo de ejecución 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 paso de JWT es adecuado para un único proveedor de identidad cuya audiencia de token ya cubre el tiempo de ejecución. Si un Gateway frontaliza agentes a través de múltiples inquilinos o audiencias, usa en su lugar el intercambio de tokens en nombre de de OAuth.

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.