Agente TypeScript Strands

Genera un TypeScript Strands Agent per la creazione di agenti AI con strumenti e, facoltativamente, distribuiscilo su Amazon Bedrock AgentCore Runtime. Il generatore utilizza tRPC su WebSocket per sfruttare il supporto di streaming bidirezionale di AgentCore per una comunicazione in tempo reale e type-safe.

Cos’è Strands?

Strands è un framework leggero per la creazione di agenti AI. Le caratteristiche principali includono:

• Leggero e personalizzabile: Un semplice ciclo di agente che non ti ostacola
• Pronto per la produzione: Completa osservabilità, tracciamento e opzioni di distribuzione per la scalabilità
• Agnostico rispetto a modello e provider: Supporta molti modelli diversi da vari provider
• Strumenti guidati dalla community: Potente set di strumenti contribuiti dalla community
• Supporto multi-agente: Tecniche avanzate come team di agenti e agenti autonomi
• Modalità di interazione flessibili: Supporto conversazionale, streaming e non-streaming

Utilizzo

Generare uno Strands Agent

Puoi generare un TypeScript Strands Agent in due modi:

VSCode

1. Installa il Nx Console VSCode Plugin se non l'hai già fatto
2. Apri la console Nx in VSCode
3. Clicca su Generate (UI) nella sezione "Common Nx Commands"
4. Cerca @aws/nx-plugin - ts#strands-agent
5. Compila i parametri richiesti
6. Clicca su 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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

Consiglio

Prima utilizza il generatore ts#project per creare un progetto a cui aggiungere il tuo Strands Agent.

Opzioni

Parametro	Tipo	Predefinito	Descrizione
project Obbligatorio	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.

Output del Generatore

Il generatore aggiungerà i seguenti file al tuo progetto TypeScript esistente:

• Directoryyour-project/

  • Directorysrc/

    • Directoryagent/ (o nome personalizzato se specificato)

      • index.ts Punto di ingresso per Bedrock AgentCore Runtime
      • init.ts Inizializzazione tRPC
      • router.ts Router tRPC con procedure dell’agente
      • agent.ts Definizione principale dell’agente con strumenti di esempio
      • client.ts Client fornito per invocare il tuo agente
      • agent-core-trpc-client.ts Factory del client per connettersi agli agenti su AgentCore Runtime
      • agent-core-mcp-client.ts Factory del client per connettersi ai server MCP su AgentCore Runtime
      • Dockerfile Punto di ingresso per l’hosting del tuo agente (escluso quando computeType è impostato su None)
  • package.json Aggiornato con le dipendenze di Strands
  • project.json Aggiornato con i target di serve dell’agente

Infrastruttura

Nota

Se hai selezionato None per computeType, il generatore non fornirà alcuna infrastruttura come codice.

Poiché questo generatore fornisce infrastruttura come codice basata sul tuo iacProvider selezionato, creerà un progetto in packages/common che include i relativi costrutti CDK o moduli Terraform.

Il progetto comune di infrastruttura come codice è strutturato come segue:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Construct per l’infrastruttura specifica di un progetto/generatore

      • …
    • Directorycore/ Construct generici riutilizzati dai construct in app

      • …
    • index.ts Punto di ingresso che esporta i construct da app
  • project.json Target di build e configurazione del progetto

Nota

Questo progetto è generato utilizzando il ts#project generator e quindi configura gli stessi target di build.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Moduli Terraform per l’infrastruttura specifica di un progetto/generatore

      • …
    • Directorycore/ Moduli generici riutilizzati dai moduli in app

      • …
  • project.json Target di build e configurazione del progetto

Nota

Questo progetto è generato utilizzando il terraform#project generator e quindi configura gli stessi target di build.

Per distribuire il tuo Strands Agent, vengono generati i seguenti file:

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directoryagents

      • Directory<project-name>

        • <project-name>.ts Costrutto CDK per distribuire il tuo agente
        • Dockerfile File docker passthrough utilizzato dal costrutto CDK

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directoryagents

      • Directory<project-name>

        • <project-name>.tf Modulo per distribuire il tuo agente
  • Directorycore

    • Directoryagent-core

      • runtime.tf Modulo generico per la distribuzione su Bedrock AgentCore Runtime

Lavorare con il Tuo Strands Agent

tRPC su WebSocket

Il TypeScript Strands Agent utilizza tRPC su WebSocket, sfruttando il supporto di streaming bidirezionale di AgentCore per abilitare la comunicazione in tempo reale e type-safe tra i client e il tuo agente.

Poiché tRPC supporta le procedure Query, Mutation e Subscription su WebSocket, puoi definire un numero qualsiasi di procedure. Per impostazione predefinita, viene definita per te una singola procedura di subscription denominata invoke in router.ts.

Aggiungere Strumenti

Gli strumenti sono funzioni che l’agente AI può chiamare per eseguire azioni. Puoi aggiungere nuovi strumenti nel file 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],
});

Il framework Strands gestisce automaticamente:

• Validazione dell’input utilizzando schemi Zod
• Generazione dello schema JSON per la chiamata degli strumenti
• Gestione degli errori e formattazione delle risposte

Configurazione del Modello

Per impostazione predefinita, gli agenti Strands utilizzano Claude 4 Sonnet, ma puoi facilmente passare da un provider di modelli all’altro:

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?');

Consulta la documentazione di Strands sui provider di modelli per ulteriori opzioni di configurazione.

Consumare Server MCP

Puoi aggiungere strumenti dai server MCP al tuo agente Strands.

Per consumare i Server MCP che hai creato utilizzando i generatori py#mcp-server o ts#mcp-server (o altri ospitati su Bedrock AgentCore Runtime), viene generata per te una factory del client in agent-core-mcp-client.ts.

Puoi aggiornare l’inizializzazione del tuo agente in agent.ts per creare client MCP e aggiungere strumenti. L’esempio seguente mostra come eseguire questa operazione con l’autenticazione 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],
});

Consiglio

Se il tuo server MCP di destinazione utilizza l’autenticazione JWT, puoi utilizzare il metodo AgentCoreMcpClient.withJwtAuth per creare il client invece.

Con l’esempio di autenticazione IAM sopra, dobbiamo configurare due cose nella nostra infrastruttura. In primo luogo, dobbiamo aggiungere la variabile d’ambiente che il nostro agente sta consumando per l’ARN di AgentCore Runtime del nostro server MCP e, in secondo luogo, dobbiamo concedere al nostro agente le autorizzazioni per invocare il server MCP. Questo può essere ottenuto come segue:

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

Altro

Per una guida più approfondita sulla scrittura di agenti Strands, fai riferimento alla documentazione di Strands.

Eseguire il Tuo Strands Agent

Sviluppo Locale

Il generatore configura un target denominato <your-agent-name>-serve, che avvia il tuo Strands Agent localmente per lo sviluppo e il testing.

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

Questo comando utilizza tsx --watch per riavviare automaticamente il server quando i file cambiano. L’agente sarà disponibile su http://localhost:8081 (o la porta assegnata se hai più agenti).

Distribuire il Tuo Strands Agent su Bedrock AgentCore Runtime

Infrastructure as Code

Se hai selezionato BedrockAgentCoreRuntime per computeType, viene generata l’infrastruttura CDK o Terraform rilevante che puoi utilizzare per distribuire il tuo Strands Agent su Amazon Bedrock AgentCore Runtime.

CDK

Viene generato un costrutto CDK per il tuo agent, denominato in base al name che hai scelto durante l’esecuzione del generatore, o <ProjectName>Agent per impostazione predefinita.

Puoi utilizzare questo costrutto CDK in un’applicazione 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/*',
        ],
      }),
    );
  }
}

Nota

Questo costrutto utilizza il modulo @aws-cdk/aws-bedrock-agentcore-alpha.

Terraform

Viene generato un modulo Terraform per te, denominato in base al name che hai scelto durante l’esecuzione del generatore, o <ProjectName>-agent per impostazione predefinita.

Puoi utilizzare questo modulo terraform in un progetto 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/*"
      ]
    }
  ]
}

Attenzione

Docker è richiesto per compilare e distribuire il tuo Strands Agent. Assicurati di aver installato e avviato Docker per evitare errori come:

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

Autenticazione

IAM

Per impostazione predefinita, il tuo Strands Agent sarà protetto utilizzando l’autenticazione IAM, semplicemente distribuiscilo senza alcun argomento:

CDK

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

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

Puoi concedere l’accesso per invocare il tuo agent su Bedrock AgentCore Runtime utilizzando il metodo grantInvoke, ad esempio:

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

Per concedere l’accesso per invocare il tuo agent, dovrai aggiungere una policy come la seguente, facendo riferimento all’output 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}/*"
  ]
}

Autenticazione Cognito JWT

Quanto segue dimostra come configurare l’autenticazione Cognito per il tuo agent.

CDK

Per configurare l’autenticazione JWT utilizzando Cognito, utilizza il metodo 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],
      ),
    });
  }
}

In alternativa, per l’autenticazione JWT personalizzata con il tuo provider OIDC, utilizza 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

Per configurare l’autenticazione JWT, puoi modificare il modulo del tuo agent per configurare la variabile authorizer_configuration come segue:

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
}

Target Bundle

Il generatore configura automaticamente un target bundle che utilizza Rolldown per creare un pacchetto di distribuzione:

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 configurazione di Rolldown si trova in rolldown.config.ts, con un’entry per bundle da generare. Rolldown gestisce la creazione di più bundle in parallelo se definiti.

Consiglio

Puoi modificare la configurazione di Rolldown in rolldown.config.ts, ad esempio se hai dipendenze che richiedono percorsi file specifici e non possono essere incluse nel bundle, puoi aggiungerle alla lista dei moduli external.

Il target bundle utilizza index.ts come punto di ingresso per il server WebSocket da ospitare su Bedrock AgentCore Runtime.

Target Docker

Il generatore configura un target <your-agent-name>-docker che esegue il server WebSocket in bundle sulla porta 8080 come da contratto runtime di AgentCore.

Consiglio

L’immagine docker viene creata utilizzando un tag (ad esempio my-scope-my-project-agent:latest), a cui fa riferimento la tua infrastruttura CDK o Terraform, consentendo al tuo Dockerfile di essere co-localizzato con il tuo progetto Strands Agent.

Viene generato anche un target docker che esegue la build docker per tutti gli agenti se ne hai definiti più di uno.

Osservabilità

Il tuo agente è automaticamente configurato con l’osservabilità utilizzando AWS Distro for Open Telemetry (ADOT), configurando l’auto-instrumentazione nel tuo Dockerfile.

Puoi trovare le tracce nella Console AWS di CloudWatch, selezionando “GenAI Observability” nel menu. Nota che affinché le tracce vengano popolate dovrai abilitare Transaction Search.

Per maggiori dettagli, fai riferimento alla documentazione di AgentCore sull’osservabilità.

Invocare il Tuo Strands Agent

La comunicazione dell’agente viene trasmessa tramite tRPC su WebSocket. Pertanto, si consiglia di utilizzare la factory del client type-safe generata in client.ts.

Invocare il Server Locale

Puoi invocare un agente in esecuzione localmente utilizzando il metodo factory .local dalla factory del client.

Puoi, ad esempio, creare un file denominato scripts/test.ts nel tuo workspace che importa il 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 });

Consiglio

Esegui con tsx come modo rapido per testare il tuo agente.

pnpm

pnpm tsx scripts/test.ts

yarn

yarn tsx scripts/test.ts

npm

npx tsx scripts/test.ts

bun

bunx tsx scripts/test.ts

Invocare l’Agente Distribuito

Per invocare il tuo Agent distribuito su Bedrock AgentCore Runtime, puoi inviare una richiesta POST all’endpoint dataplane di Bedrock AgentCore Runtime con il tuo ARN runtime codificato in URL.

Puoi ottenere l’ARN runtime dalla tua infrastruttura come segue:

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 avrà il seguente formato: arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>.

Puoi quindi codificare in URL l’ARN sostituendo : con %3A e / con %2F.

Consiglio

Questo è semplice in una console del browser o in un REPL Node utilizzando il metodo integrato encodeURIComponent:

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

L’URL dataplane di Bedrock AgentCore Runtime per invocare l’agent è il seguente:

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

Il modo esatto per invocare questo URL dipende dal metodo di autenticazione utilizzato.

NodeJS

Il file client.ts generato include una factory del client type-safe che può essere utilizzata per invocare il tuo agente distribuito.

Attenzione

La factory del client utilizza le intestazioni HTTP nell’handshake WebSocket per autenticare le richieste a Bedrock AgentCore Runtime. Questo non è possibile in un browser e pertanto questo client non è adatto per ambienti browser. Fai riferimento alla sezione “Browser” di seguito per i dettagli sull’invocazione da un browser.

Autenticazione IAM

Puoi invocare il tuo agente distribuito passando il suo ARN al metodo 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'),
});

Nota

Questo utilizzerà la catena di provider di credenziali AWS predefinita per autenticare le richieste, quindi l’ambiente in cui viene eseguito quanto sopra deve avere le credenziali AWS configurate, con accesso per invocare il runtime.

Autenticazione JWT / Cognito

Utilizza il metodo factory withJwtAuth per autenticarti con il token di accesso 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,
});

L’accessTokenProvider deve restituire il token utilizzato per autenticare la richiesta. Puoi, ad esempio, ottenere un token all’interno di questo metodo per garantire che le credenziali aggiornate vengano riutilizzate quando tRPC riavvia una connessione WebSocket. Il seguente esempio dimostra l’utilizzo dell’AWS SDK per ottenere il token da 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!;
  },
});

Browser

I WebSocket nel browser non supportano la specifica delle intestazioni (diverse da Sec-WebSocket-Protocol) e pertanto la factory del client generata in client.ts non può essere utilizzata in un browser (questo comporterà effettivamente un errore di compilazione poiché il costruttore WebSocket non accetta intestazioni come fa in NodeJS).

Autenticazione JWT / Cognito

Attenzione

Al momento della scrittura, Bedrock AgentCore Runtime richiede che i token JWT vengano passati nell’intestazione Authorization e pertanto i browser non possono autenticarsi con Bedrock AgentCore Runtime utilizzando l’autenticazione JWT. È supportata solo l’autenticazione AWS Signature Version 4 (SigV4) tramite URL prefirmati.

Ci impegneremo ad aggiornare questa documentazione qualora il supporto venga aggiunto in futuro.

Autenticazione IAM

Per invocare il tuo agente da un browser, devi creare un URL WebSocket prefirmato utilizzando AWS SigV4.

L’esempio seguente mostra un flusso end-to-end per ottenere le credenziali, creare un URL prefirmato e invocare l’agente:

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

Consiglio

Se desideri un’esperienza simile al generatore di connessione API per gli agenti, metti +1 a questa issue di GitHub.