Skip to content
@aws/nx-plugin
Blog

TypeScript Agent

Generate a TypeScript Strands Agent for building AI agents with tools, and optionally deploy it to Amazon Bedrock AgentCore Runtime. By default, the generator uses tRPC over WebSocket to leverage AgentCore’s bidirectional streaming support for real-time, type-safe communication. Alternatively, you can choose the Agent-to-Agent (A2A) protocol for interoperability with other A2A-compatible agents, or the AG-UI protocol for direct frontend integration via CopilotKit.

What is Strands?

Section titled “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

Section titled “Usage”

Generate an Agent

Section titled “Generate an Agent”

You can generate a TypeScript Agent in two ways:

Run this generator@aws/nx-plugin:ts#agent

pnpm nx g @aws/nx-plugin:ts#agent
Build your command9

Required

infra = agentcore | agentcore-ecr

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

Options

Section titled “Options”
Generator Options9 options
projectRequiredstring

The project to add the Agent to

frameworkenumDefault: strands

The agent SDK to use.

strands
authenuminfra = agentcore | agentcore-ecrDefault: iam

The method used to authenticate with your Agent. Only applicable when infra is set (ignored when infra is none).

iamcognito
protocolenumDefault: http

The server protocol for your Agent. HTTP exposes a tRPC/WebSocket server. A2A exposes an Agent-to-Agent protocol server. AG-UI exposes an AG-UI protocol server for direct frontend integration with CopilotKit.

httpa2aag-ui
iacenumDefault: inherit

The preferred IaC provider. By default this is inherited from your initial selection.

inheritcdkterraform
infraenumDefault: agentcore

The type of infrastructure to host your Agent. agentcore deploys your code as a zip to an AgentCore managed runtime for the fastest build and deploy cycle. agentcore-ecr builds and hosts a container image instead, for OS-level control or an established container pipeline.

agentcoreagentcore-ecrnone
sessionenumDefault: s3

The storage used to persist session for your Agent.

s3in-memory
namestring

The name of your Agent (default: agent)

preferInstallDependenciesbooleanDefault: true

Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

Generator Output

Section titled “Generator Output”

The generator will add the following files to your existing TypeScript project. The files generated depend on the chosen protocol:

protocol = http

HTTP Protocol (default)

Section titled “HTTP Protocol (default)”
  • Directoryyour-project/
    • Directorysrc/
      • Directoryagent/ (or custom name if specified)
        • index.ts Entry point for Bedrock AgentCore Runtime (tRPC/WebSocket server)
        • init.ts tRPC initialization
        • router.ts tRPC router with agent procedures
        • agent.ts Main agent definition with sample tools
        • session.ts Resolves the SessionManager used to persist conversation state
        • Directoryschema/
          • z-async-iterable.ts Zod schema for the router’s streamed responses
        • client.ts Vended client for invoking your agent
        • agent-core-trpc-client.ts Client factory for connecting to agents on AgentCore Runtime
        • Dockerfile Container image definition (only when infra is agentcore-ecr)
    • package.json Updated with Strands dependencies
    • project.json Updated with agent serve targets
protocol = a2a

A2A Protocol

Section titled “A2A Protocol”

The entry point uses the Strands A2A Express Server instead of tRPC:

  • Directoryyour-project/
    • Directorysrc/
      • Directoryagent/ (or custom name if specified)
        • index.ts A2A Express server entry point
        • agent.ts Main agent definition with sample tools
        • session.ts Resolves the SessionManager used to persist conversation state
        • Directorymiddleware/
          • session-id-middleware.ts Binds the inbound AgentCore session ID for the request
        • Dockerfile Container image definition (only when infra is agentcore-ecr)
    • package.json Updated with Strands and Express dependencies
    • project.json Updated with agent serve targets
protocol = ag-ui

AG-UI Protocol

Section titled “AG-UI Protocol”

The entry point uses @ag-ui/aws-strands to expose the agent via the AG-UI protocol (SSE over POST), compatible with CopilotKit:

  • Directoryyour-project/
    • Directorysrc/
      • Directoryagent/ (or custom name if specified)
        • index.ts AG-UI server entry point (Express + SSE)
        • agent.ts Main agent definition with sample tools
        • session.ts Resolves the SessionManager used to persist conversation state
        • Directorymiddleware/
          • session-id-middleware.ts Binds the inbound AgentCore session ID for the request
        • Dockerfile Container image definition (only when infra is agentcore-ecr)
    • package.json Updated with Strands and AG-UI dependencies
    • project.json Updated with agent serve targets

Infrastructure

Section titled “Infrastructure”

The infra option selects how your code is packaged and hosted on Amazon Bedrock AgentCore Runtime:

  • agentcore (default) uses direct code deployment: your built code is packaged as a .zip, uploaded to S3, and run on an AgentCore managed language runtime. There is no container image to build, no ECR repository to manage, and no image to push, which makes for a substantially faster build and deploy cycle.
  • agentcore-ecr builds an arm64 container image from a vended Dockerfile and hosts it from the shared core/asset-ecr registry, alongside every other container in the workspace. Choose this when you need control over the operating system image — for example to install native system libraries — or when you have an established container pipeline. This option additionally vends a Trivy image scan target (see Image Scanning below).
  • none generates no infrastructure at all, so the project can only be run locally.
infra = agentcore | agentcore-ecr

Since this generator vends infrastructure as code based on your chosen iac, 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:

  • 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

For deploying your Agent, the following files are generated:

  • Directorypackages/common/constructs/src
    • Directoryapp
      • Directoryagents
        • Directory<agent-name>
          • <agent-name>.ts CDK construct for deploying your agent
infra = none

If you selected none for infra, no CDK constructs or Terraform modules are generated — the Agent can only be run locally. The auth option is ignored in this mode since there is no hosted endpoint to authenticate.

Architecture

Section titled “Architecture”

When deployed to Bedrock AgentCore Runtime, your agent’s code is packaged as a zip and run in the AgentCore managed runtime. Clients invoke the AgentCore Runtime data plane endpoint, which forwards requests to your agent. The agent calls Amazon Bedrock for model inference and may invoke tools, MCP servers, or downstream APIs.

Loading the diagram…

Working with Your Agent

Section titled “Working with Your Agent”

Protocol

Section titled “Protocol”

Your agent’s server protocol determines how it communicates. You can choose between:

  • HTTP (default): Uses tRPC over WebSocket for real-time, type-safe communication. Best for custom client integrations and fine-grained control over the agent’s API.
  • A2A: Uses the Agent-to-Agent (A2A) protocol for standardized inter-agent communication. Best when your agent needs to be discoverable and invokable by other A2A-compatible agents.
  • AG-UI: Uses the AG-UI protocol (SSE over POST) via @ag-ui/aws-strands for direct frontend integration with CopilotKit. Best when you want a rich chat UI with streaming, tool-call visualization, and state management.

The protocol is set in the CDK/Terraform infrastructure, and the application code is generated accordingly.

protocol = http

tRPC over WebSocket (HTTP protocol)

Section titled “tRPC over WebSocket (HTTP protocol)”

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

Section titled “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 () => {
  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

Section titled “Model Configuration”

By default, Strands agents use Claude Sonnet 4.6 on Amazon Bedrock, 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

Section titled “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.

Run this generator@aws/nx-plugin:connection

pnpm nx g @aws/nx-plugin:connection
Build your command5

Required

Required

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

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

Section titled “More”

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

protocol = a2a

A2A Server (A2A protocol)

Section titled “A2A Server (A2A protocol)”

The generated index.ts mounts the Strands A2A Express Server onto an Express app so the generated agent exposes the A2A protocol endpoints alongside a /ping health check. The URL advertised in the agent card comes from the AGENTCORE_RUNTIME_URL environment variable, falling back to http://localhost:<port>/ for local development.

Most users will not need to modify this file — edit agent.ts to change tools or the system prompt. A2A agents listen on port 9000 (vs 8080 for HTTP), which the generated infrastructure is already configured for.

protocol = ag-ui

AG-UI Server (AG-UI protocol)

Section titled “AG-UI Server (AG-UI protocol)”

The generated index.ts wraps your Strands Agent in an @ag-ui/aws-strands StrandsAgent and builds an Express app. The resulting app exposes a single POST endpoint that streams AG-UI events over Server-Sent Events (SSE), as well as /ping for the AgentCore runtime health check.

AG-UI agents are designed to be consumed directly by a frontend. Use the connection generator to wire your React website up to the agent with a CopilotKit provider and AG-UI HttpAgent client.

Most users will not need to modify index.ts — edit agent.ts to change tools or the system prompt. AG-UI agents listen on port 8080 (same as HTTP), which the generated infrastructure is already configured for.

Running Your Agent

Section titled “Running Your Agent”

Local Development

Section titled “Local Development”

To run your Agent (and everything connected to it) locally, use the project’s dev target:

Terminal window
pnpm nx dev your-project

If you have added multiple components to your project (agents, MCP servers, etc.), this starts them all. To run just this agent, target its <your-agent-name>-dev target:

Terminal window
pnpm nx agent-dev your-project

This 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 — read it from metadata.ports in the project’s project.json).

A <your-agent-name>-serve target is also generated, which runs the agent against your deployed infrastructure and therefore requires RUNTIME_CONFIG_APP_ID to be set. See the Local Development guide for the difference between dev and serve.

Chat with Your Agent

Section titled “Chat with Your Agent”

The generator configures a <your-agent-name>-chat Nx target that drops you into an interactive terminal chat with your agent.

The chat target runs standalone. By default it connects to your locally running agent, so start the agent’s <your-agent-name>-dev target first (in a separate terminal):

Terminal window
pnpm nx agent-dev your-project

Then, in another terminal, start the chat:

Terminal window
pnpm nx run your-project:agent-chat

The generator emits a scripts/<your-agent-name>/chat.ts for every protocol. You can customize it as you evolve the agent’s input shape. It connects to the local agent by default, or to your deployed agent when RUNTIME_CONFIG_APP_ID is set (see Chat with your deployed agent below).

infra = agentcore | agentcore-ecr

Chat with your deployed agent

Section titled “Chat with your deployed agent”

To chat with your agent deployed to Bedrock AgentCore, set the RUNTIME_CONFIG_APP_ID environment variable to the AppConfig application id of the deployment (output as RuntimeConfigApplicationId by the deployed stack). The chat script resolves your agent’s runtime ARN from runtime configuration and connects to the deployed endpoint:

For IAM-authenticated agents, requests are signed with SigV4 using your default AWS credentials. Ensure the environment has AWS credentials with permission to invoke the runtime:

Terminal window
RUNTIME_CONFIG_APP_ID=<app-id> pnpm nx run your-project:agent-chat
infra = agentcore | agentcore-ecr

Deploying Your Agent to Bedrock AgentCore Runtime

Section titled “Deploying Your Agent to Bedrock AgentCore Runtime”

Infrastructure as Code

Section titled “Infrastructure as Code”

If you selected agentcore or agentcore-ecr for infra, the relevant CDK or Terraform infrastructure is generated which you can use to deploy your Agent to Amazon Bedrock AgentCore Runtime.

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) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

Authentication

Section titled “Authentication”

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

IAM

Section titled “IAM”

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

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

Cognito Authentication

Section titled “Cognito Authentication”

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

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#website#auth generator, or you can create your own CDK UserPool and UserPoolClient.

Bundle Target

Section titled “Bundle Target”

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

Terminal window
pnpm 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.

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

infra = agentcore

Package Target

Section titled “Package Target”

The generator configures a <your-agent-name>-package target which assembles the deployable code package: the bundled index.js plus a vendored install of the AWS Distro for OpenTelemetry, which AgentCore requires to be present in the package. The generated infrastructure uploads this directory as a .zip — via AgentRuntimeArtifact.fromCodeAsset under CDK, or archived into the shared asset bucket under Terraform.

infra = agentcore-ecr

Docker Target

Section titled “Docker Target”

The generator configures a <your-agent-name>-docker target which copies the Dockerfile from your agent source directory into the bundle output directory. This co-locates the Dockerfile with the bundled artifacts, allowing CDK to build the Docker image directly using AgentRuntimeArtifact.fromAsset.

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

Image Scanning

Section titled “Image Scanning”

The Docker image built for this project can be scanned for vulnerabilities using Trivy, running from the ECR-hosted Trivy image.

A trivy target is added to your project which scans the built image and exits non-zero if any HIGH or CRITICAL severity vulnerability is found. The generated Dockerfile uses a base image with no known fixable vulnerabilities of these severities at time of generation, and upgrades bundled tooling (such as npm) to keep it that way.

The scan uses the same container engine as your image build (docker or finch), so no additional tooling is required. The scan is not cached, since the image it reads lives in the container engine rather than on disk — so it always scans the real image, and fails loudly rather than reporting a cached pass for an image that is no longer there. Each run therefore takes tens of seconds per image and refreshes Trivy’s vulnerability database, so it needs network access. The vended trivy root script scans every image in the workspace:

Terminal window
pnpm trivy

Suppressing Trivy Findings

Section titled “Suppressing Trivy Findings”

There may be instances where you want to suppress a specific vulnerability, for example when no fix is yet available and you have assessed the risk as acceptable.

Add the vulnerability ID (one per line) to the .trivyignore file in the root of your project (i.e. next to your project.json):

.trivyignore
# node-tar arbitrary file write - not exploitable in our usage
CVE-2024-XXXXX

For more details on filtering findings, refer to the Trivy filtering documentation.

Observability

Section titled “Observability”

Your agent is automatically configured with observability using the AWS Distro for Open Telemetry (ADOT).

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.

Session Management

Section titled “Session Management”

The session option controls how your agent persists conversation state (message history, tool state, etc.) across invocations, using the Strands SDK’s SessionManager:

  • s3 (default): The CDK/Terraform infrastructure provisions a dedicated S3 bucket for session data, encrypted with a dedicated KMS key and with all public access blocked; server access logs are delivered to a CloudWatch Logs log group via the same key. The agent’s IAM role is granted read/write/list/delete access to the bucket and decrypt/generate-data-key access to the key, and the bucket name is registered alongside the agent’s ARN in AppConfig runtime configuration.
  • in-memory: No bucket is provisioned. Conversation state is kept in memory only for the lifetime of the running process and does not survive restarts or scale-in.

This is implemented in the generated session.ts, which exports a getSessionManager() function resolving a SessionManager for the current session.

The session ID itself comes from the AgentCore Runtime session (propagated via the x-amzn-bedrock-agentcore-runtime-session-id header for A2A/AG-UI, or the WebSocket connection context for HTTP/tRPC) and is bound to an AsyncLocalStorage-based context so getCurrentSessionId() can resolve it anywhere in the request — including in any downstream MCP or A2A clients wired up via the connection generator, so the whole call chain shares a consistent session.

Restricting sessions to their owner

Section titled “Restricting sessions to their owner”

The session ID arrives from the caller, so on its own it identifies a conversation but not who the conversation belongs to. AgentCore Runtime authorizes an invocation against the agent runtime resource ARN rather than against an individual session, which leaves the agent free to decide what a session means to your application.

To restrict each user to their own conversations:

  1. Add an API to create a session, using tRPC, FastAPI or Smithy. Generate an opaque session ID (at least 33 characters) and store it alongside the calling user’s ID — for example in a table created with the ts#dynamodb generator. Each API guide shows how to retrieve the calling user’s ID.
  2. In your agent, look up the stored user ID for the session ID it was given, and reject the request when it does not match the caller. With auth=cognito the caller’s JWT reaches your agent code, so its sub claim identifies them.

Generate the session ID rather than deriving it from user-supplied values such as a conversation name — anything a caller can predict, a caller can send.

Invoking your Agent

Section titled “Invoking your Agent”
protocol = http

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

Section titled “Invoke the Local Server”

Start your agent with the <your-agent-name>-dev target:

Terminal window
pnpm nx agent-dev your-project

Then invoke it 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:

The client class is named after your agent, so an agent named my-agent exports MyAgentClient.

scripts/test.ts
import { MyAgentClient } from '../packages/<project>/src/agent/client.js';


const client = MyAgentClient.local({ url: 'http://localhost:8081/ws' });


client.invoke.subscribe({ prompt: 'what is 1 plus 1?' }, { onData: console.log });

Substitute the port assigned to your agent — read it from metadata.ports in the project’s project.json.

Invoke the Deployed Agent

Section titled “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:

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

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.

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

Section titled “NodeJS”

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

IAM Authentication
Section titled “IAM Authentication”

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

import { MyAgentClient } from './agent/client.js';


const client = MyAgentClient.withIamAuth({
  agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
});


client.invoke.subscribe({ prompt: 'what is 1 plus 1?' }, {
  onData: (message) => console.log(message),
  onError: (error) => console.error(error),
  onComplete: () => console.log('Done'),
});

Browser / React Website

Section titled “Browser / React Website”

For invoking your 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).

Run this generator@aws/nx-plugin:connection

pnpm nx g @aws/nx-plugin:connection
Build your command5

Required

Required

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

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

protocol = a2a

Invoking an A2A Agent as a Tool

Section titled “Invoking an A2A Agent as a Tool”

To delegate work from this agent to a remote A2A agent (either TypeScript or Python), use the connection generator. It vends a SigV4-authenticated client for the target agent and AST-transforms this agent’s agent.ts to register the remote A2A agent as a Strands tool.

Run this generator@aws/nx-plugin:connection

pnpm nx g @aws/nx-plugin:connection
Build your command5

Required

Required

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

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

protocol = ag-ui

Invoking an AG-UI Agent

Section titled “Invoking an AG-UI Agent”

To invoke your AG-UI agent from a React website, use the connection generator, which wires up a CopilotKit client configured for your deployed agent with the correct authentication (IAM or Cognito).

Run this generator@aws/nx-plugin:connection

pnpm nx g @aws/nx-plugin:connection
Build your command5

Required

Required

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

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

Securing your Agent

Section titled “Securing your Agent”

Agents act on untrusted input and can drive real actions through their tools, so it’s worth considering security from the start. The following practices apply to the generated agent.

Treat model input and output as untrusted

Section titled “Treat model input and output as untrusted”

Prompts can contain adversarial instructions (prompt injection), and model output is non-deterministic — neither should be trusted in security-sensitive logic:

  • Define strict input schemas for your tools, as in the generated example tool. Constrain values to what the tool actually needs (enums, length limits, numeric ranges) rather than accepting free-form strings.
  • Never pass model output directly into shell commands, SQL queries, code evaluation, or rendered HTML without validation or encoding.
  • Apply authorization checks in your tools and downstream services — don’t rely on the system prompt to prevent the model from misusing a tool it has access to.

Strands’ Prompt Engineering and Responsible AI guides cover writing robust, safety-conscious system prompts.

Scope tool permissions tightly

Section titled “Scope tool permissions tightly”

Grant the agent’s IAM role only the permissions its tools need. The vended CDK constructs and Terraform modules expose grant* methods and scoped policies for this purpose — for example granting an agent access to invoke a specific API rather than attaching broad managed policies. Where a tool acts on behalf of a user, prefer authorizing the action using the calling user’s identity (passed through via the request context) over the agent’s own ambient permissions.

Provide a kill switch

Section titled “Provide a kill switch”

Because model behaviour can change in unexpected ways, plan for quickly disabling or swapping the model without a code change:

  • Read the model ID from configuration (for example a MODEL_ID environment variable) so operators can switch or roll back to a different model by updating configuration.
  • Gate the agent behind a feature flag so its AI functionality can be disabled entirely. When disabled, return a generic message rather than an error, and ensure the rest of your application degrades gracefully.

Document how to flip these controls in your operational runbook.

Protect sensitive data

Section titled “Protect sensitive data”
  • Avoid logging prompts and completions, which may contain user data. The generated agent’s model error logging hook logs error metadata only, not conversation content — keep this property when adding your own logging.
  • Return generic error messages to users; log detailed errors server-side.
  • Isolate conversation state between users and sessions, and authorize access to any persisted session data.
  • Redact personally identifiable information (PII) from prompts and outputs — either with a Bedrock Guardrail sensitive information filter (below) or, for Strands agents, the approaches in the PII Redaction guide.

Amazon Bedrock Guardrails

Section titled “Amazon Bedrock Guardrails”

Amazon Bedrock Guardrails provide configurable content filters, denied topics, and sensitive information (PII) filters which are evaluated on model input and output. You can attach a guardrail to the model used by the generated agent:

agent.ts
import { Agent } from '@strands-agents/sdk';
import { BedrockModel } from '@strands-agents/sdk/models/bedrock';


const model = new BedrockModel({
  modelId: process.env.MODEL_ID,
  guardrailConfig: {
    guardrailIdentifier: process.env.GUARDRAIL_ID!,
    guardrailVersion: process.env.GUARDRAIL_VERSION ?? 'DRAFT',
  },
});


const agent = new Agent({ model, /* ... */ });

See the Strands Guardrails guide for more detail.

Connections

Section titled “Connections”

Use the connection generator to integrate this project with others in your workspace. The following connections involve this project:

Strands AgentsTypeScript
React to TypeScript AgentCall a TypeScript Agent from a React website
CopilotKit
React to AG-UI AgentCall an Agent exposing the AG-UI protocol from a React website via CopilotKit
Strands AgentsTypeScriptModel Context Protocol
TypeScript Agent to MCPConnect a TypeScript Agent to an MCP server
Strands AgentsTypeScriptAgent2Agent
TypeScript Agent to A2A AgentConnect a TypeScript Agent to a remote A2A agent
Strands AgentsPythonAgent2Agent
Python Agent to A2A AgentConnect a Python Agent to a remote A2A agent
Strands AgentsTypeScriptAmazon Aurora
TypeScript Agent to Relational DatabaseConnect a TypeScript Agent to an Aurora relational database
Strands AgentsTypeScriptAmazon DynamoDB
TypeScript Agent to TypeScript DynamoDBConnect a TypeScript Agent to a DynamoDB table
Strands AgentsTypeScriptAmazon Bedrock AgentCore Gateway
TypeScript Agent to AgentCore GatewayConnect a TypeScript Agent to an AgentCore Gateway
Amazon Bedrock AgentCore GatewayStrands Agents
AgentCore Gateway to AgentFront an agent with an AgentCore Gateway as a runtime target