TypeScript Strands Agent

Generate a TypeScript Strands Agent for building AI agents with tools, and optionally deploy it to Amazon Bedrock AgentCore Runtime. The generator uses tRPC over WebSocket to leverage AgentCore’s bidirectional streaming support for real-time, type-safe communication.

What is Strands?

Strands is a lightweight framework for building AI agents. Key features include:

• Lightweight and customizable: Simple agent loop that gets out of your way
• Production ready: Full observability, tracing, and deployment options for scale
• Model and provider agnostic: Supports many different models from various providers
• Community-driven tools: Powerful set of community-contributed tools
• Multi-agent support: Advanced techniques like agent teams and autonomous agents
• Flexible interaction modes: Conversational, streaming, and non-streaming support

Usage

Generate a Strands Agent

You can generate a TypeScript Strands Agent in two ways:

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - ts#strands-agent
5. Fill in the required parameters
6. Click 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

You can also perform a dry-run to see what files would be changed

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

Project Prerequisite

First use the ts#project generator to create a project to add your Strands Agent to.

Options

Parameter	Type	Default	Description
project Required	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)
auth	string	IAM	The method used to authenticate with your Strands Agent. Choose between IAM (default) or Cognito.
iacProvider	string	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

Generator Output

The generator will add the following files to your existing TypeScript project:

• Directoryyour-project/

  • Directorysrc/

    • Directoryagent/ (or custom name if specified)

      • index.ts Entry point for Bedrock AgentCore Runtime
      • init.ts tRPC initialization
      • router.ts tRPC router with agent procedures
      • agent.ts Main agent definition with sample tools
      • client.ts Vended client for invoking your agent
      • agent-core-trpc-client.ts Client factory for connecting to agents on AgentCore Runtime
      • Dockerfile Entry point for hosting your agent (excluded when computeType is set to None)
  • package.json Updated with Strands dependencies
  • project.json Updated with agent serve targets

Infrastructure

Serverless Deployment

If you selected None for computeType, the generator will not vend any infrastructure as code.

Since this generator vends infrastructure as code based on your chosen iacProvider, it will create a project in packages/common which includes the relevant CDK constructs or Terraform modules.

The common infrastructure as code project is structured as follows:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructs for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Generated Project

This project is generated using the ts#project generator and therefore configures the same build targets.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Generated Project

This project is generated using the terraform#project generator and therefore configures the same build targets.

For deploying your Strands Agent, the following files are generated:

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directoryagents

      • Directory<project-name>

        • <project-name>.ts CDK construct for deploying your agent
        • Dockerfile Passthrough docker file used by the CDK construct

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directoryagents

      • Directory<project-name>

        • <project-name>.tf Module for deploying your agent
  • Directorycore

    • Directoryagent-core

      • runtime.tf Generic module for deploying to Bedrock AgentCore Runtime

Working with Your Strands Agent

tRPC over WebSocket

The TypeScript Strands Agent uses tRPC over WebSocket, leveraging AgentCore’s bidirectional streaming support to enable real-time, type-safe communication between clients and your agent.

Since tRPC supports Query, Mutation and Subscription procedures over WebSocket, you can define any number of procedures. By default, a single subscription procedure named invoke is defined for you in router.ts.

Adding Tools

Tools are functions that the AI agent can call to perform actions. You can add new tools in the agent.ts file:

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

The Strands framework automatically handles:

• Input validation using Zod schemas
• JSON schema generation for tool calling
• Error handling and response formatting

Model Configuration

By default, Strands agents use Claude 4 Sonnet, but you can easily switch between model providers:

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

See the Strands documentation on model providers for more configuration options.

Consuming MCP Servers

You can add tools from MCP servers to your Strands agent.

For consuming MCP Servers which you have created using the py#mcp-server or ts#mcp-server generators you can make use of the connection generator.

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - connection
5. Fill in the required parameters
6. Click 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

You can also perform a dry-run to see what files would be changed

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

Refer to the connection generator guide for details about how the connection is set up.

For other MCP servers, please refer to the Strands Documentation.

More

For a more in-depth guide to writing Strands agents, refer to the Strands documentation.

Running Your Strands Agent

Local Development

The generator configures a target named <your-agent-name>-serve, which starts your Strands Agent locally for development and 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

This command uses tsx --watch to automatically restart the server when files change. The agent will be available at http://localhost:8081 (or the assigned port if you have multiple agents).

Deploying Your Strands Agent to Bedrock AgentCore Runtime

Infrastructure as Code

If you selected BedrockAgentCoreRuntime for computeType, the relevant CDK or Terraform infrastructure is generated which you can use to deploy your Strands Agent to Amazon Bedrock AgentCore Runtime.

CDK

A CDK construct is generated for your agent, named based on the name you chose when running the generator, or <ProjectName>Agent by default.

You can use this CDK construct in a CDK application:

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

Alpha CDK Construct

This construct uses the @aws-cdk/aws-bedrock-agentcore-alpha module.

Terraform

A Terraform module is generated for you, named based on the name you chose when running the generator, or <ProjectName>-agent by default.

You can use this terraform module in a Terraform project:

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

Docker is required to build and deploy your Strands Agent. Make sure you have installed and launched Docker to avoid errors such as:

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

Authentication

The generator provides an auth option to configure authentication for your Strands Agent. You can choose between IAM (default) or Cognito authentication when generating your agent.

IAM

By default, your Strands Agent will be secured using IAM authentication, simply deploy it without any arguments:

CDK

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

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

You can grant access to invoke your agent on Bedrock AgentCore Runtime using the grantInvokeAccess method, for example:

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

To grant access to invoke your agent, you will need to add a policy such as the following, referencing the module.my_project_agent.agent_core_runtime_arn output:

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

Cognito Authentication

When you select Cognito authentication, the generator configures the agent to use Cognito for authentication.

CDK

The generated construct accepts an identity prop which configures Cognito authentication:

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

The UserIdentity construct can be generated using the ts#react-website#auth generator, or you can create your own CDK UserPool and UserPoolClient.

Terraform

The generated module accepts user_pool_id and user_pool_client_ids variables for Cognito authentication:

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

Custom OIDC Providers

If you require custom JWT authentication with a non-Cognito OIDC provider, you can modify the generated CDK construct or Terraform module for your agent directly. Note that the connection generator will only support IAM or Cognito authentication.

Bundle Target

The generator automatically configures a bundle target which uses Rolldown to create a deployment package:

pnpm

pnpm nx bundle <project-name>

yarn

yarn nx bundle <project-name>

npm

npx nx bundle <project-name>

bun

bunx nx bundle <project-name>

Rolldown configuration can be found in rolldown.config.ts, with an entry per bundle to generate. Rolldown manages creating multiple bundles in parallel if defined.

Custom Configuration

You can adjust the configuration for Rolldown in rolldown.config.ts, for example if you have dependencies which rely on file paths and cannot be bundled, you can add them to the list of external modules.

The bundle target uses index.ts as the entrypoint for the WebSocket server to host on Bedrock AgentCore Runtime.

Docker Target

The generator configures a <your-agent-name>-docker target which runs the bundled WebSocket server on port 8080 as per the AgentCore runtime contract.

Docker Image Tags

The docker image is built using a tag (for example my-scope-my-project-agent:latest), which is referenced by your CDK or Terraform infrastructure, allowing for your Dockerfile to be co-located with your Strands Agent project.

A docker target is also generated which runs the docker build for all agents if you have multiple defined.

Observability

Your agent is automatically configured with observability using the AWS Distro for Open Telemetry (ADOT), by configuring auto-instrumentation in your Dockerfile.

You can find traces in the CloudWatch AWS Console, by selecting “GenAI Observability” in the menu. Note that for traces to be populated you will need to enable Transaction Search.

For more details, refer to the AgentCore documentation on observability.

Invoking your Strands Agent

Agent communication is transmitted via tRPC over WebSocket. As such, it’s recommended to use the generated type-safe client factory in client.ts.

Invoke the Local Server

You can invoke a locally running agent using the .local factory method from the client factory.

You can, for example create a file named scripts/test.ts in your workspace which imports the 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 });

Quick Testing

Run with tsx as a quick way to test out your 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

Invoke the Deployed Agent

To invoke your Agent deployed to Bedrock AgentCore Runtime, you can send a POST request to the Bedrock AgentCore Runtime dataplane endpoint with your URL-encoded runtime ARN.

You can obtain the runtime ARN from your infrastructure as follows:

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
}

The ARN will have the following format: arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>.

You can then URL-encode the ARN by replacing : with %3A and / with %2F.

Browser Console

This is straightforward in a browser console or Node REPL using the built in encodeURIComponent method:

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

The Bedrock AgentCore Runtime dataplane URL for invoking the agent is as follows:

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

The exact way to invoke this URL depends upon the authentication method used.

NodeJS

The generated client.ts file includes a type-safe client factory which can be used to invoke your deployed agent.

HTTP Header Authentication

The client factory uses HTTP headers in the WebSocket handshake to authenticate requests to Bedrock AgentCore Runtime. This is not possible in a browser, and therefore this client is not suitable for browser environments. Refer to the below “Browser” section for details regarding invocation from a browser.

IAM Authentication

You can invoke your deployed agent by passing its ARN to the withIamAuth factory method:

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

AWS Credentials

This will use the default AWS credential provider chain to authenticate requests, so the environment in which the above is run must have AWS credentials configured, with access to invoke the runtime.

JWT / Cognito Authentication

Use the withJwtAuth factory method to authenticate with the JWT / Cognito access token.

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

The accessTokenProvider must return the token used to authenticate the request. You can, for example, obtain a token within this method to ensure that fresh credentials are reused when tRPC restarts a WebSocket connection. The below demonstrates using the AWS SDK to obtain the token from 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

For invoking your Strands Agent from a React website, you can make use of the connection generator, which automatically sets up a tRPC WebSocket client with the correct authentication (IAM or Cognito).

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - connection
5. Fill in the required parameters
6. Click 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

You can also perform a dry-run to see what files would be changed

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

Refer to the connection generator guide for details about how the connection is set up.