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 :

Un projet TypeScript avec un composant Agent (infra: agentcore)
Un projet agentcore-gateway avec protocol: mcp et auth: iam

La Gateway doit servir le protocole mcp — l’agent l’atteint en tant que client MCP, de sorte que ses cibles sont exposées en tant qu’outils. La Gateway doit également 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

Exécuter ce générateur@aws/nx-plugin:connection

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:connection

$ yarn nx g @aws/nx-plugin:connection

$ npx nx g @aws/nx-plugin:connection

$ bunx nx g @aws/nx-plugin:connection

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 - connection
Remplissez les paramètres requis
Cliquez sur Generate

Composez votre commande5

sourceProjectRequis

targetProjectRequis

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-runVous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

Sélectionnez le projet agent comme source et le projet Gateway comme cible.

Options

Options du générateur5 options

sourceProjectRequisstring: Le projet source
targetProjectRequisstring: Le projet cible auquel se connecter
sourceComponentstring: Le composant source depuis lequel se connecter (nom du composant, chemin relatif à la racine du projet source, ou identifiant de générateur). Utilisez '.' pour sélectionner explicitement le projet comme source.
targetComponentstring: Le composant cible auquel se connecter (nom du composant, chemin relatif à la racine du projet cible, ou identifiant de générateur). Utilisez '.' pour sélectionner explicitement le projet comme cible.
preferInstallDependenciesbooleanPar défaut: 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-fetch.ts Framework-agnostic SigV4 / JWT / session-forwarding fetch
    agentcore-transport.ts Shared AgentCore transport plumbing
    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 :

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
Terraform

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.

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 :

Démarrer la gateway locale de la Gateway connectée et chaque serveur MCP attaché
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 nx <agent-name>-dev <project-name>

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

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

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 nx <agent-name>-serve <project-name>

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

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

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.