Agente Strands de TypeScript

Genera un TypeScript Strands Agent para construir agentes de IA con herramientas, y opcionalmente despliégalo en Amazon Bedrock AgentCore Runtime. El generador utiliza tRPC sobre WebSocket para aprovechar el soporte de streaming bidireccional de AgentCore para comunicación en tiempo real y con seguridad de tipos.

¿Qué es Strands?

Strands es un framework ligero para construir agentes de IA. Las características clave incluyen:

• Ligero y personalizable: Bucle de agente simple que no se interpone en tu camino
• Listo para producción: Observabilidad completa, rastreo y opciones de despliegue para escalar
• Agnóstico de modelo y proveedor: Soporta muchos modelos diferentes de varios proveedores
• Herramientas impulsadas por la comunidad: Conjunto poderoso de herramientas contribuidas por la comunidad
• Soporte multi-agente: Técnicas avanzadas como equipos de agentes y agentes autónomos
• Modos de interacción flexibles: Soporte conversacional, streaming y no-streaming

Uso

Generar un Strands Agent

Puedes generar un TypeScript Strands Agent de dos maneras:

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - ts#strands-agent
5. Complete los parámetros requeridos
6. Haga clic en 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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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

Requisito previo del proyecto

Primero usa el generador ts#project para crear un proyecto al que agregar tu Strands Agent.

Opciones

Parámetro	Tipo	Predeterminado	Descripción
project Requerido	string	-	El proyecto al que agregar el Strands Agent
computeType	string	BedrockAgentCoreRuntime	El tipo de cómputo para alojar tu Strands Agent.
name	string	-	El nombre de tu Strands Agent (predeterminado: agent)
auth	string	IAM	El método utilizado para autenticar con tu Strands Agent. Elige entre IAM (predeterminado) o Cognito.
iacProvider	string	Inherit	El proveedor de IaC preferido. Por defecto, se hereda de tu selección inicial.

Salida del Generador

El generador agregará los siguientes archivos a tu proyecto TypeScript existente:

• Directorioyour-project/

  • Directoriosrc/

    • Directorioagent/ (o nombre personalizado si se especifica)

      • index.ts Punto de entrada para Bedrock AgentCore Runtime
      • init.ts Inicialización de tRPC
      • router.ts Router de tRPC con procedimientos del agente
      • agent.ts Definición principal del agente con herramientas de ejemplo
      • client.ts Cliente provisto para invocar tu agente
      • agent-core-trpc-client.ts Fábrica de cliente para conectar a agentes en AgentCore Runtime
      • Dockerfile Punto de entrada para alojar tu agente (excluido cuando computeType está establecido en None)
  • package.json Actualizado con dependencias de Strands
  • project.json Actualizado con targets de servicio del agente

Infraestructura

Despliegue serverless

Si seleccionaste None para computeType, el generador no proveerá ninguna infraestructura como código.

Dado que este generador proporciona infraestructura como código basada en tu proveedor de iacProvider seleccionado, creará un proyecto en packages/common que incluye los constructos CDK o módulos de Terraform correspondientes.

El proyecto común de infraestructura como código tiene la siguiente estructura:

CDK

• Directoriopackages/common/constructs

  • Directoriosrc

    • Directorioapp/ Constructos para infraestructura específica de un proyecto/generador

      • …
    • Directoriocore/ Constructos genéricos reutilizados por los constructos en app

      • …
    • index.ts Punto de entrada que exporta los constructos de app
  • project.json Objetivos de compilación y configuración del proyecto

Proyecto generado

Este proyecto se genera utilizando el ts#project generator y por lo tanto configura los mismos objetivos de compilación.

Terraform

• Directoriopackages/common/terraform

  • Directoriosrc

    • Directorioapp/ Módulos de Terraform para infraestructura específica de un proyecto/generador

      • …
    • Directoriocore/ Módulos genéricos reutilizados por los módulos en app

      • …
  • project.json Objetivos de compilación y configuración del proyecto

Proyecto generado

Este proyecto se genera utilizando el terraform#project generator y por lo tanto configura los mismos objetivos de compilación.

Para desplegar tu Strands Agent, se generan los siguientes archivos:

CDK

• Directoriopackages/common/constructs/src

  • Directorioapp

    • Directorioagents

      • Directorio<project-name>

        • <project-name>.ts Constructo CDK para desplegar tu agente
        • Dockerfile Archivo docker de paso utilizado por el constructo CDK

Terraform

• Directoriopackages/common/terraform/src

  • Directorioapp

    • Directorioagents

      • Directorio<project-name>

        • <project-name>.tf Módulo para desplegar tu agente
  • Directoriocore

    • Directorioagent-core

      • runtime.tf Módulo genérico para desplegar en Bedrock AgentCore Runtime

Trabajar con tu Strands Agent

tRPC sobre WebSocket

El TypeScript Strands Agent utiliza tRPC sobre WebSocket, aprovechando el soporte de streaming bidireccional de AgentCore para habilitar comunicación en tiempo real y con seguridad de tipos entre clientes y tu agente.

Dado que tRPC soporta procedimientos Query, Mutation y Subscription sobre WebSocket, puedes definir cualquier número de procedimientos. Por defecto, se define un único procedimiento de suscripción llamado invoke en router.ts.

Agregar Herramientas

Las herramientas son funciones que el agente de IA puede llamar para realizar acciones. Puedes agregar nuevas herramientas en el archivo 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],
  });
};

El framework Strands maneja automáticamente:

• Validación de entrada usando esquemas Zod
• Generación de esquema JSON para llamadas a herramientas
• Manejo de errores y formateo de respuestas

Configuración de Modelo

Por defecto, los agentes Strands usan Claude 4 Sonnet, pero puedes cambiar fácilmente entre proveedores de modelos:

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 documentación de Strands sobre proveedores de modelos para más opciones de configuración.

Consumir Servidores MCP

Puedes agregar herramientas desde servidores MCP a tu agente Strands.

Para consumir Servidores MCP que has creado usando los generadores py#mcp-server o ts#mcp-server puedes hacer uso del generador connection.

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - connection
5. Complete los parámetros requeridos
6. Haga clic en 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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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

Consulta la guía del generador connection para detalles sobre cómo se configura la conexión.

Para otros servidores MCP, por favor consulta la Documentación de Strands.

Más

Para una guía más profunda sobre cómo escribir agentes Strands, consulta la documentación de Strands.

Ejecutar tu Strands Agent

Desarrollo Local

El generador configura un target llamado <your-agent-name>-serve, que inicia tu Strands Agent localmente para desarrollo y pruebas.

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

Este comando usa tsx --watch para reiniciar automáticamente el servidor cuando cambian los archivos. El agente estará disponible en http://localhost:8081 (o el puerto asignado si tienes múltiples agentes).

Desplegar tu Strands Agent en Bedrock AgentCore Runtime

Infraestructura como Código

Si seleccionaste BedrockAgentCoreRuntime para computeType, se genera la infraestructura CDK o Terraform relevante que puedes usar para desplegar tu Strands Agent en Amazon Bedrock AgentCore Runtime.

CDK

Se genera una construcción CDK para tu agente, nombrada según el name que elegiste al ejecutar el generador, o <ProjectName>Agent por defecto.

Puedes usar esta construcción CDK en una aplicación 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/*',
        ],
      }),
    );
  }
}

Constructo CDK Alpha

Esta construcción utiliza el módulo @aws-cdk/aws-bedrock-agentcore-alpha.

Terraform

Se genera un módulo Terraform para ti, nombrado según el name que elegiste al ejecutar el generador, o <ProjectName>-agent por defecto.

Puedes usar este módulo terraform en un proyecto 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 requerido

Docker es necesario para construir y desplegar tu Strands Agent. Asegúrate de haber instalado e iniciado Docker para evitar errores como:

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

Autenticación

El generador proporciona una opción auth para configurar la autenticación de tu Strands Agent. Puedes elegir entre autenticación IAM (predeterminada) o Cognito al generar tu agente.

IAM

Por defecto, tu Strands Agent estará protegido usando autenticación IAM, simplemente despliégalo sin ningún argumento:

CDK

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

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

Puedes otorgar acceso para invocar tu agente en Bedrock AgentCore Runtime usando el método grantInvokeAccess, por ejemplo:

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

Para otorgar acceso para invocar tu agente, necesitarás agregar una política como la siguiente, haciendo referencia a la salida 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}/*"
  ]
}

Autenticación Cognito

Cuando seleccionas autenticación Cognito, el generador configura el agente para usar Cognito para la autenticación.

CDK

La construcción generada acepta una propiedad identity que configura la autenticación 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,
    });
  }
}

La construcción UserIdentity puede generarse usando el generador ts#react-website#auth, o puedes crear tu propio UserPool y UserPoolClient de CDK.

Terraform

El módulo generado acepta las variables user_pool_id y user_pool_client_ids para la autenticación 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]
}

Proveedores OIDC personalizados

Si requieres autenticación JWT personalizada con un proveedor OIDC que no sea Cognito, puedes modificar directamente la construcción CDK o el módulo Terraform generado para tu agente. Ten en cuenta que el generador de conexión solo admitirá autenticación IAM o Cognito.

Target Bundle

El generador configura automáticamente un objetivo bundle que utiliza Rolldown para crear un paquete de despliegue:

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 configuración de Rolldown se encuentra en rolldown.config.ts, con una entrada por cada bundle a generar. Rolldown gestiona la creación de múltiples bundles en paralelo si están definidos.

Configuración personalizada

Puedes ajustar la configuración de Rolldown en rolldown.config.ts, por ejemplo si tienes dependencias que requieren rutas de archivo específicas y no pueden incluirse en el bundle, puedes agregarlas a la lista de módulos external.

El target bundle usa index.ts como punto de entrada para el servidor WebSocket para alojar en Bedrock AgentCore Runtime.

Target Docker

El generador configura un target <your-agent-name>-docker que ejecuta el servidor WebSocket empaquetado en el puerto 8080 según el contrato de runtime de AgentCore.

Etiquetas de imagen Docker

La imagen docker se construye usando una etiqueta (por ejemplo my-scope-my-project-agent:latest), que es referenciada por tu infraestructura CDK o Terraform, permitiendo que tu Dockerfile esté co-ubicado con tu proyecto Strands Agent.

También se genera un target docker que ejecuta la construcción docker para todos los agentes si tienes múltiples definidos.

Observabilidad

Tu agente está configurado automáticamente con observabilidad usando el AWS Distro for Open Telemetry (ADOT), configurando auto-instrumentación en tu Dockerfile.

Puedes encontrar trazas en la Consola AWS CloudWatch, seleccionando “GenAI Observability” en el menú. Ten en cuenta que para que las trazas se completen necesitarás habilitar Transaction Search.

Para más detalles, consulta la documentación de AgentCore sobre observabilidad.

Invocar tu Strands Agent

La comunicación del agente se transmite vía tRPC sobre WebSocket. Como tal, se recomienda usar la fábrica de cliente con seguridad de tipos generada en client.ts.

Invocar el Servidor Local

Puedes invocar un agente ejecutándose localmente usando el método de fábrica .local de la fábrica de cliente.

Puedes, por ejemplo, crear un archivo llamado scripts/test.ts en tu workspace que importe el cliente:

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

Prueba rápida

Ejecuta con tsx como una forma rápida de probar tu 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

Invocar el Agente Desplegado

Para invocar tu Agente desplegado en Bedrock AgentCore Runtime, puedes enviar una solicitud POST al endpoint del plano de datos de Bedrock AgentCore Runtime con tu ARN de runtime codificado en URL.

Puedes obtener el ARN de runtime desde tu infraestructura de la siguiente manera:

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
}

El ARN tendrá el siguiente formato: arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>.

Luego puedes codificar el ARN en URL reemplazando : con %3A y / con %2F.

Consola del navegador

Esto es sencillo en una consola de navegador o Node REPL usando el método integrado encodeURIComponent:

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

La URL del plano de datos de Bedrock AgentCore Runtime para invocar el agente es la siguiente:

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

La forma exacta de invocar esta URL depende del método de autenticación utilizado.

NodeJS

El archivo client.ts generado incluye una fábrica de cliente con seguridad de tipos que puede usarse para invocar tu agente desplegado.

Autenticación por cabeceras HTTP

La fábrica de cliente usa encabezados HTTP en el handshake de WebSocket para autenticar solicitudes a Bedrock AgentCore Runtime. Esto no es posible en un navegador, y por lo tanto este cliente no es adecuado para entornos de navegador. Consulta la sección “Browser / React Website” a continuación para detalles sobre la invocación desde un navegador.

Autenticación IAM

Puedes invocar tu agente desplegado pasando su ARN al método de fábrica 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'),
});

Credenciales de AWS

Esto usará la cadena de proveedores de credenciales AWS predeterminada para autenticar solicitudes, por lo que el entorno en el que se ejecuta lo anterior debe tener credenciales AWS configuradas, con acceso para invocar el runtime.

Autenticación JWT / Cognito

Usa el método de fábrica withJwtAuth para autenticar con el token de acceso 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,
});

El accessTokenProvider debe devolver el token usado para autenticar la solicitud. Puedes, por ejemplo, obtener un token dentro de este método para asegurar que las credenciales frescas se reutilicen cuando tRPC reinicie una conexión WebSocket. Lo siguiente demuestra usar el AWS SDK para obtener el token de 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 / React Website

Para invocar tu Strands Agent desde un sitio web React, puedes hacer uso del generador connection, que configura automáticamente un cliente tRPC WebSocket con la autenticación correcta (IAM o Cognito).

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - connection
5. Complete los parámetros requeridos
6. Haga clic en 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

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

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

Consulta la guía del generador connection para detalles sobre cómo se configura la conexión.