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 locale.

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

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

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

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

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

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

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

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

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 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 Résolution ARN/URL indépendante du framework
    agentcore-gateway-mcp-transport.ts Transport MCP Gateway indépendant du framework
    agentcore-gateway-mcp-client-strands.ts Client MCP Strands pour la Gateway déployée
  - Répertoireapp/
    <gateway-kebab>-client-strands.ts Wrapper client Strands par Gateway
  - index.ts Ré-exporte le client Gateway

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 dépendre 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 (SERVE_LOCAL non défini), le client pointe vers le point de terminaison MCP de la Gateway et s’authentifie avec SigV4. Lorsque SERVE_LOCAL=true, il pointe vers la gateway locale démarrée par la cible serve-local du projet Gateway, donc 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 la construction CDK générée, 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
resource "aws_iam_policy" "agent_invoke_gateway" {
  name = "AgentInvokeGatewayPolicy"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect   = "Allow"
      Action   = "bedrock-agentcore:InvokeGateway"
      Resource = module.my_gateway.gateway_arn
    }]
  })
}

resource "aws_iam_role_policy_attachment" "agent_invoke_gateway" {
  role       = module.my_agent.agent_core_runtime_role_arn
  policy_arn = aws_iam_policy.agent_invoke_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 (par exemple, pour tester les politiques Cedar), utilisez la cible serve de l’agent. Sans SERVE_LOCAL défini, le client résout l’URL de la Gateway déployée depuis 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 d’un agent et des noms d’action Cedar que vous référencez entre les exécutions locales et déployées. oyées.