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

Astuce

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	-	The project to add the Strands Agent to
computeType	string	BedrockAgentCoreRuntime	The type of compute to host your Strands Agent.
name	string	-	The name of your Strands Agent (default: agent)
iacProvider	string	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

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
      • agent-core-mcp-client.ts Factory de client pour se connecter aux serveurs MCP 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

Note

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

Note

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

Note

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 agent = 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 (ou d’autres hébergés sur Bedrock AgentCore Runtime), une factory de client est générée pour vous dans agent-core-mcp-client.ts.

Vous pouvez mettre à jour l’initialisation de votre agent dans agent.ts pour créer des clients MCP et ajouter des outils. L’exemple suivant montre comment effectuer cela avec l’authentification IAM (SigV4) :

agent.ts

import { Agent } from '@strands-agents/sdk';
import { AgentCoreMcpClient } from './agent-core-mcp-client.js';

const mcpClient = AgentCoreMcpClient.withIamAuth({
  agentRuntimeArn: process.env.MCP_AGENTCORE_RUNTIME_ARN!,
  region: process.env.AWS_REGION || 'us-west-2',
  sessionId: 'my-session-id',
});

export const agent = new Agent({
  systemPrompt: '...',
  tools: [mcpClient],
});

Astuce

Si votre serveur MCP cible utilise l’authentification JWT, vous pouvez utiliser la méthode AgentCoreMcpClient.withJwtAuth pour créer le client à la place.

Avec l’exemple d’authentification IAM ci-dessus, nous devons configurer deux choses dans notre infrastructure. Premièrement, nous devons ajouter la variable d’environnement que notre agent consomme pour l’ARN AgentCore Runtime de notre serveur MCP, et deuxièmement, nous devons accorder à notre agent les permissions d’invoquer le serveur MCP. Cela peut être réalisé comme suit :

CDK

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

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

    const agent = new MyProjectAgent(this, 'MyProjectAgent', {
      environmentVariables: {
        MCP_AGENTCORE_RUNTIME_ARN: mcpServer.agentCoreRuntime.agentRuntimeArn,
      },
    });

    mcpServer.agentCoreRuntime.grantInvoke(agent.agentCoreRuntime);
  }
}

Terraform

# MCP Server
module "my_project_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

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

  env = {
    MCP_AGENTCORE_RUNTIME_ARN = module.my_project_mcp_server.agent_core_runtime_arn
  }

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

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 run your-project:agent-serve

yarn

yarn nx run your-project:agent-serve

npm

npx nx run your-project:agent-serve

bun

bunx nx run your-project:agent-serve

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/*',
        ],
      }),
    );
  }
}

Note

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/*"
      ]
    }
  ]
}

Attention

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

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 grantInvoke, 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.agentCoreRuntime.grantInvoke(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 JWT

Ce qui suit démontre comment configurer l’authentification Cognito pour votre agent.

CDK

Pour configurer l’authentification JWT en utilisant Cognito, utilisez la méthode factory RuntimeAuthorizerConfiguration.usingCognito() :

import { MyProjectAgent } from ':my-scope/common-constructs';
import { RuntimeAuthorizerConfiguration } from '@aws-cdk/aws-bedrock-agentcore-alpha';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const userPool = new UserPool(this, 'UserPool');
    const client = userPool.addClient('Client', {
      authFlows: {
        userPassword: true,
      },
    });

    new MyProjectAgent(this, 'MyProjectAgent', {
      authorizerConfiguration: RuntimeAuthorizerConfiguration.usingCognito(
        userPool,
        [client],
      ),
    });
  }
}

Alternativement, pour une authentification JWT personnalisée avec votre propre fournisseur OIDC, utilisez RuntimeAuthorizerConfiguration.usingJWT() :

import { MyProjectAgent } from ':my-scope/common-constructs';
import { RuntimeAuthorizerConfiguration } from '@aws-cdk/aws-bedrock-agentcore-alpha';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent', {
      authorizerConfiguration: RuntimeAuthorizerConfiguration.usingJWT(
        'https://example.com/.well-known/openid-configuration',
        ['client1', 'client2'], // Allowed Client IDs (optional)
        ['audience1'],          // Allowed Audiences (optional)
      ),
    });
  }
}

Terraform

Pour configurer l’authentification JWT, vous pouvez modifier votre module agent pour configurer la variable authorizer_configuration comme suit :

packages/common/terraform/src/app/agents/my-project-agent/my-project-agent.tf

data "aws_region" "current" {}

locals {
  aws_region = data.aws_region.current.id

  # Replace with your user pool and client ids or expose as variables
  user_pool_id = "xxx"
  user_pool_client_ids = ["yyy"]
}

module "agent_core_runtime" {
  source = "../../../core/agent-core"
  agent_runtime_name = "MyProjectAgent"
  docker_image_tag = "my-scope-my-project-agent:latest"
  server_protocol = "HTTP"
  authorizer_configuration = {
    custom_jwt_authorizer = {
      discovery_url = "https://cognito-idp.${local.aws_region}.amazonaws.com/${local.user_pool_id}/.well-known/openid-configuration"
      allowed_clients = local.user_pool_client_ids
    }
  }
  env = var.env
  additional_iam_policy_statements = var.additional_iam_policy_statements
  tags = var.tags
}

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 run <project-name>:bundle

yarn

yarn nx run <project-name>:bundle

npm

npx nx run <project-name>:bundle

bun

bunx nx run <project-name>:bundle

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.

Astuce

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.

Astuce

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

Astuce

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.

Astuce

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

Attention

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

Note

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

Les WebSockets dans le navigateur ne prennent pas en charge la spécification d’en-têtes (autre que Sec-WebSocket-Protocol), et par conséquent la factory de client générée dans client.ts ne peut pas être utilisée dans un navigateur (cela entraînera en fait une erreur de compilation car le constructeur WebSocket n’accepte pas d’en-têtes comme il le fait dans NodeJS).

Authentification JWT / Cognito

Attention

Au moment de la rédaction, Bedrock AgentCore Runtime exige que les jetons JWT soient passés dans l’en-tête Authorization, et par conséquent les navigateurs ne peuvent pas s’authentifier auprès de Bedrock AgentCore Runtime en utilisant l’authentification JWT. Seule l’authentification AWS Signature Version 4 (SigV4) est prise en charge via des URL présignées.

Nous nous efforcerons de mettre à jour cette documentation si la prise en charge est ajoutée à l’avenir.

Authentification IAM

Pour invoquer votre agent depuis un navigateur, vous devez créer une URL WebSocket présignée en utilisant AWS SigV4.

L’exemple ci-dessous montre un flux de bout en bout d’obtention d’informations d’identification, de création d’une URL présignée et d’invocation de l’agent :

import { createTRPCClient, createWSClient, wsLink } from '@trpc/client';
import { AwsClient } from 'aws4fetch';
import { CognitoIdentityClient } from '@aws-sdk/client-cognito-identity';
import { fromCognitoIdentityPool } from '@aws-sdk/credential-provider-cognito-identity';
import type { AppRouter } from './your-agent/router';

// Build a presigned WebSocket URL
async function buildSignedUrl(
  agentRuntimeArn: string,
  idToken: string,
  region: string = 'us-west-2'
): Promise<string> {
  // Get credentials from a Cognito Identity Pool (or other source)
  const credentials = fromCognitoIdentityPool({
    client: new CognitoIdentityClient({ region }),
    identityPoolId: 'us-west-2:xxxxx',
    logins: {
      [`cognito-idp.${region}.amazonaws.com/us-west-2_xxxxx`]: idToken,
    },
  });

  const cognitoIdentity = new CognitoIdentityClient({ credentials });
  const credential = await cognitoIdentity.config.credentials();

  // Create AWS SigV4 client
  const awsClient = new AwsClient({
    ...credential,
    service: 'bedrock-agentcore',
  });

  // Build WebSocket URL from ARN
  const wsUrl = `wss://bedrock-agentcore.${region}.amazonaws.com/runtimes/${agentRuntimeArn.replace(/:/g, '%3A').replace(/\//g, '%2F')}/ws`;

  // Create presigned URL
  const signedRequest = await awsClient.sign(wsUrl, {
    method: 'GET',
    aws: { signQuery: true },
  });

  return signedRequest.url;
}

// Create tRPC client with presigned WebSocket URL
const agentRuntimeArn = 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent';
const idToken = '<your-id-token>';

const wsClient = createWSClient({
  url: async () => buildSignedUrl(agentRuntimeArn, idToken),
});

const trpcClient = createTRPCClient<AppRouter>({
  links: [wsLink({ client: wsClient })],
});

// Invoke the agent
trpcClient.invoke.subscribe({ message: 'what is 1 plus 1?' }, {
  onData: (message) => console.log(message),
});

Astuce

Si vous souhaitez une expérience similaire au générateur de connexion API pour les agents, veuillez +1 ce problème GitHub.