Agent TypeScript vers Gateway

Le générateur connection peut connecter votre Agent TypeScript à une Gateway AgentCore.

Le générateur configure l’agent pour qu’il s’authentifie auprès de la Gateway avec IAM SigV4 lors du déploiement, et se connecte à la gateway locale démarrée par le projet Gateway lors de l’exécution en local.

Prérequis

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

1. Un projet TypeScript avec un composant Agent (infra: agentcore)
2. Un projet agentcore-gateway avec auth: iam

La Gateway doit utiliser l’authentification IAM — l’agent signe ses requêtes avec SigV4 en utilisant son propre rôle d’exécution. Le générateur rejette les gateways authentifiées par Cognito.

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 agent comme source et le projet Gateway 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 émet des fichiers client core partagés dans votre package agent-connection, plus un wrapper par Gateway, et modifie votre agent :

• Répertoirepackages/common/agent-connection

  • Répertoiresrc

    • Répertoirecore/

      • agentcore-endpoints.ts Framework-agnostic ARN/URL resolution
      • agentcore-gateway-mcp-transport.ts Framework-agnostic Gateway MCP transport
      • agentcore-gateway-mcp-client-strands.ts Strands MCP client for the deployed Gateway
    • Répertoireapp/

      • <gateway-kebab>-client-strands.ts Per-Gateway Strands client wrapper
    • index.ts Re-exports the Gateway client

De plus, le générateur :

• Modifie le fichier agent.ts de votre agent pour importer la classe client Gateway, appeler <Gateway>ClientStrands.create(), et enregistrer le client retourné dans le tableau tools
• Configure la cible <agent>-dev de l’agent pour qu’elle dépende de la cible dev de la Gateway
• Installe les dépendances SigV4 / MCP requises

Utiliser la Gateway connectée

Le générateur transforme le fichier agent.ts de votre agent pour utiliser le client Gateway :

packages/example/src/my-agent/agent.ts

import { Agent } from '@strands-agents/sdk';
import { MyGatewayClientStrands } from '@my-scope/agent-connection';

export const getAgent = async () => {
  const myGateway = await MyGatewayClientStrands.create();
  return new Agent({
    systemPrompt: '...',
    tools: [myGateway],
  });
};

Lors du déploiement (LOCAL_DEV non défini), le client pointe vers le point de terminaison MCP de la Gateway et s’authentifie avec SigV4. Lorsque LOCAL_DEV=true, il pointe vers la gateway locale démarrée par la cible dev du projet Gateway, de sorte que le même agent.ts fonctionne uniformément dans les deux modes.

L’ID de session est propagé automatiquement aux serveurs MCP en aval via l’en-tête X-Amzn-Bedrock-AgentCore-Runtime-Session-Id.

Infrastructure

Après avoir exécuté le générateur, vous devez accorder à l’agent la permission d’invoquer la Gateway.

CDK

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

const gateway = new MyGateway(this, 'MyGateway');
const myAgent = new MyAgent(this, 'MyAgent');

// Grant the agent permissions to invoke the Gateway
gateway.grantInvokeAccess(myAgent);

L’URL de la Gateway est automatiquement enregistrée dans l’espace de noms agentcore.gateways.<ClassName> de la Configuration d’exécution par le construct CDK généré, afin que l’agent puisse la découvrir au moment de l’exécution.

Terraform

packages/infra/src/main.tf

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

module "my_agent" {
  source = "../../common/terraform/src/app/agents/my-agent"

  # Grant the agent permission to invoke the Gateway
  additional_iam_policy_statements = [{
    Effect   = "Allow"
    Action   = ["bedrock-agentcore:InvokeGateway"]
    Resource = [module.my_gateway.gateway_arn]
  }]
}

L’URL de la Gateway est automatiquement enregistrée dans l’espace de noms agentcore.gateways.<ClassName> de la Configuration d’exécution par le module Terraform généré, afin que l’agent puisse la découvrir au moment de l’exécution.

Développement local

Le générateur configure la cible dev de l’agent pour :

1. Démarrer la gateway locale de la Gateway connectée et chaque serveur MCP attaché
2. Définir LOCAL_DEV=true afin que le client généré pointe vers la gateway locale au lieu de la Gateway déployée

Exécutez l’agent localement avec :

pnpm

pnpm nx <agent-name>-dev <project-name>

yarn

yarn nx <agent-name>-dev <project-name>

npm

npx nx <agent-name>-dev <project-name>

bun

bunx nx <agent-name>-dev <project-name>

Pour exécuter l’agent localement contre la Gateway déployée à la place (par exemple, pour tester les politiques Cedar), utilisez la cible serve de l’agent. Sans LOCAL_DEV défini, le client résout l’URL de la Gateway déployée à partir de la configuration d’exécution et signe les requêtes avec SigV4 en utilisant vos identifiants AWS locaux :

pnpm

pnpm nx <agent-name>-serve <project-name>

yarn

yarn nx <agent-name>-serve <project-name>

npm

npx nx <agent-name>-serve <project-name>

bun

bunx nx <agent-name>-serve <project-name>

Fidélité locale

La gateway locale remplace la Gateway déployée, donc :

• Pas d’évaluation de politique Cedar. Chaque outil est visible par l’agent indépendamment des politiques. Utilisez la cible serve pour tester les politiques contre la Gateway déployée.
• Le préfixage des noms d’outils est préservé. Les outils de chaque serveur MCP local sont encapsulés pour exposer des noms de la forme <target-name>___<tool-name>, correspondant à ce que la Gateway déployée émet. Cela maintient la cohérence du prompt système de l’agent et des noms d’actions Cedar que vous référencez entre les exécutions locales et déployées.