Agent TypeScript Strands

Générez un Agent TypeScript pour créer des agents IA avec des outils, et déployez-le optionnellement sur Amazon Bedrock AgentCore Runtime. Par défaut, le générateur utilise tRPC sur WebSocket pour tirer parti de la prise en charge du streaming bidirectionnel d’AgentCore pour une communication en temps réel et type-safe. Alternativement, vous pouvez choisir le protocole Agent-to-Agent (A2A) pour l’interopérabilité avec d’autres agents compatibles A2A, ou le protocole AG-UI pour une intégration frontend directe via CopilotKit.

Qu’est-ce que Strands ?

Strands est un framework léger pour créer des agents IA. Les fonctionnalités clés incluent :

Léger et personnalisable : Boucle d’agent simple qui ne vous gêne pas
Prêt pour la production : Observabilité complète, traçage et options de déploiement à grande échelle
Agnostique au modèle et au fournisseur : Prend en charge de nombreux modèles de différents fournisseurs
Outils communautaires : Ensemble puissant d’outils contributés par la communauté
Prise en charge multi-agents : Techniques avancées comme les équipes d’agents et les agents autonomes
Modes d’interaction flexibles : Prise en charge conversationnelle, en streaming et sans streaming

Utilisation

Générer un Agent

Vous pouvez générer un Agent TypeScript de deux manières :

VSCode
CLI

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

pnpm nx g @aws/nx-plugin:ts#agent

yarn nx g @aws/nx-plugin:ts#agent

npx nx g @aws/nx-plugin:ts#agent

bunx nx g @aws/nx-plugin:ts#agent

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

pnpm nx g @aws/nx-plugin:ts#agent --dry-run

yarn nx g @aws/nx-plugin:ts#agent --dry-run

npx nx g @aws/nx-plugin:ts#agent --dry-run

bunx nx g @aws/nx-plugin:ts#agent --dry-run

Options

Paramètre	Type	Par défaut	Description
project Requis	string	-	Le projet auquel ajouter l'Agent
framework	strands	strands	Le SDK d'agent à utiliser.
name	string	-	Le nom de votre Agent (par défaut : agent)
auth	iam \| cognito	iam	La méthode utilisée pour s'authentifier auprès de votre Agent. Applicable uniquement lorsque infra est défini (ignoré lorsque infra est none).
protocol	http \| a2a \| ag-ui	http	Le protocole serveur pour votre Agent. HTTP expose un serveur tRPC/WebSocket. A2A expose un serveur de protocole Agent-to-Agent. AG-UI expose un serveur de protocole AG-UI pour l'intégration frontend directe avec CopilotKit.
iac	inherit \| cdk \| terraform	inherit	Le fournisseur IaC préféré. Par défaut, cela est hérité de votre sélection initiale.
infra	agentcore \| none	agentcore	Le type d'infrastructure pour héberger votre Agent.
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 ajoutera les fichiers suivants à votre projet TypeScript existant. Les fichiers générés dépendent du protocol choisi :

Protocole HTTP (par défaut)

Répertoireyour-project/
- Répertoiresrc/
  - Répertoireagent/ (ou nom personnalisé si spécifié)
    index.ts Point d’entrée pour Bedrock AgentCore Runtime (serveur tRPC/WebSocket)
    init.ts Initialisation tRPC
    router.ts Routeur tRPC avec procédures d’agent
    agent.ts Définition principale de l’agent avec exemples d’outils
    client.ts Client fourni pour invoquer votre agent
    agent-core-trpc-client.ts Factory de client pour se connecter aux agents sur AgentCore Runtime
    Dockerfile Point d’entrée pour héberger votre agent (exclu lorsque infra est défini sur None)
- package.json Mis à jour avec les dépendances Strands
- project.json Mis à jour avec les cibles de service de l’agent

Protocole A2A

Le point d’entrée utilise le Strands A2A Express Server au lieu de tRPC :

Répertoireyour-project/
- Répertoiresrc/
  - Répertoireagent/ (ou nom personnalisé si spécifié)
    index.ts Point d’entrée du serveur A2A Express
    agent.ts Définition principale de l’agent avec exemples d’outils
    Dockerfile Point d’entrée pour héberger votre agent (exclu lorsque infra est défini sur None)
- package.json Mis à jour avec les dépendances Strands et Express
- project.json Mis à jour avec les cibles de service de l’agent

Protocole AG-UI

Le point d’entrée utilise @ag-ui/aws-strands pour exposer l’agent via le protocole AG-UI (SSE sur POST), compatible avec CopilotKit :

Répertoireyour-project/
- Répertoiresrc/
  - Répertoireagent/ (ou nom personnalisé si spécifié)
    index.ts Point d’entrée du serveur AG-UI (Express + SSE)
    agent.ts Définition principale de l’agent avec exemples d’outils
    Dockerfile Point d’entrée pour héberger votre agent (exclu lorsque infra est défini sur None)
- package.json Mis à jour avec les dépendances Strands et AG-UI
- project.json Mis à jour avec les cibles de service de l’agent

Infrastructure

Ce générateur fournit de l’infrastructure as code basée sur votre iac 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

Pour déployer votre Agent, les fichiers suivants sont générés :

CDK
Terraform

Répertoirepackages/common/constructs/src
- Répertoireapp
  - Répertoireagents
    Répertoire<project-name>
    <project-name>.ts Construct CDK pour déployer votre agent

Si vous avez sélectionné None pour infra, aucun construct CDK ou module Terraform n’est généré — le Agent ne peut être exécuté que localement. L’option auth est ignorée dans ce mode car il n’y a pas de point de terminaison hébergé à authentifier.

Lorsqu’il est déployé sur Bedrock AgentCore Runtime, l’agent est construit dans une image de conteneur, poussé vers Amazon ECR et exécuté dans AgentCore Runtime. Les clients invoquent le point de terminaison du plan de données AgentCore Runtime, qui transmet les requêtes à votre agent. L’agent appelle Amazon Bedrock pour l’inférence de modèle et peut invoquer des outils, des serveurs MCP ou des API en aval.

Avec infra: None, aucune infrastructure AWS n’est générée. L’agent s’exécute en tant que processus local et appelle Amazon Bedrock pour l’inférence de modèle.

Travailler avec votre Agent

Protocole

Le protocole serveur de votre agent détermine comment il communique. Vous pouvez choisir entre :

HTTP (par défaut) : Utilise tRPC sur WebSocket pour une communication en temps réel et type-safe. Idéal pour les intégrations client personnalisées et un contrôle fin de l’API de l’agent.
A2A : Utilise le protocole Agent-to-Agent (A2A) pour une communication inter-agents standardisée. Idéal lorsque votre agent doit être découvrable et invocable par d’autres agents compatibles A2A.
AG-UI : Utilise le protocole AG-UI (SSE sur POST) via @ag-ui/aws-strands pour une intégration frontend directe avec CopilotKit. Idéal lorsque vous souhaitez une interface de chat riche avec streaming, visualisation des appels d’outils et gestion d’état.

Le protocole est défini dans l’infrastructure CDK/Terraform, et le code de l’application est généré en conséquence.

tRPC sur WebSocket (protocole HTTP)

Le Agent TypeScript utilise tRPC sur WebSocket, tirant parti de la prise en charge du streaming bidirectionnel d’AgentCore pour permettre une communication en temps réel et type-safe entre les clients et votre agent.

Comme tRPC prend en charge les procédures Query, Mutation et Subscription sur WebSocket, vous pouvez définir autant de procédures que vous le souhaitez. Par défaut, une seule procédure de souscription nommée invoke est définie pour vous dans router.ts.

Ajout d’outils

Les outils sont des fonctions que l’agent IA peut appeler pour effectuer des actions. Vous pouvez ajouter de nouveaux outils dans le fichier agent.ts :

import { Agent, tool } from '@strands-agents/sdk';
import { z } from 'zod';

const letterCounter = tool({
  name: 'letter_counter',
  description: 'Count occurrences of a specific letter in a word',
  inputSchema: z.object({
    word: z.string().describe('The input word to search in'),
    letter: z.string().length(1).describe('The specific letter to count'),
  }),
  callback: (input) => {
    const { word, letter } = input;
    const count = word.toLowerCase().split(letter.toLowerCase()).length - 1;
    return `The letter '${letter}' appears ${count} time(s) in '${word}'`;
  },
});

// Add tools to your agent
export const getAgent = async (sessionId: string) => {
  return new Agent({
    systemPrompt: 'You are a helpful assistant with access to various tools.',
    tools: [letterCounter],
  });
};

Le framework Strands gère automatiquement :

La validation des entrées à l’aide de schémas Zod
La génération de schémas JSON pour l’appel d’outils
La gestion des erreurs et le formatage des réponses

Configuration du modèle

Par défaut, les agents Strands utilisent Claude 4 Sonnet, mais vous pouvez facilement basculer entre les fournisseurs de modèles :

import { Agent } from '@strands-agents/sdk';
import { BedrockModel } from '@strands-agents/sdk/models/bedrock';
import { OpenAIModel } from '@strands-agents/sdk/models/openai';

// Use Bedrock
const bedrockModel = new BedrockModel({
  modelId: 'anthropic.claude-sonnet-4-20250514-v1:0',
});
let agent = new Agent({ model: bedrockModel });
let response = await agent.invoke('What can you help me with?');

// Alternatively, use OpenAI by just switching model provider
const openaiModel = new OpenAIModel({
  apiKey: process.env.OPENAI_API_KEY,
  modelId: 'gpt-4o',
});
agent = new Agent({ model: openaiModel });
response = await agent.invoke('What can you help me with?');

Consultez la documentation Strands sur les fournisseurs de modèles pour plus d’options de configuration.

Consommation de serveurs MCP

Vous pouvez ajouter des outils depuis des serveurs MCP à votre agent Strands.

Pour consommer des serveurs MCP que vous avez créés à l’aide des générateurs py#mcp-server ou ts#mcp-server, vous pouvez utiliser le générateur connection.

VSCode
CLI

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

Consultez le guide du générateur connection pour plus de détails sur la façon dont la connexion est configurée.

Pour d’autres serveurs MCP, veuillez consulter la Documentation Strands.

Plus

Pour un guide plus approfondi sur l’écriture d’agents Strands, consultez la documentation Strands.

Serveur A2A (protocole A2A)

Le fichier index.ts généré monte le Strands A2A Express Server sur une application Express afin que l’agent généré expose les points de terminaison du protocole A2A aux côtés d’un contrôle de santé /ping. Lorsqu’il est déployé sur AgentCore, le point d’entrée résout l’ARN public du runtime depuis AppConfig et l’annonce dans la carte de l’agent.

La plupart des utilisateurs n’auront pas besoin de modifier ce fichier — éditez agent.ts pour changer les outils ou le prompt système. Les agents A2A écoutent sur le port 9000 (vs 8080 pour HTTP), pour lequel le Dockerfile généré et l’infrastructure sont déjà configurés.

Serveur AG-UI (protocole AG-UI)

Le fichier index.ts généré encapsule votre Agent Strands dans un StrandsAgent @ag-ui/aws-strands et crée une application Express via createStrandsApp(). L’application résultante expose un seul point de terminaison POST qui diffuse des événements AG-UI via Server-Sent Events (SSE), ainsi que /ping pour le contrôle de santé du runtime AgentCore.

Les agents AG-UI sont conçus pour être consommés directement par un frontend. Utilisez le générateur connection pour connecter votre site web React à l’agent avec un fournisseur CopilotKit et un client AG-UI HttpAgent.

La plupart des utilisateurs n’auront pas besoin de modifier index.ts — éditez agent.ts pour changer les outils ou le prompt système. Les agents AG-UI écoutent sur le port 8080 (identique à HTTP), pour lequel le Dockerfile généré et l’infrastructure sont déjà configurés.

Exécution de votre Agent

Développement local

Pour exécuter votre Agent (et tout ce qui y est connecté) localement, utilisez la cible dev du projet :

pnpm nx dev your-project

yarn nx dev your-project

npx nx dev your-project

bunx nx dev your-project

Si vous avez ajouté plusieurs composants à votre projet (agents, serveurs MCP, etc.), cela les démarre tous. Pour exécuter uniquement cet agent, ciblez sa cible <your-agent-name>-dev :

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

Cela utilise tsx --watch pour redémarrer automatiquement le serveur lorsque les fichiers changent. L’agent sera disponible à http://localhost:8081 (ou le port attribué si vous avez plusieurs agents).

Discuter avec votre Agent

Le générateur configure une cible Nx <your-agent-name>-chat qui vous place dans un chat terminal interactif avec votre agent.

La cible chat s’exécute de manière autonome. Par défaut, elle se connecte à votre agent en cours d’exécution localement, donc démarrez d’abord la cible <your-agent-name>-dev de l’agent (dans un terminal séparé) :

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

Ensuite, dans un autre terminal, démarrez le chat :

pnpm nx run your-project:agent-chat

yarn nx run your-project:agent-chat

npx nx run your-project:agent-chat

bunx nx run your-project:agent-chat

Le générateur émet un scripts/<your-agent-name>/chat.ts pour chaque protocole. Vous pouvez le personnaliser au fur et à mesure que vous faites évoluer la forme d’entrée de l’agent. Il se connecte à l’agent local par défaut, ou à votre agent déployé lorsque RUNTIME_CONFIG_APP_ID est défini (voir Discuter avec votre agent déployé ci-dessous).

Chat with your deployed agent

Pour discuter avec votre agent déployé sur Bedrock AgentCore, définissez la variable d’environnement RUNTIME_CONFIG_APP_ID sur l’identifiant d’application AppConfig du déploiement (sortie en tant que RuntimeConfigApplicationId par la pile déployée). Le script de chat résout l’ARN d’exécution de votre agent à partir de la configuration d’exécution et se connecte au point de terminaison déployé :

IAM
Cognito

Pour les agents authentifiés par IAM, les requêtes sont signées avec SigV4 en utilisant vos informations d’identification AWS par défaut. Assurez-vous que l’environnement dispose d’informations d’identification AWS avec l’autorisation d’invoquer le runtime :

RUNTIME_CONFIG_APP_ID=<app-id> pnpm nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> yarn nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> npx nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> bunx nx run your-project:agent-chat

Pour les agents authentifiés par Cognito, fournissez un jeton d’accès Cognito via la variable d’environnement AGENT_ACCESS_TOKEN, qui est envoyé en tant que jeton bearer :

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> pnpm nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> yarn nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> npx nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> bunx nx run your-project:agent-chat

Vous pouvez obtenir un jeton d’accès en utilisant la commande cognito-idp admin-initiate-auth de l’AWS CLI, par exemple :

aws cognito-idp admin-initiate-auth \
  --user-pool-id <user-pool-id> \
  --client-id <user-pool-client-id> \
  --auth-flow ADMIN_NO_SRP_AUTH \
  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
  --query 'AuthenticationResult.AccessToken' \
  --output text

Déploiement de votre Agent sur Bedrock AgentCore Runtime

Infrastructure as Code

Si vous avez sélectionné agentcore pour infra, l’infrastructure CDK ou Terraform correspondante est générée, que vous pouvez utiliser pour déployer votre Agent sur Amazon Bedrock AgentCore Runtime.

CDK
Terraform

Un construct CDK est généré pour votre agent, nommé en fonction du name que vous avez choisi lors de l’exécution du générateur, ou <ProjectName>Agent par défaut.

Vous pouvez utiliser ce construct CDK dans une application CDK :

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

Un module Terraform est généré pour vous, nommé en fonction du name que vous avez choisi lors de l’exécution du générateur, ou <ProjectName>-agent par défaut.

Transmettez les sorties du module partagé runtime_config_appconfig au module agent :

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

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

Docker est requis pour construire et déployer votre Agent. Assurez-vous d’avoir installé et lancé Docker pour éviter des erreurs telles que :

ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.

Authentification

Le générateur fournit une option auth pour configurer l’authentification de votre Agent. Vous pouvez choisir entre l’authentification IAM (par défaut) ou Cognito lors de la génération de votre agent.

IAM

Par défaut, votre Agent sera sécurisé à l’aide de l’authentification IAM, déployez-le simplement sans aucun argument :

CDK
Terraform

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

Vous pouvez accorder l’accès pour invoquer votre agent sur Bedrock AgentCore Runtime en utilisant la méthode grantInvokeAccess, par exemple :

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');
    const lambdaFunction = new Function(this, ...);

    agent.grantInvokeAccess(lambdaFunction);
  }
}

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

Pour accorder l’accès pour invoquer votre agent, vous devrez ajouter une politique telle que la suivante, en référençant la sortie module.my_project_agent.agent_core_runtime_arn :

{
  Effect = "Allow"
  Action = [
    "bedrock-agentcore:InvokeAgentRuntime"
  ]
  Resource = [
    module.my_project_agent.agent_core_runtime_arn,
    "${module.my_project_agent.agent_core_runtime_arn}/*"
  ]
}

Authentification Cognito

Lorsque vous sélectionnez l’authentification Cognito, le générateur configure l’agent pour utiliser Cognito pour l’authentification.

CDK
Terraform

Le construct généré accepte une prop identity qui configure l’authentification Cognito :

import { MyProjectAgent, UserIdentity } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const identity = new UserIdentity(this, 'Identity');

    new MyProjectAgent(this, 'MyProjectAgent', {
      identity,
    });
  }
}

Le construct UserIdentity peut être généré en utilisant le générateur ts#website#auth, ou vous pouvez créer votre propre UserPool et UserPoolClient CDK.

Le module généré accepte les variables user_pool_id et user_pool_client_ids pour l’authentification Cognito :

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

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

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

Cible Bundle

Le générateur configure automatiquement une cible bundle qui utilise Rolldown pour créer un package de déploiement :

pnpm nx bundle <project-name>

yarn nx bundle <project-name>

npx nx bundle <project-name>

bunx nx bundle <project-name>

La configuration de Rolldown se trouve dans rolldown.config.ts, avec une entrée par bundle à générer. Rolldown gère la création de plusieurs bundles en parallèle si définis.

La cible bundle utilise index.ts comme point d’entrée pour le serveur WebSocket à héberger sur Bedrock AgentCore Runtime.

Cible Docker

Le générateur configure une cible <your-agent-name>-docker qui copie le Dockerfile depuis le répertoire source de votre agent dans le répertoire de sortie du bundle. Cela colocalise le Dockerfile avec les artefacts groupés, permettant à CDK de construire l’image Docker directement en utilisant AgentRuntimeArtifact.fromAsset.

Une cible docker est également générée qui prépare le contexte docker pour tous les agents si vous en avez plusieurs définis.

Analyse d’image

L’image Docker construite pour ce projet peut être analysée pour détecter les vulnérabilités en utilisant Trivy, exécuté à partir de l’image Trivy hébergée sur ECR.

Une cible trivy est ajoutée à votre projet qui analyse l’image construite et se termine avec un code non-zéro si une vulnérabilité de gravité HIGH ou CRITICAL est trouvée. Le Dockerfile généré utilise une image de base sans vulnérabilité corrigeable connue de ces gravités au moment de la génération, et met à niveau les outils intégrés (tels que npm) pour le maintenir ainsi.

L’analyse utilise le même moteur de conteneur que votre construction d’image (docker ou finch), donc aucun outillage supplémentaire n’est requis. Étant donné que l’analyse n’est réexécutée que lorsque l’image change, une image inchangée n’est pas réanalysée. Le script racine trivy fourni analyse chaque image dans l’espace de travail :

pnpm trivy

yarn trivy

npm run trivy

bun trivy

Suppression des résultats Trivy

Il peut y avoir des cas où vous souhaitez supprimer une vulnérabilité spécifique, par exemple lorsqu’aucun correctif n’est encore disponible et que vous avez évalué le risque comme acceptable.

Ajoutez l’ID de vulnérabilité (un par ligne) au fichier .trivyignore à la racine de votre projet (c’est-à-dire à côté de votre project.json) :

# node-tar arbitrary file write - not exploitable in our usage
CVE-2024-XXXXX

Pour plus de détails sur le filtrage des résultats, consultez la documentation de filtrage Trivy.

Observabilité

Votre agent est automatiquement configuré avec l’observabilité en utilisant AWS Distro for Open Telemetry (ADOT), en configurant l’auto-instrumentation dans votre Dockerfile.

Vous pouvez trouver les traces dans la console AWS CloudWatch, en sélectionnant “GenAI Observability” dans le menu. Notez que pour que les traces soient remplies, vous devrez activer Transaction Search.

Pour plus de détails, consultez la documentation AgentCore sur l’observabilité.

Invocation de votre Agent

La communication de l’agent est transmise via tRPC sur WebSocket. En tant que tel, il est recommandé d’utiliser la factory de client type-safe générée dans client.ts.

Invoquer le serveur local

Vous pouvez invoquer un agent en cours d’exécution localement en utilisant la méthode factory .local de la factory de client.

Vous pouvez, par exemple, créer un fichier nommé scripts/test.ts dans votre espace de travail qui importe le client :

import { AgentClient } from '../packages/<project>/src/agent/client.js';

const client = AgentClient.local({ url: 'http://localhost:8081/ws' });

client.invoke.subscribe({ message: 'what is 1 plus 1?' }, { onData: console.log });

Exécutez avec tsx comme moyen rapide de tester votre agent.

pnpm tsx scripts/test.ts

yarn tsx scripts/test.ts

npx tsx scripts/test.ts

bunx tsx scripts/test.ts

Invoquer l’agent déployé

Pour invoquer votre Agent déployé sur Bedrock AgentCore Runtime, vous pouvez envoyer une requête POST au point de terminaison du plan de données Bedrock AgentCore Runtime avec votre ARN d’exécution encodé en URL.

Vous pouvez obtenir l’ARN d’exécution depuis votre infrastructure comme suit :

CDK
Terraform

import { CfnOutput } from 'aws-cdk-lib';
import { MyProjectAgent } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    new CfnOutput(this, 'AgentArn', {
      value: agent.agentCoreRuntime.agentRuntimeArn,
    });
  }
}

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

output "agent_arn" {
  value = module.my_project_agent.agent_core_runtime_arn
}

L’ARN aura le format suivant : arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>.

Vous pouvez ensuite encoder l’ARN en URL en remplaçant : par %3A et / par %2F.

Ceci est simple dans une console de navigateur ou un REPL Node en utilisant la méthode intégrée encodeURIComponent :

encodeURIComponent('arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>')

L’URL du plan de données Bedrock AgentCore Runtime pour invoquer l’agent est la suivante :

https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations

Votre infrastructure peut également générer directement l’URL d’invocation complète, avec l’encodage de l’ARN géré pour vous :

CDK
Terraform

new CfnOutput(this, 'AgentUrl', {
  value: agent.invocationUrl,
});

output "agent_url" {
  value = module.my_project_agent.invocation_url
}

La manière exacte d’invoquer cette URL dépend de la méthode d’authentification utilisée.

NodeJS

Le fichier client.ts généré inclut une factory de client type-safe qui peut être utilisée pour invoquer votre agent déployé.

IAM
Cognito

Authentification IAM

Vous pouvez invoquer votre agent déployé en passant son ARN à la méthode factory withIamAuth :

import { AgentClient } from './agent/client.js';

const client = AgentClient.withIamAuth({
  agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
});

client.invoke.subscribe({ prompt: 'what is 1 plus 1?' }, {
  onData: (message) => console.log(message),
  onError: (error) => console.error(error),
  onComplete: () => console.log('Done'),
});

Authentification JWT / Cognito

Utilisez la méthode factory withJwtAuth pour vous authentifier avec le jeton d’accès JWT / Cognito.

const client = AgentClient.withJwtAuth({
  agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
  accessTokenProvider: async () => `<access-token>`,
});

client.invoke.subscribe({ message: 'what is 1 plus 1?' }, {
  onData: console.log,
});

Le accessTokenProvider doit retourner le jeton utilisé pour authentifier la requête. Vous pouvez, par exemple, obtenir un jeton dans cette méthode pour vous assurer que les informations d’identification fraîches sont réutilisées lorsque tRPC redémarre une connexion WebSocket. Ce qui suit démontre l’utilisation du SDK AWS pour obtenir le jeton depuis Cognito :

import { CognitoIdentityProvider } from "@aws-sdk/client-cognito-identity-provider";

const cognito = new CognitoIdentityProvider();

const jwtClient = AgentClient.withJwtAuth({
  agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
  accessTokenProvider: async () => {
    const response = await cognito.adminInitiateAuth({
      UserPoolId: '<user-pool-id>',
      ClientId: '<user-pool-client-id>',
      AuthFlow: 'ADMIN_NO_SRP_AUTH',
      AuthParameters: {
        USERNAME: '<username>',
        PASSWORD: '<password>',
      },
    });
    return response.AuthenticationResult!.AccessToken!;
  },
});

Navigateur / Site web React

Pour invoquer votre Agent depuis un site web React, vous pouvez utiliser le générateur connection, qui configure automatiquement un client tRPC WebSocket avec l’authentification correcte (IAM ou Cognito).

VSCode
CLI

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

Consultez le guide du générateur connection pour plus de détails sur la façon dont la connexion est configurée.

Invocation d’un agent A2A en tant qu’outil

Pour déléguer du travail de cet agent à un agent A2A distant (soit TypeScript soit Python), utilisez le générateur connection. Il fournit un client authentifié SigV4 pour l’agent cible et transforme par AST le fichier agent.ts de cet agent pour enregistrer l’agent A2A distant en tant qu’tool Strands.

VSCode
CLI

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

Consultez le guide du générateur connection pour plus de détails sur la façon dont la connexion est configurée.

Invocation d’un agent AG-UI

Pour invoquer votre agent AG-UI depuis un site web React, utilisez le générateur connection, qui configure un client CopilotKit configuré pour votre agent déployé avec l’authentification correcte (IAM ou Cognito).

VSCode
CLI

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

Consultez le guide du générateur connection pour plus de détails sur la façon dont la connexion est configurée.

Sécurisation de votre agent

Les agents agissent sur des entrées non fiables et peuvent déclencher des actions réelles via leurs outils, il est donc important de considérer la sécurité dès le départ. Les pratiques suivantes s’appliquent à l’agent généré.

Traiter les entrées et sorties du modèle comme non fiables

Les prompts peuvent contenir des instructions adverses (injection de prompt), et la sortie du modèle est non déterministe — ni l’un ni l’autre ne doivent être considérés comme fiables dans une logique sensible à la sécurité :

Définissez des schémas d’entrée stricts pour vos outils, comme dans l’outil d’exemple généré. Contraignez les valeurs à ce dont l’outil a réellement besoin (énumérations, limites de longueur, plages numériques) plutôt que d’accepter des chaînes de caractères libres.
Ne passez jamais la sortie du modèle directement dans des commandes shell, des requêtes SQL, une évaluation de code ou du HTML rendu sans validation ou encodage.
Appliquez des vérifications d’autorisation dans vos outils et services en aval — ne comptez pas sur le prompt système pour empêcher le modèle d’abuser d’un outil auquel il a accès.

Les guides Ingénierie des prompts et IA responsable de Strands expliquent comment rédiger des prompts système robustes et soucieux de la sécurité.

Limiter strictement les permissions des outils

Accordez au rôle IAM de l’agent uniquement les permissions dont ses outils ont besoin. Les constructs CDK et modules Terraform fournis exposent des méthodes grant* et des politiques limitées à cet effet — par exemple, accorder à un agent l’accès pour invoquer une API spécifique plutôt que d’attacher des politiques gérées larges. Lorsqu’un outil agit au nom d’un utilisateur, préférez autoriser l’action en utilisant l’identité de l’utilisateur appelant (transmise via le contexte de la requête) plutôt que les permissions ambiantes propres à l’agent.

Fournir un interrupteur d’urgence

Étant donné que le comportement du modèle peut changer de manière inattendue, prévoyez de désactiver ou de remplacer rapidement le modèle sans modification de code :

Lisez l’ID du modèle à partir de la configuration (par exemple une variable d’environnement MODEL_ID) afin que les opérateurs puissent basculer ou revenir à un modèle différent en mettant à jour la configuration.
Placez l’agent derrière un feature flag afin que sa fonctionnalité IA puisse être désactivée entièrement. Lorsqu’il est désactivé, renvoyez un message générique plutôt qu’une erreur, et assurez-vous que le reste de votre application se dégrade gracieusement.

Documentez comment activer ces contrôles dans votre manuel opérationnel.

Protéger les données sensibles

Évitez de journaliser les prompts et les complétions, qui peuvent contenir des données utilisateur. Le hook de journalisation des erreurs du modèle de l’agent généré journalise uniquement les métadonnées d’erreur, pas le contenu de la conversation — conservez cette propriété lors de l’ajout de votre propre journalisation.
Renvoyez des messages d’erreur génériques aux utilisateurs ; journalisez les erreurs détaillées côté serveur.
Isolez l’état de conversation entre les utilisateurs et les sessions, et autorisez l’accès à toutes les données de session persistées.
Expurgez les informations personnellement identifiables (PII) des prompts et des sorties — soit avec un filtre d’informations sensibles Bedrock Guardrail (ci-dessous), soit, pour les agents Strands, avec les approches du guide PII Redaction.

Amazon Bedrock Guardrails

Amazon Bedrock Guardrails fournissent des filtres de contenu configurables, des sujets interdits et des filtres d’informations sensibles (PII) qui sont évalués sur les entrées et sorties du modèle. Vous pouvez attacher un guardrail au modèle utilisé par l’agent généré :

import { Agent } from '@strands-agents/sdk';
import { BedrockModel } from '@strands-agents/sdk/models/bedrock';

const model = new BedrockModel({
  modelId: process.env.MODEL_ID,
  guardrailConfig: {
    guardrailIdentifier: process.env.GUARDRAIL_ID!,
    guardrailVersion: process.env.GUARDRAIL_VERSION ?? 'DRAFT',
  },
});

const agent = new Agent({ model, /* ... */ });

Consultez le guide Guardrails de Strands pour plus de détails.

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 :

React vers TypeScript AgentAppeler un TypeScript Agent depuis un site React

React vers AG-UI AgentAppeler un Agent exposant le protocole AG-UI depuis un site React via CopilotKit

TypeScript Agent vers MCPConnecter un TypeScript Agent à un serveur MCP

TypeScript Agent vers A2A AgentConnecter un TypeScript Agent à un agent A2A distant

Python Agent vers A2A AgentConnecter un Python Agent à un agent A2A distant

TypeScript Agent vers Base de données relationnelleConnecter un TypeScript Agent à une base de données relationnelle Aurora

TypeScript Agent vers TypeScript DynamoDBConnecter un TypeScript Agent à une table DynamoDB

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