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

Prerequisito del progetto

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	-	Il progetto a cui aggiungere lo Strands Agent
computeType	string	BedrockAgentCoreRuntime	Il tipo di compute per ospitare il tuo Strands Agent.
name	string	-	Il nome del tuo Strands Agent (predefinito: agent)
auth	string	IAM	Il metodo utilizzato per autenticarsi con il tuo Strands Agent. Scegli tra IAM (predefinito) o Cognito.
iacProvider	string	Inherit	Il provider IaC preferito. Per impostazione predefinita viene ereditato dalla selezione iniziale.

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

Deploy serverless

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

Progetto generato

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

Progetto generato

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 getAgent = async (sessionId: string) => {
  return 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 puoi utilizzare il generatore connection.

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 - connection
5. Compila i parametri richiesti
6. Clicca su 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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

Fai riferimento alla guida del generatore connection per i dettagli su come viene configurata la connessione.

Per altri server MCP, consulta la Documentazione di Strands.

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

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

Costrutto CDK Alpha

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

Docker richiesto

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

Il generatore fornisce un’opzione auth per configurare l’autenticazione per il tuo Strands Agent. Puoi scegliere tra l’autenticazione IAM (predefinita) o Cognito durante la generazione del tuo agent.

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 grantInvokeAccess, 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.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"
}

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

Quando selezioni l’autenticazione Cognito, il generatore configura l’agent per utilizzare Cognito per l’autenticazione.

CDK

Il costrutto generato accetta una prop identity che configura l’autenticazione 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,
    });
  }
}

Il costrutto UserIdentity può essere generato utilizzando il generatore ts#react-website#auth, oppure puoi creare il tuo UserPool e UserPoolClient CDK.

Terraform

Il modulo generato accetta le variabili user_pool_id e user_pool_client_ids per l’autenticazione 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]
}

Provider OIDC personalizzati

Se hai bisogno di autenticazione JWT personalizzata con un provider OIDC non-Cognito, puoi modificare direttamente il costrutto CDK o il modulo Terraform generato per il tuo agent. Nota che il generatore di connessioni supporterà solo l’autenticazione IAM o Cognito.

Target Bundle

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

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

Configurazione personalizzata

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.

Tag immagine Docker

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

Test rapido

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.

Console del browser

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.

Autenticazione tramite header HTTP

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 / Sito Web React” 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'),
});

Credenziali AWS

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 / Sito Web React

Per invocare il tuo Strands Agent da un sito web React, puoi utilizzare il generatore connection, che configura automaticamente un client tRPC WebSocket con l’autenticazione corretta (IAM o Cognito).

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 - connection
5. Compila i parametri richiesti
6. Clicca su 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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

Fai riferimento alla guida del generatore connection per i dettagli su come viene configurata la connessione.