AgentCore Gateway

Genera un proyecto Amazon Bedrock AgentCore Gateway. Un AgentCore Gateway es un punto de entrada administrado que agrega uno o más destinos de servidor MCP detrás de un único endpoint MCP, autentica solicitudes entrantes (IAM o Cognito), evalúa cada llamada de herramienta contra un motor de políticas Cedar, y firma el tráfico saliente a servidores MCP con IAM SigV4.

Uso

Generar un AgentCore Gateway

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

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

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	mcp	El protocolo de entrada expuesto por tu gateway. Solo mcp es compatible actualmente; protocolos adicionales pueden agregarse en el futuro.
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>/, además de un constructo CDK o módulo Terraform para la infraestructura:

• Directoriopackages/<name>/

  • Directoriopolicies/ Archivos fuente de políticas Cedar (omitidos 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 que agrega servidores MCP adjuntos para desarrollo local
  • project.json Agrega los destinos serve y dev

Infraestructura

La infraestructura se genera cuando infra es agentcore (el valor 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 seleccionado, creará un proyecto en packages/common que incluye los constructos CDK o módulos de Terraform correspondientes.

El proyecto común de infraestructura como código tiene la siguiente estructura:

CDK

• Directoriopackages/common/constructs

  • Directoriosrc

    • Directorioapp/ Constructos para infraestructura específica de un proyecto/generador

      • …
    • Directoriocore/ Constructos genéricos reutilizados por los constructos en app

      • …
    • index.ts Punto de entrada que exporta los constructos de app
  • project.json Objetivos de compilación y configuración del proyecto

Proyecto generado

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

Terraform

• Directoriopackages/common/terraform

  • Directoriosrc

    • Directorioapp/ Módulos de Terraform para infraestructura específica de un proyecto/generador

      • …
    • Directoriocore/ Módulos genéricos reutilizados por los módulos en app

      • …
  • project.json Objetivos de compilación y configuración del proyecto

Proyecto generado

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

CDK

• Directoriopackages/common/constructs/src

  • Directoriocore

    • Directorioagentcore-gateway/ Constructo compartido de gateway (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 configurado para el protocolo MCP con autenticación IAM entrante (predeterminada) o autenticación JWT de Cognito (consulta Authentication)
• Un AgentCore::PolicyEngine ejecutándose en modo ENFORCE, adjunto al Gateway (omitido cuando cedarPolicy: false)
• Una AgentCore::Policy por cada archivo .cedar en policies/
• Un Web ACL de AWS WAFv2 asociado con el Gateway, con registro de solicitudes en CloudWatch (habilitado por defecto — consulta AWS WAF)

La URL del Gateway se registra automáticamente en el espacio de nombres 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 a sus destinos de servidor MCP descendentes:

Authentication

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 que se ejecutan 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 son usuarios finales que se autentican a través de Cognito (por ejemplo, un sitio web o un cliente que no es de AWS).

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 autenticarte con un proveedor OIDC que no sea Cognito, modifica directamente el constructo Gateway o el módulo Terraform generado — 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 (consulta Variables de plantilla a continuación) en lugar de codificarlo de forma fija. 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 del Gateway:

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

Siempre referencia estas variables en lugar de codificar valores de forma fija.

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 predeterminada

El PolicyEngine se ejecuta en modo ENFORCE, lo que significa que se aplica semántica de denegación predeterminada: 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 determinada, 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 predeterminada bloqueará cada llamada.

Referencia de alcance de políticas

El tipo de principal depende de cómo el Gateway autentica a los llamadores (consulta Authentication).

Para un Gateway IAM, los llamadores son principales IAM:

principal is AgentCore::IamEntity

Los llamadores se evalúan como ARNs de assumed-role 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 a nivel de 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, scope, etc.) están disponibles como etiquetas de principal:

principal is AgentCore::OAuthUser

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

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 formato 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 valor predeterminado del servicio) rechaza muchas políticas legítimas — por ejemplo, un forbid que deshabilita una sola herramienta para todos los llamadores se rechaza como “Overly Restrictive”, incluso cuando está delimitado con una cláusula when. La aplicación no se ve afectada; está configurada por el modo ENFORCE del motor de políticas.

Una restricción de orden aún se aplica: una política que referencia 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 presenta el rechazo como un error opaco de 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 destino dev al proyecto Gateway, que ejecuta local-dev.ts: un gateway local que 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. Ejecutarlo inicia el gateway local y todos los servidores MCP adjuntos juntos:

pnpm

pnpm nx dev <name>

yarn

yarn nx dev <name>

npm

npx nx dev <name>

bun

bunx nx dev <name>

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

Desplegar tu AgentCore Gateway

El generador de AgentCore Gateway crea infraestructura como código CDK o Terraform basada en 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 (consulta 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 (consulta 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, incluido 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 obtener más detalles.

Puedes editar el constructo Gateway generado para agregar, eliminar o ajustar reglas (por ejemplo, para agregar reglas basadas en tasas 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 una 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 una configuración adicional.

Conexiones

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

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

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

TypeScript Agent a AgentCore GatewayConecta un TypeScript Agent a un AgentCore Gateway

Python Agent a AgentCore GatewayConecta un Python Agent a un AgentCore Gateway