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, 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

Instale el Nx Console VSCode Plugin si aún no lo ha hecho
Abra la consola Nx en VSCode
Haga clic en Generate (UI) en la sección "Common Nx Commands"
Busque @aws/nx-plugin - agentcore-gateway
Complete los parámetros requeridos
Haga clic en Generate

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

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

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

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 nx g @aws/nx-plugin:agentcore-gateway --dry-run

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

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

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	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 desde dentro de la misma cuenta de AWS
  - 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 proveedor de iacProvider 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
Terraform

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

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

CDK
Terraform

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

El constructo generado crea los siguientes recursos de AWS:

Un AgentCore::Gateway configurado para el protocolo MCP con GatewayAuthorizer.usingAwsIam() (autenticación IAM entrante)
Un AgentCore::PolicyEngine ejecutándose en modo ENFORCE, adjunto al Gateway (omitido cuando cedarPolicy: false)
Una AgentCore::Policy por cada archivo .cedar en policies/

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.

Escribir Políticas

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:

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
Terraform

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

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 que permite cualquier llamador IAM de la cuenta de AWS en la que se despliega el Gateway:

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

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

Para los Gateways generados por este plugin, todos los llamadores son principales IAM (el Gateway está configurado con GatewayAuthorizer.usingAwsIam()):

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.

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

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 nx dev <name>

yarn nx dev <name>

npx nx dev <name>

bunx nx dev <name>

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

Conexiones

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

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

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

TypeScript Agent a AgentCore Gateway Conecta un TypeScript Agent a un AgentCore Gateway

Python Agent a AgentCore Gateway Conecta un Python Agent a un AgentCore Gateway