AgentCore Gateway vers AgentCore Gateway

Le générateur connection peut enregistrer une AgentCore Gateway comme cible d’une autre AgentCore Gateway. Cela vous permet de composer des gateways de manière hiérarchique — par exemple, une gateway au niveau de l’équipe agrégeant plusieurs gateways de domaine, chacune desservant ses propres serveurs MCP.

Une fois connectée, la Gateway source agrège les outils de la Gateway cible dans son point de terminaison MCP unique. Étant donné que la Gateway cible préfixe déjà ses outils avec ses propres noms de cible, les outils apparaissent à travers la Gateway source sous la forme <gateway-target-name>___<target-name>___<tool-name> — chaque gateway dans la chaîne ajoute un préfixe. Les deux gateways évaluent leurs propres politiques Cedar : la Gateway source autorise l’appelant pour l’action préfixée, puis la Gateway cible autorise le rôle d’exécution de la Gateway source pour l’action interne.

Prérequis

Avant d’utiliser ce générateur, assurez-vous d’avoir :

1. Deux projets agentcore-gateway

Les deux gateways doivent avoir protocol: mcp, et la gateway cible doit avoir auth: iam — la gateway source invoque la cible en signant avec son propre rôle d’exécution, donc seule l’authentification entrante de la cible doit être IAM. Le générateur valide cela, et rejette également les connexions qui créeraient un cycle entre les gateways, ce qui provoquerait sinon une récursion infinie sur tools/list.

Utilisation

Exécuter le générateur

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --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 - connection
5. Remplissez les paramètres requis
6. Cliquez sur Generate

Sélectionnez le projet Gateway agrégeant comme source et la Gateway à agréger comme cible.

Options

Paramètre	Type	Par défaut	Description
sourceProject Requis	string	-	Le projet source
targetProject Requis	string	-	Le projet cible auquel se connecter
sourceComponent	string	-	Le composant source depuis lequel se connecter (nom du composant, chemin relatif à la racine du projet source, ou identifiant du générateur). Utilisez '.' pour sélectionner explicitement le projet comme source.
targetComponent	string	-	Le composant cible auquel se connecter (nom du composant, chemin relatif à la racine du projet cible, ou identifiant du générateur). Utilisez '.' pour sélectionner explicitement le projet comme cible.
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 à 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 relie les projets existants ensemble plutôt que d’émettre de nouveaux fichiers source. Les fichiers suivants sont modifiés :

• Répertoirepackages/<source-gateway>

  • project.json la cible dev de la Gateway source gagne une dépendance sur la cible dev de la gateway cible
  • local-dev.ts ATTACHED_MCP_SERVERS mis à jour pour que la gateway locale agrège la gateway cible

La cible dev du projet Gateway source gagne une dépendance sur la cible dev de la Gateway cible, donc l’exécution de la Gateway source localement démarre également la gateway cible (et, transitivement, chaque serveur MCP qui y est attaché). La gateway cible est également enregistrée dans le local-dev.ts du projet Gateway source afin que la gateway locale agrège ses outils.

Ajouter la cible gateway à votre stack

Le générateur ne peut pas automatiquement intégrer la cible gateway dans votre infrastructure car il ne sait pas quelle stack ou quel module instancie les Gateways. Ajoutez vous-même un seul appel à gateway.addGateway(targetGateway).

CDK

Dans la stack où vous instanciez les Gateways, enregistrez la gateway cible comme cible de la gateway source :

packages/infra/src/stacks/application-stack.ts

const innerGateway = new InnerGateway(this, 'InnerGateway');
const outerGateway = new OuterGateway(this, 'OuterGateway');

// Register the inner gateway as a target of the outer gateway. The target
// name defaults to the inner gateway's `gatewayName` (its class name in
// kebab-case, e.g. `InnerGateway` -> `inner-gateway`).
outerGateway.addGateway(innerGateway);

Le nom de la cible Gateway (le gatewayName de la gateway cible par défaut) préfixe les noms d’action Cedar sur la gateway source — le format d’action est AgentCore::Action::"<gatewayTargetName>___<targetName>___<toolName>". Voir la section Rédaction de politiques. Gardez le nom de cible court et stable ; le modifier ultérieurement invalide toutes les politiques Cedar qui référencent l’ancien nom.

Pour remplacer le nom de cible par défaut, passez gatewayTargetName :

outerGateway.addGateway(innerGateway, { gatewayTargetName: 'inner' });

Le construct accorde au rôle d’exécution de la gateway source l’accès bedrock-agentcore:InvokeGateway à la gateway cible, et configure la cible avec iamCredentialProvider.service = 'bedrock-agentcore' afin que la gateway source signe les appels sortants en utilisant son propre rôle d’exécution. La cible est créée après la gateway cible et toutes ses propres cibles, car AgentCore récupère les outils de la cible lors de la création.

Terraform

Dans le fichier Terraform où vous instanciez les Gateways, intégrez la cible gateway :

packages/infra/src/main.tf

module "inner_gateway" {
  source = "../../common/terraform/src/app/gateways/inner-gateway"

  # Target ids of the inner gateway's own targets (e.g. its MCP servers), so
  # its gateway_url is not consumed until it serves their tools.
  tool_dependencies = [aws_bedrockagentcore_gateway_target.my_mcp_server.target_id]
}

module "outer_gateway" {
  source              = "../../common/terraform/src/app/gateways/outer-gateway"
  policy_dependencies = [aws_bedrockagentcore_gateway_target.inner_gateway.target_id]

  additional_iam_policy_statements = [
    {
      Effect   = "Allow"
      Action   = ["bedrock-agentcore:InvokeGateway"]
      Resource = [module.inner_gateway.gateway_arn]
    }
  ]
}

# Register the inner gateway as a target of the outer gateway
resource "aws_bedrockagentcore_gateway_target" "inner_gateway" {
  gateway_identifier = module.outer_gateway.gateway_id
  name               = "inner-gateway"

  target_configuration {
    mcp {
      mcp_server {
        endpoint = module.inner_gateway.gateway_url
      }
    }
  }

  credential_provider_configuration {
    gateway_iam_role {
      service = "bedrock-agentcore"
    }
  }
}

Le name de la cible (inner-gateway ci-dessus) préfixe les noms d’action Cedar sur la gateway externe — voir la section Rédaction de politiques. L’entrée additional_iam_policy_statements accorde au rôle d’exécution de la gateway externe l’accès d’invocation à la gateway interne, ce qui est requis à la fois pour récupérer les outils de la gateway interne au moment de la création de la cible et pour acheminer les appels à l’exécution. policy_dependencies garantit que les politiques Cedar référençant les actions de cette cible sont créées après que la cible a enregistré ces actions.

Ordre des cibles

AgentCore récupère les outils de la gateway interne lorsque le aws_bedrockagentcore_gateway_target est créé, donc la gateway interne doit déjà les servir. Définissez le tool_dependencies de la gateway interne sur les ids de ses propres cibles : son gateway_url passe alors par une sonde de disponibilité qui interroge tools/list jusqu’à ce que ces outils soient servis, de sorte que la cible de la gateway externe attend que la gateway interne soit prête.

Politiques Cedar à travers les gateways chaînées

Chaque gateway dans la chaîne évalue son propre ensemble de politiques :

1. La gateway source évalue l’appelant d’origine (par exemple, le rôle d’exécution d’un agent) par rapport à l’action préfixée, par exemple AgentCore::Action::"inner-gateway___my-mcp___add".
2. La gateway cible évalue le rôle d’exécution de la gateway source par rapport à l’action interne, par exemple AgentCore::Action::"my-mcp___add".

Cela signifie qu’un appel d’outil à travers une chaîne de gateways doit être autorisé à chaque saut. Le permit-all.cedar par défaut autorise tout appelant dans le même compte AWS, ce qui inclut le rôle de la gateway source ; si vous écrivez des politiques plus restrictives sur la gateway cible, rappelez-vous que le principal qu’elle voit est le rôle de la gateway source, et non l’appelant d’origine.

Développement local

L’exécution de la Gateway source localement avec :

pnpm

pnpm nx dev <source-gateway-name>

yarn

yarn nx dev <source-gateway-name>

npm

npx nx dev <source-gateway-name>

bun

bunx nx dev <source-gateway-name>

démarre la gateway source locale, la gateway cible locale et chaque serveur MCP attaché à l’une ou l’autre, chacun sur son port local assigné. Les noms d’outils sont préfixés à chaque saut exactement comme déployés (<gateway-target-name>___<target-name>___<tool-name>), de sorte que les prompts d’agent et les noms d’action Cedar restent cohérents entre les exécutions locales et déployées.

Fidélité locale

Le développement local utilise des gateways de substitution locales — des agrégateurs MCP légers démarrés par chaque projet Gateway, et non le service AgentCore Gateway. En conséquence, les politiques Cedar ne sont pas évaluées localement à aucun saut. Pour exercer les politiques Cedar, exécutez plutôt la cible serve de l’agent (voir les guides de connexion d’agent TypeScript / Python) afin que l’agent s’exécutant localement appelle la Gateway déployée.