AgentCore Gateway

Genera un proyecto de Amazon Bedrock AgentCore Gateway. Un AgentCore Gateway es un punto de entrada administrado frente a tus servidores MCP o agentes, autenticando solicitudes entrantes (IAM o Cognito) y firmando el tráfico saliente hacia sus destinos con IAM SigV4.

La opción protocol selecciona qué frontaliza el Gateway:

• mcp (predeterminado) — agrega uno o más destinos de servidor MCP detrás de un único endpoint MCP, y evalúa cada llamada de herramienta contra un motor de políticas Cedar.
• http — envía solicitudes directamente a destinos AgentCore Runtime (tus agentes) mediante enrutamiento basado en rutas (/<targetName>/invocations), sin agregación ni traducción de protocolo. Usa esto para frontalizar agentes con un único endpoint gobernado — por ejemplo, para que un sitio web pueda alcanzar agentes que están desplegados dentro de una VPC a través del Gateway.

Uso

Generar un AgentCore Gateway

CLI

pnpm

pnpm nx g @aws/nx-plugin:agentcore-gateway

yarn

yarn nx g @aws/nx-plugin:agentcore-gateway

npm

npx nx g @aws/nx-plugin:agentcore-gateway

bun

bunx nx g @aws/nx-plugin:agentcore-gateway

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

pnpm

pnpm nx g @aws/nx-plugin:agentcore-gateway --dry-run

yarn

yarn nx g @aws/nx-plugin:agentcore-gateway --dry-run

npm

npx nx g @aws/nx-plugin:agentcore-gateway --dry-run

bun

bunx nx g @aws/nx-plugin:agentcore-gateway --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 - agentcore-gateway
5. Complete los parámetros requeridos
6. Haga clic en Generate

Opciones

Parámetro	Tipo	Predeterminado	Descripción
name Requerido	string	-	El nombre de tu proyecto AgentCore Gateway
directory	string	packages	Directorio padre donde se coloca el proyecto gateway.
subDirectory	string	-	El subdirectorio donde se coloca el proyecto. Por defecto, este es el nombre del proyecto.
protocol	mcp | http	mcp	El protocolo de entrada expuesto por tu gateway. Un gateway mcp agrega destinos de servidor MCP en un único endpoint MCP. Un gateway http redirige solicitudes a destinos de runtime de agentes mediante enrutamiento basado en rutas, permitiendo que los llamadores (por ejemplo, un sitio web) alcancen agentes a través del gateway.
auth	iam | cognito	iam	El método utilizado para autenticar solicitudes entrantes a tu gateway. Solo iam es compatible actualmente; cognito y custom-jwt pueden agregarse en el futuro.
cedarPolicy	boolean	true	Si se debe incluir un motor de políticas Cedar que aplique autorización de grano fino en el gateway.
infra	agentcore | none	agentcore	El tipo de infraestructura para alojar tu gateway. Selecciona none para no tener alojamiento.
iac	inherit | cdk | terraform	inherit	El proveedor IaC preferido. Por defecto, se hereda de tu selección inicial.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establece en false para diferir la instalación cuando se ejecutan múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsecuentes puedan calcular el grafo de proyectos de Nx); instala una vez al final.

Salida del Generador

El generador crea un nuevo proyecto en packages/<name>/, más un constructo CDK o módulo Terraform para la infraestructura:

• Directoriopackages/<name>/

  • Directoriopolicies/ Archivos fuente de políticas Cedar (solo protocolo mcp; omitido cuando cedarPolicy: false)

    • permit-all.cedar Política Cedar predeterminada que permite llamadores autenticados
    • README.md Referencia para escribir políticas Cedar
  • local-dev.ts Gateway local para desarrollo local — agrega servidores MCP adjuntos (mcp) o envía agentes adjuntos (http)
  • project.json Agrega los targets serve y dev

Infraestructura

La infraestructura se genera cuando infra es agentcore (el predeterminado). Con infra: none no se genera infraestructura — vuelve a ejecutar el generador con infra: agentcore más tarde para agregarla.

Dado que este generador proporciona infraestructura como código basada en tu iac elegido, creará un proyecto en packages/common que incluye las construcciones CDK o módulos Terraform relevantes.

El proyecto común de infraestructura como código está estructurado de la siguiente manera:

CDK

• Directoriopackages/common/constructs

  • Directoriosrc

    • Directorioapp/ Constructs for infrastructure specific to a project/generator

      • …
    • Directoriocore/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Proyecto Generado

Este proyecto se genera utilizando el generador ts#project y por lo tanto configura los mismos objetivos de compilación.

Terraform

• Directoriopackages/common/terraform

  • Directoriosrc

    • Directorioapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Directoriocore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Proyecto Generado

Este proyecto se genera utilizando el generador terraform#project y por lo tanto configura los mismos objetivos de compilación.

CDK

• Directoriopackages/common/constructs/src

  • Directoriocore

    • Directorioagentcore-gateway/ Constructo de gateway compartido (sonda de preparación, carga de políticas Cedar)

      • …
  • Directorioapp

    • Directoriogateways

      • Directorio<name>/

        • <name>.ts Constructo CDK para desplegar el Gateway

Terraform

• Directoriopackages/common/terraform/src

  • Directorioapp

    • Directoriogateways

      • Directorio<name>/

        • <name>.tf Módulo Terraform para desplegar el Gateway

El constructo generado crea los siguientes recursos de AWS:

• Un AgentCore::Gateway con autenticación IAM entrante (predeterminado) o autenticación JWT de Cognito (ver Autenticación). Un gateway mcp está configurado para el protocolo MCP; un gateway http no tiene tipo de protocolo, lo cual AgentCore requiere para sus destinos de runtime
• Un AgentCore::PolicyEngine ejecutándose en modo ENFORCE, adjunto al Gateway (solo gateways mcp; omitido cuando cedarPolicy: false)
• Una AgentCore::Policy por archivo .cedar en policies/ (solo gateways mcp)
• Un Web ACL de AWS WAFv2 asociado con el Gateway, con registro de solicitudes a CloudWatch (habilitado por defecto — ver AWS WAF)

La URL del Gateway se registra automáticamente en el namespace agentcore.gateways.<ClassName> de Runtime Configuration para que los agentes puedan descubrirla en tiempo de ejecución.

Arquitectura

El Gateway desplegado tiene la siguiente arquitectura, con un Web ACL de AWS WAFv2 frente al Gateway, que enruta hacia sus destinos de servidor MCP descendentes:

Autenticación

La opción auth configura cómo el Gateway autentica las solicitudes entrantes. Elige entre iam (predeterminado) y cognito.

IAM

Por defecto, el Gateway está configurado con GatewayAuthorizer.usingAwsIam(). Los llamadores firman solicitudes con SigV4, y la identidad IAM del llamador está disponible para las políticas Cedar como un principal AgentCore::IamEntity. Esta es la opción recomendada cuando tus llamadores son agentes o servicios ejecutándose en AWS — por ejemplo, un agente conectado a través del generador de conexión de agente a Gateway, que firma sus llamadas con su propio rol de ejecución.

Cognito

Cuando seleccionas cognito, el Gateway se configura con un autorizador JWT personalizado que apunta a un grupo de usuarios de Cognito. Los llamadores se autentican presentando un token bearer JWT, y el claim sub del token está disponible para las políticas Cedar como un principal AgentCore::OAuthUser. Usa esto cuando tus llamadores se autentican a través de Cognito — por ejemplo, un sitio web o un agente de codificación conectándose a través del generador ts#dcr-proxy.

La infraestructura generada consume un grupo de usuarios y cliente de Cognito existentes — no los crea. Puedes generar un UserIdentity usando el generador ts#website#auth, o proporcionar el tuyo propio.

CDK

El constructo generado requiere una prop identity que proporcione el grupo de usuarios y el cliente:

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

import { MyGateway, UserIdentity } from ':my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const identity = new UserIdentity(this, 'Identity');

    new MyGateway(this, 'MyGateway', {
      identity,
    });
  }
}

Terraform

El módulo generado requiere las variables user_pool_id y user_pool_client_ids:

packages/infra/src/main.tf

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "my_gateway" {
  source               = "../../common/terraform/src/app/gateways/my-gateway"
  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

Proveedores OIDC personalizados

Para autenticar con un proveedor OIDC que no sea Cognito, modifica el constructo Gateway generado o el módulo Terraform directamente — intercambia la URL de descubrimiento del autorizador y los clientes permitidos por los de tu proveedor. Los generadores de conexión de agente a Gateway solo admiten gateways autenticados con IAM, ya que los agentes firman sus llamadas con SigV4.

Escribir Políticas

cedarPolicy = true

Cedar es el lenguaje de políticas utilizado por AgentCore Gateway para autorizar llamadas de herramientas. Cada solicitud tools/list y tools/call que fluye a través del Gateway se evalúa contra el conjunto de políticas adjunto, y el llamador debe tener al menos una declaración permit coincidente (y ninguna forbid coincidente) para que la solicitud tenga éxito.

Consulta la documentación de AWS sobre políticas de AgentCore Gateway para la referencia completa, incluyendo patrones de políticas comunes.

Agregar una política

Para agregar una política, crea un nuevo archivo .cedar junto a permit-all.cedar. Cada archivo .cedar en policies/ debe contener exactamente una declaración permit o forbid y se despliega como un único recurso AWS::BedrockAgentCore::Policy. El nombre del recurso de política se deriva del nombre del archivo: permit-all.cedar se convierte en PermitAll (kebab/snake-case se convierte a PascalCase). Los archivos que contienen múltiples declaraciones producen errores unexpected token 'forbid' en tiempo de despliegue — divídelos en archivos separados.

Por ejemplo, para permitir solo que un rol de agente específico invoque una herramienta particular, crea:

packages/<name>/policies/ts-agent-divide.cedar

permit (
  principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= tsAgentRoleName %>",
  action == AgentCore::Action::"ts-mcp___divide",
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

Pasa el nombre del rol como una variable de plantilla (ver Variables de plantilla a continuación) en lugar de codificarlo. Vuelve a ejecutar synth o plan para desplegar la nueva política.

Variables de plantilla

Las políticas son plantillas EJS renderizadas en tiempo de synth/plan para que permanezcan portables entre cuentas y redespliegues de Gateway:

Variable	Sustituido con
<%= gatewayArn %>	El ARN del Gateway desplegado
<%= accountId %>	La cuenta de AWS en la que se despliega este Gateway

Siempre referencia estas variables en lugar de codificar valores.

Agregar tus propias variables

Agrega nuevas variables donde se renderizan las políticas, por ejemplo para pasar el nombre del rol de ejecución de un agente al ejemplo ts-agent-divide.cedar anterior:

CDK

En packages/common/constructs/src/app/gateways/<name>/<name>.ts, pasa cedarPolicyVariables al constructo compartido:

super(scope, id, {
  cedarPolicyPath: path.join(
    ...
  ),
  cedarPolicyVariables: {
    tsAgentRoleName: cdk.Token.asString(tsAgent.agentCoreRuntime.role.roleName),
  },
});

Terraform

En packages/common/terraform/src/app/gateways/<name>/<name>.tf, agrega al query de la fuente de datos rendered_policies:

query = {
  template        = "${local.policies_dir}/${each.value}"
  gatewayArn      = aws_bedrockagentcore_gateway.this.gateway_arn
  tsAgentRoleName = var.ts_agent_role_name
  # ...
}

Modo ENFORCE y denegación por defecto

El PolicyEngine se ejecuta en modo ENFORCE, lo que significa que se aplica semántica de denegación por defecto: si ninguna declaración permit coincide con la tupla (principal, action, resource), la solicitud se deniega. Las llamadas de herramientas que se deniegan devuelven:

Tool Execution Denied: Tool call not allowed due to policy enforcement
[No policy applies to the request (denied by default).]

Además, el Gateway filtra la respuesta de tools/list para que los llamadores solo vean las herramientas para las que tienen al menos un permit coincidente: si un agente carece de permiso para una herramienta dada, la herramienta se oculta por completo en lugar de aparecer y fallar en tiempo de llamada.

permit-all.cedar predeterminado

El generador incluye una política predeterminada con alcance al tipo de autenticación del Gateway.

Para un Gateway IAM, permite cualquier llamador IAM de la cuenta de AWS en la que se despliega el Gateway:

packages/<name>/policies/permit-all.cedar

permit (
  principal is AgentCore::IamEntity,
  action,
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
) when {
  principal.id like "arn:aws:*::<%= accountId %>:*"
};

Para un Gateway Cognito, permite cualquier usuario OAuth autenticado (el autorizador JWT ya ha validado el grupo de usuarios y el cliente del token antes de que se evalúen las políticas):

packages/<name>/policies/permit-all.cedar

permit (
  principal is AgentCore::OAuthUser,
  action,
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

Para restringir las cosas aún más, agrega políticas más estrictas junto a ella. Siempre conserva al menos un permit coincidente en el conjunto de políticas, de lo contrario la denegación por defecto bloqueará cada llamada.

Referencia de alcance de políticas

El tipo de principal depende de cómo el Gateway autentica a los llamadores (ver Autenticación).

Para un Gateway IAM, los llamadores son principales IAM:

principal is AgentCore::IamEntity

Los llamadores se evalúan como ARNs de rol asumido de STS con el nombre de sesión eliminado, por lo que un rol puede coincidir exactamente — no se necesitan comodines:

principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= myAgentRoleName %>"

El mismo valor está disponible como principal.id para cláusulas when. Reserva like para patrones genuinos, como la coincidencia de toda la cuenta en el permit-all.cedar predeterminado.

Para un Gateway Cognito, los llamadores son usuarios OAuth construidos a partir del claim sub del token JWT, y los claims JWT (nombre de usuario, alcance, etc.) están disponibles como etiquetas principales:

principal is AgentCore::OAuthUser

Coincide con claims individuales en cláusulas when — por ejemplo, para requerir un alcance:

permit (
  principal is AgentCore::OAuthUser,
  action,
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
) when {
  principal.scope == "gateway/invoke"
};

Las invocaciones de herramientas llegan al motor de políticas como acciones con la forma:

AgentCore::Action::"<target-name>___<tool-name>"

donde <target-name> es el nombre del destino del Gateway (el mcpServerName del servidor MCP por defecto cuando se usa gateway.addMcpServer(...), derivado del nombre de clase del proyecto MCP en kebab-case — por ejemplo, TsMcp → ts-mcp), <tool-name> es el nombre de la herramienta MCP, y el separador es ___ (tres guiones bajos). Cedar no admite comodines en acciones — coincide con acciones exactas, u omite action == para coincidir con todas las acciones.

El recurso es siempre el Gateway mismo:

resource == AgentCore::Gateway::"<%= gatewayArn %>"

Consideraciones de validación

La infraestructura generada crea políticas con IGNORE_ALL_FINDINGS: el analizador Cedar de AgentCore (FAIL_ON_ANY_FINDINGS, el predeterminado del servicio) rechaza muchas políticas legítimas — por ejemplo, un forbid que deshabilita una sola herramienta para cada llamador se rechaza como “Demasiado Restrictivo”, incluso cuando tiene alcance con una cláusula when. La aplicación no se ve afectada; está configurada por el modo ENFORCE del motor de políticas.

Todavía se aplica una restricción de orden: una política que hace referencia a AgentCore::Action::"<target>___<tool>" solo se valida una vez que el destino ha registrado esa herramienta con el Gateway, por lo que la infraestructura generada crea políticas después de los destinos del Gateway.

Si una política no se despliega, CloudFormation muestra el rechazo como un error opaco Resource stabilization failed — ejecuta aws bedrock-agentcore-control list-policies --policy-engine-id <id> para recuperar los statusReasons del validador, que contienen la razón real.

Ejemplo: prohibir una herramienta mientras se mantiene un permiso más amplio

Empareja un forbid estrecho con un permit más amplio (Cedar evalúa forbid sobre permit):

packages/<name>/policies/forbid-divide-for-py-agent.cedar

forbid (
  principal == AgentCore::IamEntity::"arn:aws:sts::<%= accountId %>:assumed-role/<%= pyAgentRoleName %>",
  action == AgentCore::Action::"ts-mcp___divide",
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
);

Esto deniega al rol del agente Python llamar a ts-mcp___divide mientras deja el permit-all.cedar más amplio en su lugar para todos los demás llamadores.

Desarrollo Local

El generador agrega un target dev al proyecto Gateway, que ejecuta local-dev.ts. Ejecutarlo inicia el gateway local y cada destino adjunto juntos:

pnpm

pnpm nx dev <name>

yarn

yarn nx dev <name>

npm

npx nx dev <name>

bun

bunx nx dev <name>

protocol = mcp

El gateway local expone un único endpoint MCP que agrega cada servidor MCP adjunto (conectado a través del generador agentcore-gateway#mcp-connection), con herramientas prefijadas <target>___<tool> para coincidir con el Gateway desplegado.

protocol = http

El gateway local envía rutas /<targetName>/... al servidor local de cada agente adjunto (conectado a través del generador agentcore-gateway#agent-connection), coincidiendo con el enrutamiento basado en rutas del Gateway desplegado.

Consulta las guías de conexión para la historia completa de desarrollo local.

Desplegar tu AgentCore Gateway

El generador AgentCore Gateway crea infraestructura como código CDK o Terraform según tu iac seleccionado. Puedes usar esto para desplegar tu Gateway.

CDK

El constructo CDK para desplegar tu Gateway se encuentra en la carpeta common/constructs. Puedes consumir esto en una aplicación CDK, por ejemplo:

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

import { MyGateway } from '@my-scope/common-constructs';

export class ApplicationStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    new MyGateway(this, 'MyGateway');
  }
}

Esto configura tu infraestructura de Gateway, incluyendo el AgentCore::Gateway, su PolicyEngine Cedar, y el Web ACL de AWS WAF (ver AWS WAF a continuación). Registra destinos de servidor MCP con gateway.addMcpServer(...) — consulta la guía de conexión de servidor MCP.

Terraform

El módulo Terraform para desplegar tu Gateway está en la carpeta common/terraform. Puedes usar esto en una configuración Terraform, por ejemplo:

packages/infra/src/main.tf

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

Esto configura tu infraestructura de Gateway, incluyendo el aws_bedrockagentcore_gateway, su motor de políticas Cedar, y el Web ACL de AWS WAF (ver AWS WAF a continuación). Registra destinos de servidor MCP con un recurso aws_bedrockagentcore_gateway_target — consulta la guía de conexión de servidor MCP.

AWS WAF

Por defecto, el constructo generado asocia un Web ACL de AWS WAFv2 con el Gateway. AWS WAF inspecciona cada solicitud entrante en línea antes de que llegue a un destino, protegiendo tu Gateway de exploits web, tráfico de bots y ataques volumétricos. El Web ACL utiliza el conjunto de reglas predeterminado administrado por AWS (AWSManagedRulesCommonRuleSet y AWSManagedRulesKnownBadInputsRuleSet), proporcionando protección contra exploits web comunes incluyendo el OWASP Top 10. Los registros de solicitudes de WAF se escriben en un grupo de CloudWatch Logs.

El Web ACL es REGIONAL y se crea en la región del Gateway, como se requiere para las asociaciones de AgentCore Gateway.

Desviación de SizeRestrictions_BODY de los valores predeterminados

La regla SizeRestrictions_BODY de AWSManagedRulesCommonRuleSet se anula a Count en lugar de Block, ya que el límite de 8 KB de la regla es demasiado restrictivo para las cargas útiles típicas de herramientas MCP. Las solicitudes de gran tamaño aún se registrarán como métricas para que puedas monitorearlas. Consulta la guía de límites de tamaño del cuerpo de AWS WAF para más detalles.

Puedes editar el constructo Gateway generado para agregar, eliminar o ajustar reglas (por ejemplo, para agregar reglas basadas en tasa o grupos de reglas administradas adicionales).

CDK

Para optar por no participar (por ejemplo, para adjuntar tu propio Web ACL), establece enableWaf en false cuando instancies el constructo Gateway:

new MyGateway(this, 'MyGateway', {
  enableWaf: false,
});

El constructo expone el Web ACL creado como webAcl para configuración adicional.

Terraform

Para optar por no participar (por ejemplo, para adjuntar tu propio Web ACL), establece enable_waf en false en el módulo Gateway:

module "my_gateway" {
  enable_waf = false
}

El módulo genera el ARN del Web ACL creado como waf_web_acl_arn para configuración adicional.

Conexiones

Usa el generador connection para integrar este proyecto con otros en tu espacio de trabajo. Las siguientes conexiones involucran este proyecto:

AgentCore Gateway a Servidor MCPAgregar un servidor MCP detrás de un AgentCore Gateway

AgentCore Gateway a AgentCore GatewayAgregar un AgentCore Gateway detrás de otro AgentCore Gateway

Agente TypeScript a AgentCore GatewayConectar un Agente TypeScript a un AgentCore Gateway

Agente Python a AgentCore GatewayConectar un Agente Python a un AgentCore Gateway

AgentCore Gateway a AgenteFrontalizar un agente con un AgentCore Gateway como destino de runtime

Sitio Web React a AgentCore GatewayConectar un sitio web React a agentes a través de un AgentCore Gateway