Agent TypeScript Strands

Générez un Strands Agent TypeScript pour créer des agents IA avec des outils, et déployez-le optionnellement sur Amazon Bedrock AgentCore Runtime. 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.

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 Strands Agent

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

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

Prérequis du projet

Utilisez d’abord le générateur ts#project pour créer un projet auquel ajouter votre Strands Agent.

Options

Paramètre	Type	Par défaut	Description
project Requis	string	-	Le projet auquel ajouter l'Agent Strands
computeType	string	BedrockAgentCoreRuntime	Le type de calcul pour héberger votre Agent Strands.
name	string	-	Le nom de votre Agent Strands (par défaut : agent)
auth	string	IAM	La méthode utilisée pour s'authentifier auprès de votre Strands Agent. Choisissez entre IAM (par défaut) ou Cognito.
iacProvider	string	Inherit	Le fournisseur IaC préféré. Par défaut, celui-ci est hérité de votre sélection initiale.

Sortie du générateur

Le générateur ajoutera les fichiers suivants à votre projet TypeScript existant :

• Répertoireyour-project/

  • Répertoiresrc/

    • Répertoireagent/ (ou nom personnalisé si spécifié)

      • index.ts Point d’entrée pour Bedrock AgentCore Runtime
      • 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 computeType 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

Infrastructure

Déploiement serverless

Si vous avez sélectionné None pour computeType, le générateur ne fournira aucune infrastructure as code.

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

• 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

Projet généré

Ce projet est généré avec le générateur ts#project et configure donc les mêmes cibles de build.

Terraform

• 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

Projet généré

Ce projet est généré avec le générateur terraform#project et configure donc les mêmes cibles de build.

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

CDK

• Répertoirepackages/common/constructs/src

  • Répertoireapp

    • Répertoireagents

      • Répertoire<project-name>

        • <project-name>.ts Construct CDK pour déployer votre agent
        • Dockerfile Fichier docker passthrough utilisé par le construct CDK

Terraform

• Répertoirepackages/common/terraform/src

  • Répertoireapp

    • Répertoireagents

      • Répertoire<project-name>

        • <project-name>.tf Module pour déployer votre agent
  • Répertoirecore

    • Répertoireagent-core

      • runtime.tf Module générique pour déployer sur Bedrock AgentCore Runtime

Travailler avec votre Strands Agent

tRPC sur WebSocket

Le Strands 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

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

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

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.

Exécution de votre Strands Agent

Développement local

Le générateur configure une cible nommée <your-agent-name>-serve, qui démarre votre Strands Agent localement pour le développement et les tests.

pnpm

pnpm nx agent-serve your-project

yarn

yarn nx agent-serve your-project

npm

npx nx agent-serve your-project

bun

bunx nx agent-serve your-project

Cette commande 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).

Déploiement de votre Strands Agent sur Bedrock AgentCore Runtime

Infrastructure as Code

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

CDK

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) {
    // Add the agent to your stack
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    // Grant permissions to invoke the relevant models in bedrock
    agent.agentCoreRuntime.addToRolePolicy(
      new PolicyStatement({
        actions: [
          'bedrock:InvokeModel',
          'bedrock:InvokeModelWithResponseStream',
        ],
        // You can scope the below down to the specific models you use
        resources: [
          'arn:aws:bedrock:*:*:foundation-model/*',
          'arn:aws:bedrock:*:*:inference-profile/*',
        ],
      }),
    );
  }
}

Construct CDK Alpha

Ce construct utilise le module @aws-cdk/aws-bedrock-agentcore-alpha.

Terraform

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.

Vous pouvez utiliser ce module terraform dans un projet Terraform :

# 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"

  # Grant permissions to invoke the relevant models in bedrock
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ]
      # You can scope the below down to the specific models you use
      Resource = [
        "arn:aws:bedrock:*:*:foundation-model/*",
        "arn:aws:bedrock:*:*:inference-profile/*"
      ]
    }
  ]
}

Docker requis

Docker est requis pour construire et déployer votre Strands 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 Strands 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 Strands Agent sera sécurisé à l’aide de l’authentification IAM, déployez-le simplement sans aucun argument :

CDK

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);
  }
}

Terraform

# 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"
}

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

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#react-website#auth, ou vous pouvez créer votre propre UserPool et UserPoolClient CDK.

Terraform

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"

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

Fournisseurs OIDC personnalisés

Si vous avez besoin d’une authentification JWT personnalisée avec un fournisseur OIDC non-Cognito, vous pouvez modifier directement le construct CDK ou le module Terraform généré pour votre agent. Notez que le générateur de connexion ne prendra en charge que l’authentification IAM ou Cognito.

Cible Bundle

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

pnpm

pnpm nx bundle <project-name>

yarn

yarn nx bundle <project-name>

npm

npx nx bundle <project-name>

bun

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.

Configuration personnalisée

Vous pouvez ajuster la configuration de Rolldown dans rolldown.config.ts, par exemple si vous avez des dépendances qui reposent sur des chemins de fichiers et ne peuvent pas être regroupées, vous pouvez les ajouter à la liste des modules external.

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 exécute le serveur WebSocket groupé sur le port 8080 conformément au contrat de runtime AgentCore.

Tags d’image Docker

L’image docker est construite en utilisant un tag (par exemple my-scope-my-project-agent:latest), qui est référencé par votre infrastructure CDK ou Terraform, permettant à votre Dockerfile d’être colocalisé avec votre projet Strands Agent.

Une cible docker est également générée qui exécute la construction docker pour tous les agents si vous en avez plusieurs définis.

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 Strands 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 :

scripts/test.ts

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 });

Test rapide

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

pnpm

pnpm tsx scripts/test.ts

yarn

yarn tsx scripts/test.ts

npm

npx tsx scripts/test.ts

bun

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

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,
    });
  }
}

Terraform

# 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"
}

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.

Console du navigateur

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

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

Authentification par en-têtes HTTP

La factory de client utilise des en-têtes HTTP dans la négociation WebSocket pour authentifier les requêtes vers Bedrock AgentCore Runtime. Cela n’est pas possible dans un navigateur, et par conséquent ce client n’est pas adapté aux environnements de navigateur. Reportez-vous à la section “Navigateur / Site web React” ci-dessous pour plus de détails concernant l’invocation depuis un navigateur.

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({ message: 'what is 1 plus 1?' }, {
  onData: (message) => console.log(message),
  onError: (error) => console.error(error),
  onComplete: () => console.log('Done'),
});

Identifiants AWS

Cela utilisera la chaîne de fournisseur d’informations d’identification AWS par défaut pour authentifier les requêtes, donc l’environnement dans lequel ce qui précède est exécuté doit avoir des informations d’identification AWS configurées, avec accès pour invoquer le runtime.

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 Strands 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

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

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

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