AgentCore Gateway

Génère un projet Amazon Bedrock AgentCore Gateway. Un AgentCore Gateway est un point d’entrée géré devant vos serveurs MCP ou agents, authentifiant les requêtes entrantes (IAM ou Cognito) et signant le trafic sortant vers ses cibles avec IAM SigV4.

L’option protocol sélectionne ce que le Gateway expose :

• mcp (par défaut) — agrège une ou plusieurs cibles de serveur MCP derrière un seul point de terminaison MCP, et évalue chaque appel d’outil contre un moteur de politique Cedar.
• http — proxie les requêtes directement vers les cibles AgentCore Runtime (vos agents) via un routage basé sur le chemin (/<targetName>/invocations), sans agrégation ni traduction de protocole. Utilisez ceci pour exposer des agents avec un seul point de terminaison gouverné — par exemple pour qu’un site web puisse atteindre des agents déployés dans un VPC via le Gateway.

Utilisation

Générer 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

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

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. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - agentcore-gateway
5. Remplissez les paramètres requis
6. Cliquez sur Generate

Options

Paramètre	Type	Par défaut	Description
name Requis	string	-	Le nom de votre projet AgentCore Gateway
directory	string	packages	Répertoire parent où le projet gateway est placé.
subDirectory	string	-	Le sous-répertoire dans lequel le projet est placé. Par défaut, il s'agit du nom du projet.
protocol	mcp | http	mcp	Le protocole entrant exposé par votre passerelle. Une passerelle mcp agrège les cibles de serveur MCP en un seul point de terminaison MCP. Une passerelle http achemine les requêtes vers les cibles d'exécution d'agent via un routage basé sur le chemin, permettant aux appelants (par exemple un site web) d'atteindre les agents via la passerelle.
auth	iam | cognito	iam	La méthode utilisée pour authentifier les requêtes entrantes vers votre gateway. Seul iam est pris en charge aujourd'hui ; cognito et custom-jwt pourront être ajoutés à l'avenir.
cedarPolicy	boolean	true	Indique s'il faut inclure un moteur de politique Cedar appliquant une autorisation fine sur le gateway.
infra	agentcore | none	agentcore	Le type d'infrastructure pour héberger votre gateway. Sélectionnez none pour aucun hébergement.
iac	inherit | cdk | terraform	inherit	Le fournisseur IaC préféré. Par défaut, il est hérité de votre sélection initiale.
preferInstallDependencies	boolean	true	Indique s'il faut privilégier l'installation des dépendances après l'exécution du générateur. Définir sur false pour différer l'installation lors de l'exécution de plusieurs générateurs en lot (une installation s'exécute quand même si nécessaire pour que les générateurs suivants puissent calculer le graphe de projet Nx) ; installer une seule fois à la fin.

Sortie du générateur

Le générateur crée un nouveau projet dans packages/<name>/, plus un construct CDK ou un module Terraform pour l’infrastructure :

• Répertoirepackages/<name>/

  • Répertoirepolicies/ Fichiers source de politique Cedar (protocole mcp uniquement ; omis quand cedarPolicy: false)

    • permit-all.cedar Politique Cedar par défaut qui autorise les appelants authentifiés
    • README.md Référence pour écrire des politiques Cedar
  • local-dev.ts Gateway local pour le développement local — agrège les serveurs MCP attachés (mcp) ou proxie les agents attachés (http)
  • project.json Ajoute les cibles serve et dev

Infrastructure

L’infrastructure est générée lorsque infra est agentcore (par défaut). Avec infra: none, aucune infrastructure n’est générée — réexécutez le générateur avec infra: agentcore plus tard pour l’ajouter.

Étant donné que ce générateur fournit de l’infrastructure en tant que code basée sur votre iac choisi, il créera un projet dans packages/common qui inclut les constructs CDK ou modules Terraform pertinents.

Le projet d’infrastructure en tant que code commun est structuré comme suit :

CDK

• Répertoirepackages/common/constructs

  • Répertoiresrc

    • Répertoireapp/ Constructs pour l’infrastructure spécifique à un projet/générateur

      • …
    • Répertoirecore/ Constructs génériques qui sont réutilisés par les constructs dans app

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

Projet généré

Ce projet est généré en utilisant le générateur ts#project et configure donc les mêmes cibles de build.

Terraform

• Répertoirepackages/common/terraform

  • Répertoiresrc

    • Répertoireapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Répertoirecore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Projet généré

Ce projet est généré en utilisant le générateur terraform#project et configure donc les mêmes cibles de build.

CDK

• Répertoirepackages/common/constructs/src

  • Répertoirecore

    • Répertoireagentcore-gateway/ Construct de gateway partagé (sonde de disponibilité, chargement de politique Cedar)

      • …
  • Répertoireapp

    • Répertoiregateways

      • Répertoire<name>/

        • <name>.ts Construct CDK pour déployer le Gateway

Terraform

• Répertoirepackages/common/terraform/src

  • Répertoireapp

    • Répertoiregateways

      • Répertoire<name>/

        • <name>.tf Module Terraform pour déployer le Gateway

Le construct généré crée les ressources AWS suivantes :

• Un AgentCore::Gateway avec authentification IAM entrante (par défaut) ou authentification JWT Cognito (voir Authentification). Un gateway mcp est configuré pour le protocole MCP ; un gateway http n’a pas de type de protocole, ce qu’AgentCore requiert pour ses cibles runtime
• Un AgentCore::PolicyEngine fonctionnant en mode ENFORCE, attaché au Gateway (gateways mcp uniquement ; omis quand cedarPolicy: false)
• Une AgentCore::Policy par fichier .cedar dans policies/ (gateways mcp uniquement)
• Une Web ACL AWS WAFv2 associée au Gateway, avec journalisation des requêtes vers CloudWatch (activée par défaut — voir AWS WAF)

L’URL du Gateway est automatiquement enregistrée dans l’espace de noms agentcore.gateways.<ClassName> de la Configuration Runtime afin que les agents puissent la découvrir à l’exécution.

Architecture

Le Gateway déployé a l’architecture suivante, avec une Web ACL AWS WAFv2 devant le Gateway, qui route vers ses cibles de serveur MCP en aval :

Authentification

L’option auth configure comment le Gateway authentifie les requêtes entrantes. Choisissez entre iam (par défaut) et cognito.

IAM

Par défaut, le Gateway est configuré avec GatewayAuthorizer.usingAwsIam(). Les appelants signent les requêtes avec SigV4, et l’identité IAM de l’appelant est disponible pour les politiques Cedar en tant que principal AgentCore::IamEntity. C’est l’option recommandée lorsque vos appelants sont des agents ou des services s’exécutant dans AWS — par exemple un agent connecté via le générateur de connexion agent vers Gateway, qui signe ses appels avec son propre rôle d’exécution.

Cognito

Lorsque vous sélectionnez cognito, le Gateway est configuré avec un autorisateur JWT personnalisé pointant vers un pool d’utilisateurs Cognito. Les appelants s’authentifient en présentant un jeton bearer JWT, et la revendication sub du jeton est disponible pour les politiques Cedar en tant que principal AgentCore::OAuthUser. Utilisez ceci lorsque vos appelants s’authentifient via Cognito — par exemple un site web ou un agent de codage se connectant via le générateur ts#dcr-proxy.

L’infrastructure générée consomme un pool d’utilisateurs Cognito et un client existants — elle ne les crée pas. Vous pouvez générer une UserIdentity en utilisant le générateur ts#website#auth, ou fournir la vôtre.

CDK

Le construct généré nécessite une prop identity fournissant le pool d’utilisateurs et le client :

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

Le module généré nécessite les variables user_pool_id et 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]
}

Fournisseurs OIDC personnalisés

Pour s’authentifier avec un fournisseur OIDC non-Cognito, modifiez directement le construct Gateway ou le module Terraform généré — remplacez l’URL de découverte de l’autorisateur et les clients autorisés par ceux de votre fournisseur. Les générateurs de connexion agent vers Gateway ne prennent en charge que les gateways authentifiés par IAM, car les agents signent leurs appels avec SigV4.

Écrire des politiques

cedarPolicy = true

Cedar est le langage de politique utilisé par AgentCore Gateway pour autoriser les appels d’outils. Chaque requête tools/list et tools/call transitant par le Gateway est évaluée par rapport à l’ensemble de politiques attaché, et l’appelant doit avoir au moins une instruction permit correspondante (et aucun forbid correspondant) pour que la requête réussisse.

Consultez la documentation AWS sur les politiques AgentCore Gateway pour la référence complète, y compris les modèles de politique courants.

Ajouter une politique

Pour ajouter une politique, créez un nouveau fichier .cedar à côté de permit-all.cedar. Chaque fichier .cedar dans policies/ doit contenir exactement une instruction permit ou forbid et est déployé en tant que ressource AWS::BedrockAgentCore::Policy unique. Le nom de la ressource de politique est dérivé du nom de fichier : permit-all.cedar devient PermitAll (kebab/snake-case est converti en PascalCase). Les fichiers contenant plusieurs instructions produisent des erreurs unexpected token 'forbid' au moment du déploiement — divisez-les en fichiers séparés.

Par exemple, pour autoriser uniquement un rôle d’agent spécifique à invoquer un outil particulier, créez :

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

Passez le nom du rôle en tant que variable de template (voir Variables de template ci-dessous) plutôt que de le coder en dur. Re-synth ou re-plan pour déployer la nouvelle politique.

Variables de template

Les politiques sont des templates EJS rendus au moment du synth/plan afin qu’elles restent portables entre les comptes et les redéploiements de Gateway :

Variable	Substitué par
<%= gatewayArn %>	L’ARN du Gateway déployé
<%= accountId %>	Le compte AWS dans lequel ce Gateway est déployé

Référencez toujours ces variables plutôt que de coder les valeurs en dur.

Ajouter vos propres variables

Ajoutez de nouvelles variables là où les politiques sont rendues, par exemple pour passer le nom du rôle d’exécution d’un agent à l’exemple ts-agent-divide.cedar ci-dessus :

CDK

Dans packages/common/constructs/src/app/gateways/<name>/<name>.ts, passez cedarPolicyVariables au construct partagé :

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

Terraform

Dans packages/common/terraform/src/app/gateways/<name>/<name>.tf, ajoutez à la query de la source de données rendered_policies :

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

Mode ENFORCE et refus par défaut

Le PolicyEngine fonctionne en mode ENFORCE, ce qui signifie que la sémantique de refus par défaut s’applique : si aucune instruction permit ne correspond au tuple (principal, action, ressource), la requête est refusée. Les appels d’outils qui sont refusés retournent :

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

De plus, le Gateway filtre la réponse de tools/list afin que les appelants ne voient que les outils pour lesquels ils ont au moins un permit correspondant : si un agent n’a pas la permission pour un outil donné, l’outil est entièrement masqué plutôt que d’apparaître et d’échouer au moment de l’appel.

permit-all.cedar par défaut

Le générateur fournit une politique par défaut limitée au type d’authentification du Gateway.

Pour un Gateway IAM, elle autorise tout appelant IAM du compte AWS dans lequel le Gateway est déployé :

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

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

Pour un Gateway Cognito, elle autorise tout utilisateur OAuth authentifié (l’autorisateur JWT a déjà validé le pool d’utilisateurs et le client du jeton avant que les politiques ne soient évaluées) :

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

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

Pour verrouiller davantage les choses, ajoutez des politiques plus restrictives à côté. Conservez toujours au moins un permit correspondant dans l’ensemble de politiques, sinon le refus par défaut bloquera chaque appel.

Référence de portée de politique

Le type de principal dépend de la façon dont le Gateway authentifie les appelants (voir Authentification).

Pour un Gateway IAM, les appelants sont des principaux IAM :

principal is AgentCore::IamEntity

Les appelants sont évalués en tant qu’ARN de rôle assumé STS avec le nom de session supprimé, donc un rôle peut être mis en correspondance exactement — aucun caractère générique nécessaire :

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

La même valeur est disponible en tant que principal.id pour les clauses when. Réservez like pour les véritables motifs, tels que la correspondance à l’échelle du compte dans le permit-all.cedar par défaut.

Pour un Gateway Cognito, les appelants sont des utilisateurs OAuth construits à partir de la revendication sub du jeton JWT, et les revendications JWT (nom d’utilisateur, portée, etc.) sont disponibles en tant que balises de principal :

principal is AgentCore::OAuthUser

Faites correspondre les revendications individuelles dans les clauses when — par exemple pour exiger une portée :

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

Les invocations d’outils atteignent le moteur de politique en tant qu’actions avec la forme :

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

où <target-name> est le nom de la cible Gateway (le mcpServerName du serveur MCP par défaut lors de l’utilisation de gateway.addMcpServer(...), dérivé du nom de classe du projet MCP en kebab-case — par ex. TsMcp → ts-mcp), <tool-name> est le nom de l’outil MCP, et le séparateur est ___ (trois underscores). Cedar ne prend pas en charge les caractères génériques sur les actions — faites correspondre des actions exactes, ou omettez action == pour correspondre à toutes les actions.

La ressource est toujours le Gateway lui-même :

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

Considérations de validation

L’infrastructure générée crée des politiques avec IGNORE_ALL_FINDINGS : l’analyseur Cedar d’AgentCore (FAIL_ON_ANY_FINDINGS, la valeur par défaut du service) rejette de nombreuses politiques légitimes — par exemple, un forbid désactivant un seul outil pour tous les appelants est rejeté comme “Overly Restrictive”, même lorsqu’il est limité avec une clause when. L’application n’est pas affectée ; elle est configurée par le mode ENFORCE du moteur de politique.

Une contrainte d’ordre s’applique toujours : une politique référençant AgentCore::Action::"<target>___<tool>" ne valide qu’une fois que la cible a enregistré cet outil avec le Gateway, c’est pourquoi l’infrastructure générée crée des politiques après les cibles Gateway.

Si une politique échoue au déploiement, CloudFormation affiche le rejet comme une erreur opaque Resource stabilization failed — exécutez aws bedrock-agentcore-control list-policies --policy-engine-id <id> pour récupérer les statusReasons du validateur, qui contiennent la raison réelle.

Exemple : interdire un outil tout en conservant un permit plus large

Associez un forbid étroit avec un permit plus large (Cedar évalue forbid avant 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 %>"
);

Cela empêche le rôle d’agent Python d’appeler ts-mcp___divide tout en laissant le permit-all.cedar plus large en place pour tous les autres appelants.

Développement local

Le générateur ajoute une cible dev au projet Gateway, qui exécute local-dev.ts. L’exécuter démarre le gateway local et chaque cible attachée ensemble :

pnpm

pnpm nx dev <name>

yarn

yarn nx dev <name>

npm

npx nx dev <name>

bun

bunx nx dev <name>

protocol = mcp

Le gateway local expose un seul point de terminaison MCP qui agrège chaque serveur MCP attaché (connecté via le générateur agentcore-gateway#mcp-connection), avec des outils préfixés <target>___<tool> pour correspondre au Gateway déployé.

protocol = http

Le gateway local proxie les chemins /<targetName>/... vers le serveur local de chaque agent attaché (connecté via le générateur agentcore-gateway#agent-connection), correspondant au routage basé sur le chemin du Gateway déployé.

Consultez les guides de connexion pour l’histoire complète du développement local.

Déployer votre AgentCore Gateway

Le générateur AgentCore Gateway crée une infrastructure en tant que code CDK ou Terraform basée sur votre iac sélectionné. Vous pouvez l’utiliser pour déployer votre Gateway.

CDK

Le construct CDK pour déployer votre Gateway se trouve dans le dossier common/constructs. Vous pouvez le consommer dans une application CDK, par exemple :

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

Cela configure votre infrastructure Gateway, y compris l’AgentCore::Gateway, son PolicyEngine Cedar, et la Web ACL AWS WAF (voir AWS WAF ci-dessous). Enregistrez les cibles de serveur MCP avec gateway.addMcpServer(...) — voir le guide de connexion de serveur MCP.

Terraform

Le module Terraform pour déployer votre Gateway se trouve dans le dossier common/terraform. Vous pouvez l’utiliser dans une configuration Terraform, par exemple :

packages/infra/src/main.tf

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

Cela configure votre infrastructure Gateway, y compris l’aws_bedrockagentcore_gateway, son moteur de politique Cedar, et la Web ACL AWS WAF (voir AWS WAF ci-dessous). Enregistrez les cibles de serveur MCP avec une ressource aws_bedrockagentcore_gateway_target — voir le guide de connexion de serveur MCP.

AWS WAF

Par défaut, le construct généré associe une Web ACL AWS WAFv2 au Gateway. AWS WAF inspecte chaque requête entrante en ligne avant qu’elle n’atteigne une cible, protégeant votre Gateway contre les exploits web, le trafic de bots et les attaques volumétriques. La Web ACL utilise l’ensemble de règles par défaut géré par AWS (AWSManagedRulesCommonRuleSet et AWSManagedRulesKnownBadInputsRuleSet), offrant une protection contre les exploits web courants, y compris le Top 10 OWASP. Les journaux de requêtes WAF sont écrits dans un groupe de journaux CloudWatch Logs.

La Web ACL est REGIONAL et créée dans la région du Gateway, comme requis pour les associations AgentCore Gateway.

Déviation de SizeRestrictions_BODY par rapport aux valeurs par défaut

La règle SizeRestrictions_BODY de AWSManagedRulesCommonRuleSet est remplacée par Count plutôt que Block, car la limite de 8 Ko de la règle est trop restrictive pour les charges utiles d’outils MCP typiques. Les requêtes surdimensionnées seront toujours enregistrées en tant que métriques afin que vous puissiez les surveiller. Consultez le guide limites de taille de corps AWS WAF pour plus de détails.

Vous pouvez modifier le construct Gateway généré pour ajouter, supprimer ou ajuster des règles (par exemple, pour ajouter des règles basées sur le taux ou des groupes de règles gérés supplémentaires).

CDK

Pour désactiver (par exemple, pour attacher votre propre Web ACL), définissez enableWaf sur false lorsque vous instanciez le construct Gateway :

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

Le construct expose la Web ACL créée en tant que webAcl pour une configuration supplémentaire.

Terraform

Pour désactiver (par exemple, pour attacher votre propre Web ACL), définissez enable_waf sur false sur le module Gateway :

module "my_gateway" {
  enable_waf = false
}

Le module génère l’ARN de la Web ACL créée en tant que waf_web_acl_arn pour une configuration supplémentaire.

Connexions

Utilisez le générateur connection pour intégrer ce projet avec d’autres dans votre espace de travail. Les connexions suivantes impliquent ce projet :

AgentCore Gateway to MCP ServerAggregate an MCP server behind an AgentCore Gateway

AgentCore Gateway to AgentCore GatewayAggregate an AgentCore Gateway behind another AgentCore Gateway

TypeScript Agent to AgentCore GatewayConnect a TypeScript Agent to an AgentCore Gateway

Python Agent to AgentCore GatewayConnect a Python Agent to an AgentCore Gateway

AgentCore Gateway to AgentFront an agent with an AgentCore Gateway as a runtime target

React Website to AgentCore GatewayConnect a React website to agents through an AgentCore Gateway