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

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

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

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

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	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 du même compte AWS
  - 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 iacProvider 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
Terraform

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

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

CDK
Terraform

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

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

Une AgentCore::Gateway configurée pour le protocole MCP avec GatewayAuthorizer.usingAwsIam() (authentification IAM entrante)
Un AgentCore::PolicyEngine fonctionnant en mode ENFORCE, attaché à la Gateway (omis lorsque cedarPolicy: false)
Une AgentCore::Policy par fichier .cedar dans policies/

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.

Écriture de politiques

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 :

permit (
  principal is AgentCore::IamEntity,
  action == AgentCore::Action::"ts-mcp___divide",
  resource == AgentCore::Gateway::"<%= gatewayArn %>"
) when {
  principal.id like "<%= tsAgentRoleArn %>/*"
};

Passez l’ARN 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 ou de le faire correspondre par motif. 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 l’ARN du rôle d’exécution d’un agent à l’exemple ts-agent-divide.cedar ci-dessus :

CDK
Terraform

Dans packages/common/constructs/src/app/gateways/<name>/<name>.ts, ajoutez à l’objet passé à ejs.render :

ejs.render(raw, {
  gatewayArn: cdk.Token.asString(this.gateway.gatewayArn),
  tsAgentRoleArn: cdk.Token.asString(tsAgent.agentCoreRuntime.role.roleArn),
  // ...
}),

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
  tsAgentRoleArn = var.ts_agent_role_arn
  # ...
}

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 qui autorise tout appelant IAM du compte AWS dans lequel la Gateway est déployée :

permit (
  principal is AgentCore::IamEntity,
  action,
  resource == AgentCore::Gateway::"${gateway_arn}"
) when {
  principal.id like "arn:aws:*::${account_id}:*"
};

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

Pour les Gateways générées par ce plugin, tous les appelants sont des principaux IAM (la Gateway est configurée avec GatewayAuthorizer.usingAwsIam()) :

principal is AgentCore::IamEntity

L’attribut id du principal contient l’ARN IAM de l’appelant. Les appelants arrivent généralement sous forme d’ARN de rôle assumé STS avec un suffixe de session généré, donc passez l’ARN exact du rôle en tant que variable de modèle et faites correspondre le suffixe de session avec like :

principal.id like "<%= myAgentRoleArn %>/*"

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

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

yarn nx dev <name>

npx nx dev <name>

bunx nx dev <name>

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

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 MCP Agréger un serveur MCP derrière une AgentCore Gateway

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

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

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