AgentCore Gateway

Générez un projet Amazon Bedrock AgentCore Gateway. Une AgentCore Gateway est un point d’entrée géré qui agrège un ou plusieurs serveurs MCP cibles derrière un seul point de terminaison MCP, authentifie les requêtes entrantes (IAM ou Cognito), évalue chaque appel d’outil par rapport à un moteur de politiques Cedar, et signe le trafic sortant vers les serveurs MCP avec IAM SigV4.

Utilisation

Générer une AgentCore Gateway

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

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

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	mcp	Le protocole entrant exposé par votre gateway. Seul mcp est pris en charge aujourd'hui ; des protocoles supplémentaires pourront être ajoutés à l'avenir.
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>/ contenant les fichiers source de politiques Cedar, ainsi qu’un construct CDK ou un module Terraform pour l’infrastructure :

• Répertoirepackages/<name>/

  • Répertoirepolicies/ Fichiers source de politiques Cedar (omis lorsque cedarPolicy: false)

    • permit-all.cedar Politique Cedar par défaut qui autorise les appelants authentifiés (appelants IAM du même compte AWS, ou tout utilisateur Cognito — voir Authentification)
    • README.md Référence pour écrire des politiques Cedar
  • local-dev.ts Gateway locale agrégeant les serveurs MCP attachés pour le développement local
  • project.json Ajoute les cibles serve et dev

Infrastructure

L’infrastructure est générée lorsque infra est agentcore (la valeur 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.

Ce générateur fournit de l’infrastructure as code basée sur votre iac choisi. Il créera un projet dans packages/common qui inclut les constructions CDK ou modules Terraform pertinents.

Le projet commun d’infrastructure as code est structuré comme suit :

CDK

• Répertoirepackages/common/constructs

  • Répertoiresrc

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

      • …
    • Répertoirecore/ Constructions génériques réutilisées par celles dans app

      • …
    • index.ts Point d’entrée exportant les constructions depuis app
  • project.json Cibles de build et configuration du projet

Projet généré

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

Terraform

• Répertoirepackages/common/terraform

  • Répertoiresrc

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

      • …
    • Répertoirecore/ Modules génériques réutilisés par ceux dans app

      • …
  • project.json Cibles de build et configuration du projet

Projet généré

Ce projet est généré avec 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 politiques Cedar)

      • …
  • Répertoireapp

    • Répertoiregateways

      • Répertoire<name>/

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

Terraform

• Répertoirepackages/common/terraform/src

  • Répertoireapp

    • Répertoiregateways

      • Répertoire<name>/

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

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

• Une AgentCore::Gateway configurée pour le protocole MCP avec authentification IAM entrante (par défaut) ou authentification JWT Cognito (voir Authentification)
• Un AgentCore::PolicyEngine fonctionnant en mode ENFORCE, attaché à la Gateway (omis lorsque cedarPolicy: false)
• Une AgentCore::Policy par fichier .cedar dans policies/
• Une Web ACL AWS WAFv2 associée à la Gateway, avec journalisation des requêtes vers CloudWatch (activée par défaut — voir AWS WAF)

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

Architecture

La Gateway déployée a l’architecture suivante. Les requêtes entrantes passent par une Web ACL AWS WAFv2 et l’authentification IAM, sont autorisées par rapport au moteur de politiques Cedar, puis routées vers les serveurs MCP cibles en aval :

Authentification

L’option auth configure la manière dont la Gateway authentifie les requêtes entrantes. Choisissez entre IAM (par défaut) et Cognito.

IAM

Par défaut, la Gateway est configurée 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, la Gateway est configurée 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 le 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: {
        userPool: identity.userPool,
        userPoolClient: identity.userPoolClient,
      },
    });
  }
}

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ées par IAM, car les agents signent leurs appels avec SigV4.

Écriture de 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 la Gateway est évaluée par rapport à l’ensemble de politiques attaché, et l’appelant doit avoir au moins une instruction permit correspondante (et aucune forbid correspondante) 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 politiques 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é comme une seule ressource AWS::BedrockAgentCore::Policy. 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 modèle (voir Variables de modèle ci-dessous) plutôt que de le coder en dur. Resynthétisez ou replanifiez pour déployer la nouvelle politique.

Variables de modèle

Les politiques sont des modèles EJS rendus au moment de la synthèse/planification afin qu’elles restent portables entre les comptes et les redéploiements de Gateway :

Variable	Substitué par
<%= gatewayArn %>	L’ARN de la Gateway déployée
<%= accountId %>	Le compte AWS dans lequel cette Gateway est déployée

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

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, resource), 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, la Gateway filtre la réponse de tools/list de sorte 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 adaptée au type d’authentification de la Gateway.

Pour une Gateway IAM, elle autorise tout appelant IAM du compte AWS dans lequel la Gateway est déployée :

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

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

Pour une 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 manière dont la Gateway authentifie les appelants (voir Authentification).

Pour une 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é, de sorte qu’un rôle peut être mis en correspondance exactement — aucun caractère générique n’est 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 une 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 politiques sous forme d’actions avec la forme :

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

où <target-name> est le nom de cible de 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 exemple TsMcp → ts-mcp), <tool-name> est le nom de l’outil MCP, et le séparateur est ___ (trois traits de soulignement). 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 la Gateway elle-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 délimité avec une clause when. L’application n’est pas affectée ; elle est configurée par le mode ENFORCE du moteur de politiques.

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

Si une politique échoue lors du déploiement, CloudFormation présente le rejet sous forme d’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 une autorisation 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 refuse au 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 : une gateway locale exposant 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 à la Gateway déployée. Son exécution démarre la gateway locale et tous les serveurs MCP attachés ensemble :

pnpm

pnpm nx dev <name>

yarn

yarn nx dev <name>

npm

npx nx dev <name>

bun

bunx nx dev <name>

Consultez le guide 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 en fonction de 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 l’utiliser 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(...) — consultez 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 politiques 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 — consultez le guide de connexion de serveur MCP.

AWS WAF

Par défaut, le construct généré associe une Web ACL AWS WAFv2 à la 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 de l’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 de la 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 AWS WAF body size limits 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ées 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 dans 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 vers Serveur MCPAgréger un serveur MCP derrière une AgentCore Gateway

AgentCore Gateway vers AgentCore GatewayAgréger une AgentCore Gateway derrière une autre AgentCore Gateway

TypeScript Agent vers AgentCore GatewayConnecter un TypeScript Agent à une AgentCore Gateway

Python Agent vers AgentCore GatewayConnecter un Python Agent à une AgentCore Gateway