@aws/nx-plugin-mcp 0.120.0 → 0.121.0

package/docs/guides/ts-agent.mdx

@@ -0,0 +1,436 @@
+---
+title: TypeScript Agent
+description: Generate a TypeScript Agent for building AI agents with tools and deploy to Amazon Bedrock AgentCore Runtime
+generator: ts#agent
+---
+
+import { FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
+import RunGenerator from '@components/run-generator.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Link from '@components/link.astro';
+import Snippet from '@components/snippet.astro';
+import Infrastructure from '@components/infrastructure.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import PackageManagerExecCommand from '@components/package-manager-exec-command.astro';
+import OptionFilter from '@components/option-filter.astro';
+
+Generate a TypeScript [Strands Agent](https://strandsagents.com/) for building AI agents with tools, and optionally deploy it to [Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/). By default, the generator uses [tRPC](https://trpc.io/) over WebSocket to leverage [AgentCore's bidirectional streaming support](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-websocket.html) for real-time, type-safe communication. Alternatively, you can choose the [Agent-to-Agent (A2A)](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-a2a.html) protocol for interoperability with other A2A-compatible agents, or the [AG-UI](https://docs.ag-ui.com/) protocol for direct frontend integration via [CopilotKit](https://docs.copilotkit.ai/aws-strands).
+
+## What is Strands?
+
+[Strands](https://strandsagents.com/docs/user-guide/quickstart/overview/) 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 an Agent
+
+You can generate a TypeScript Agent in two ways:
+
+<RunGenerator generator="ts#agent" />
+
+:::tip[Project Prerequisite]
+First use the <Link path="/guides/typescript-project">`ts#project`</Link> generator to create a project to add your Agent to.
+:::
+
+### Options
+
+<GeneratorParameters generator="ts#agent" />
+
+## Generator Output
+
+The generator will add the following files to your existing TypeScript project. The files generated depend on the chosen `protocol`:
+
+<OptionFilter when={{ protocol: 'HTTP' }} description="tRPC-over-WebSocket layout">
+### HTTP Protocol (default)
+
+<FileTree>
+  - your-project/
+    - src/
+      - agent/ (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
+        - 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
+</FileTree>
+</OptionFilter>
+
+<OptionFilter when={{ protocol: 'A2A' }} description="Strands A2A Express server layout">
+### A2A Protocol
+
+The entry point uses the [Strands A2A Express Server](https://strandsagents.com/docs/user-guide/concepts/multi-agent/agent-to-agent) instead of tRPC:
+
+<FileTree>
+  - your-project/
+    - src/
+      - agent/ (or custom name if specified)
+        - index.ts A2A Express server entry point
+        - agent.ts Main agent definition with sample tools
+        - Dockerfile Entry point for hosting your agent (excluded when `computeType` is set to `None`)
+    - package.json Updated with Strands and Express dependencies
+    - project.json Updated with agent serve targets
+</FileTree>
+</OptionFilter>
+
+<OptionFilter when={{ protocol: 'AG-UI' }} description="AG-UI SSE-over-POST server layout">
+### AG-UI Protocol
+
+The entry point uses [`@ag-ui/aws-strands`](https://www.npmjs.com/package/@ag-ui/aws-strands) to expose the agent via the [AG-UI protocol](https://docs.ag-ui.com/) (SSE over POST), compatible with [CopilotKit](https://docs.copilotkit.ai/aws-strands):
+
+<FileTree>
+  - your-project/
+    - src/
+      - agent/ (or custom name if specified)
+        - index.ts AG-UI server entry point (Express + SSE)
+        - agent.ts Main agent definition with sample tools
+        - Dockerfile Entry point for hosting your agent (excluded when `computeType` is set to `None`)
+    - package.json Updated with Strands and AG-UI dependencies
+    - project.json Updated with agent serve targets
+</FileTree>
+</OptionFilter>
+
+### Infrastructure
+
+<OptionFilter when={{ computeType: 'BedrockAgentCoreRuntime' }} description="Bedrock AgentCore Runtime deployment">
+<Snippet name="shared-constructs" />
+
+For deploying your Agent, the following files are generated:
+
+<Infrastructure>
+<Fragment slot="cdk">
+<FileTree>
+  - packages/common/constructs/src
+    - app
+      - agents
+        - \<project-name>
+          - \<project-name>.ts CDK construct for deploying your agent
+</FileTree>
+</Fragment>
+<Fragment slot="terraform">
+<FileTree>
+  - packages/common/terraform/src
+    - app
+      - agents
+        - \<project-name>
+          - \<project-name>.tf Module for deploying your agent
+    - core
+      - agent-core
+        - runtime.tf Generic module for deploying to Bedrock AgentCore Runtime
+</FileTree>
+</Fragment>
+</Infrastructure>
+</OptionFilter>
+
+<OptionFilter when={{ computeType: 'None' }} description="No infrastructure is vended for computeType=None">
+If you selected `None` for `computeType`, 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.
+</OptionFilter>
+
+#### Architecture
+
+<Snippet name="agent/architecture" />
+
+## Working with Your Agent
+
+### Protocol
+
+Your agent's server protocol determines how it communicates. You can choose between:
+
+- **HTTP** (default): Uses [tRPC](https://trpc.io/) 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)](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-a2a.html) 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](https://docs.ag-ui.com/) (SSE over POST) via [`@ag-ui/aws-strands`](https://www.npmjs.com/package/@ag-ui/aws-strands) for direct frontend integration with [CopilotKit](https://docs.copilotkit.ai/aws-strands). 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.
+
+<OptionFilter when={{ protocol: 'HTTP' }} description="tRPC over WebSocket details">
+### tRPC over WebSocket (HTTP protocol)
+
+The TypeScript Agent uses [tRPC](https://trpc.io/) over WebSocket, leveraging [AgentCore's bidirectional streaming support](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-websocket.html) 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`.
+</OptionFilter>
+
+### Adding Tools
+
+Tools are functions that the AI agent can call to perform actions. You can add new tools in the `agent.ts` file:
+
+```typescript
+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:
+
+```typescript
+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](https://strandsagents.com/docs/user-guide/concepts/model-providers/) for more configuration options.
+
+### Consuming MCP Servers
+
+You can [add tools from MCP servers](https://strandsagents.com/docs/user-guide/concepts/tools/mcp-tools/) to your Strands agent.
+
+For consuming MCP Servers which you have created using the <Link path="/guides/py-mcp-server">`py#mcp-server`</Link> or <Link path="/guides/ts-mcp-server">`ts#mcp-server`</Link> generators you can make use of the <Link path="/guides/connection/ts-agent-mcp">`connection` generator</Link>.
+
+<RunGenerator generator="connection" />
+
+Refer to the <Link path="/guides/connection/ts-agent-mcp">`connection` generator guide</Link> for details about how the connection is set up.
+
+For other MCP servers, please refer to the [Strands Documentation](https://strandsagents.com/docs/user-guide/concepts/tools/mcp-tools/).
+
+### More
+
+For a more in-depth guide to writing Strands agents, refer to the [Strands documentation](https://strandsagents.com/docs/user-guide/quickstart/overview/).
+
+<OptionFilter when={{ protocol: 'A2A' }} description="A2A Express server details">
+## A2A Server (A2A protocol)
+
+The generated `index.ts` mounts the [Strands A2A Express Server](https://strandsagents.com/docs/user-guide/concepts/multi-agent/agent-to-agent) onto an Express app so the generated agent exposes the A2A protocol endpoints alongside a `/ping` health check. When deployed to AgentCore, the entry point resolves the runtime's public ARN from AppConfig and advertises it in the agent card.
+
+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 Dockerfile and infrastructure are already configured for.
+</OptionFilter>
+
+<OptionFilter when={{ protocol: 'AG-UI' }} description="AG-UI server details">
+## AG-UI Server (AG-UI protocol)
+
+The generated `index.ts` wraps your Strands `Agent` in an [`@ag-ui/aws-strands`](https://www.npmjs.com/package/@ag-ui/aws-strands) `StrandsAgent` and creates an Express app via `createStrandsApp()`. The resulting app exposes a single POST endpoint that streams [AG-UI](https://docs.ag-ui.com/) 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 <Link path="/guides/connection/react-agui">`connection` generator</Link> to wire your React website up to the agent with a [CopilotKit](https://docs.copilotkit.ai/aws-strands) provider and [AG-UI HttpAgent](https://docs.ag-ui.com/) 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 Dockerfile and infrastructure are already configured for.
+</OptionFilter>
+
+## Running Your Agent
+
+### Local Development
+
+The generator configures a target named `<your-agent-name>-serve`, which starts your Agent locally for development and testing.
+
+<NxCommands commands={['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).
+
+### Chat with Your Agent
+
+The generator configures a `<your-agent-name>-chat` Nx target that depends on `<your-agent-name>-serve-local`. Running it starts the agent locally and drops you into an interactive terminal chat:
+
+<NxCommands commands={['run your-project:agent-chat']} />
+
+For **HTTP** (tRPC over WebSocket) agents, the generator also emits a tiny `scripts/<your-agent-name>/chat.ts` that wraps the generated `<Agent>Client.local({ url })` so you can customize it as you evolve the agent's input shape.
+
+<OptionFilter when={{ computeType: 'BedrockAgentCoreRuntime' }} description="Bedrock AgentCore Runtime deployment details">
+## Deploying Your Agent to Bedrock AgentCore Runtime
+
+<Snippet name="agent/bedrock-deployment" parentHeading="Deploying Your Agent to Bedrock AgentCore Runtime" />
+
+### Bundle Target
+
+<Snippet name="ts-bundle" />
+
+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 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.
+
+### Observability
+
+Your agent is automatically configured with observability using the [AWS Distro for Open Telemetry](https://aws.amazon.com/otel/) (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](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html).
+
+For more details, refer to the [AgentCore documentation on observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html).
+</OptionFilter>
+
+## Invoking your 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`.
+
+<OptionFilter when={{ protocol: 'HTTP' }} description="tRPC-over-WebSocket client factory invocation details">
+### 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:
+
+```typescript
+// 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 });
+```
+
+:::tip[Quick Testing]
+Run with `tsx` as a quick way to test out your agent.
+
+<PackageManagerExecCommand commands={['tsx scripts/test.ts']} />
+:::
+
+### Invoke the Deployed Agent
+
+<Snippet name="agent/runtime-arn" parentHeading="Invoke the Deployed Agent" />
+
+#### NodeJS
+
+The generated `client.ts` file includes a type-safe client factory which can be used to invoke your deployed agent.
+
+:::caution[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.
+:::
+
+<Tabs syncKey="auth">
+<TabItem label="IAM" _filter={{ auth: 'IAM' }}>
+##### IAM Authentication
+
+You can invoke your deployed agent by passing its ARN to the `withIamAuth` factory method:
+
+```typescript
+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'),
+});
+```
+
+:::note[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.
+:::
+</TabItem>
+
+<TabItem label="Cognito" _filter={{ auth: 'Cognito' }}>
+##### JWT / Cognito Authentication
+
+Use the `withJwtAuth` factory method to authenticate with the JWT / Cognito access token.
+
+```typescript
+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:
+
+```typescript
+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!;
+  },
+});
+```
+</TabItem>
+</Tabs>
+
+#### Browser / React Website
+
+For invoking your Agent from a React website, you can make use of the <Link path="/guides/connection/react-ts-agent">`connection` generator</Link>, which automatically sets up a tRPC WebSocket client with the correct authentication (IAM or Cognito).
+
+<RunGenerator generator="connection" />
+
+Refer to the <Link path="/guides/connection/react-ts-agent">`connection` generator guide</Link> for details about how the connection is set up.
+</OptionFilter>
+
+<OptionFilter when={{ protocol: 'A2A' }} description="A2A delegation details">
+### Invoking an A2A Agent as a Tool
+
+To delegate work from this agent to a remote A2A agent (either <Link path="/guides/ts-agent">TypeScript</Link> or <Link path="/guides/py-agent">Python</Link>), use the <Link path="/guides/connection/ts-agent-a2a">`connection` generator</Link>. 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`.
+
+<RunGenerator generator="connection" />
+
+Refer to the <Link path="/guides/connection/ts-agent-a2a">`connection` generator guide</Link> for details about how the connection is set up.
+</OptionFilter>
+
+<OptionFilter when={{ protocol: 'AG-UI' }} description="AG-UI / React connection details">
+### Invoking an AG-UI Agent
+
+To invoke your AG-UI agent from a React website, use the <Link path="/guides/connection/react-agui">`connection` generator</Link>, which wires up a [CopilotKit](https://docs.copilotkit.ai/aws-strands) client configured for your deployed agent with the correct authentication (IAM or Cognito).
+
+<RunGenerator generator="connection" />
+
+Refer to the <Link path="/guides/connection/react-agui">`connection` generator guide</Link> for details about how the connection is set up.
+</OptionFilter>

package/docs/guides/ts-lambda-function.mdx

@@ -0,0 +1,218 @@
+---
+title: TypeScript Lambda Function
+description: Generate a TypeScript lambda function
+generator: ts#lambda-function
+---
+
+import { FileTree } from '@astrojs/starlight/components';
+import Link from '@components/link.astro';
+import RunGenerator from '@components/run-generator.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Infrastructure from '@components/infrastructure.astro';
+import Snippet from '@components/snippet.astro';
+import OptionFilter from '@components/option-filter.astro';
+
+The TypeScript Lambda Function generator provides the ability to add a lambda function to an existing TypeScript project.
+
+This generator creates a new TypeScript lambda handler with AWS CDK or Terraform infrastructure setup. The generated handler uses [AWS Lambda Powertools for TypeScript](https://docs.powertools.aws.dev/lambda/typescript/latest/) for observability, including logging, AWS X-Ray tracing and CloudWatch Metrics, as well as optional type-safety for the event using the [Parser from AWS Lambda Powertools](https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/parser/)
+
+## Usage
+
+### Generate a TypeScript lambda function
+
+You can generate a lambda function in two ways:
+
+<RunGenerator generator="ts#lambda-function" />
+
+### Options
+
+<GeneratorParameters generator="ts#lambda-function" />
+
+## Generator Output
+
+The generator will add the following files to your project:
+
+<FileTree>
+
+- \<project-name>
+  - src/
+    - \<lambda-function>.ts Function implementation
+
+</FileTree>
+
+If the `functionPath` option is provided, the generator will add the handler to the specified path within the project source directory:
+
+<FileTree>
+
+- \<project-name>
+  - src/
+    - \<custom-path>/
+      - \<function-name>.ts Function implementation
+
+</FileTree>
+
+### Infrastructure
+
+<Snippet name="shared-constructs" />
+
+The generator creates infrastructure as code for deploying your function based on your selected `iacProvider`:
+
+<Infrastructure>
+<Fragment slot="cdk">
+The generator creates a CDK construct which can be used to deploy your function, which resides in the `packages/common/constructs/src/app/lambda-functions` directory.
+</Fragment>
+<Fragment slot="terraform">
+The generator creates a Terraform module which can be used to deploy your function, which resides in the `packages/common/terraform/src/app/lambda-functions/<function-name>` directory.
+</Fragment>
+</Infrastructure>
+
+#### Architecture
+
+<Snippet name="lambda-function/architecture" />
+
+## Implementing your Function
+
+The main function implementation is in `<function-name>.ts`. Here's an example:
+
+```typescript
+import { parser } from '@aws-lambda-powertools/parser/middleware';
+import { EventBridgeSchema } from '@aws-lambda-powertools/parser/schemas';
+import middy from '@middy/core';
+import { Tracer } from '@aws-lambda-powertools/tracer';
+import { captureLambdaHandler } from '@aws-lambda-powertools/tracer/middleware';
+import { injectLambdaContext } from '@aws-lambda-powertools/logger/middleware';
+import { Logger } from '@aws-lambda-powertools/logger';
+import { Metrics } from '@aws-lambda-powertools/metrics';
+import { logMetrics } from '@aws-lambda-powertools/metrics/middleware';
+import { z } from 'zod';
+
+process.env.POWERTOOLS_METRICS_NAMESPACE = 'MyFunction';
+process.env.POWERTOOLS_SERVICE_NAME = 'MyFunction';
+
+const tracer = new Tracer();
+const logger = new Logger();
+const metrics = new Metrics();
+
+export const myFunction = async (
+  event: z.infer<typeof EventBridgeSchema>,
+): Promise<void> => {
+  logger.info('Received event', event);
+
+  // TODO: implement
+};
+
+export const handler = middy()
+  .use(captureLambdaHandler(tracer))
+  .use(injectLambdaContext(logger))
+  .use(logMetrics(metrics))
+  .use(parser({ schema: EventBridgeSchema }))
+  .handler(myFunction);
+
+```
+
+The generator sets up several features automatically:
+
+1. **Middy middleware stack** for enhanced Lambda functionality
+2. **AWS Lambda Powertools integration** for observability
+3. **Metrics collection** with CloudWatch
+4. **Type-safety** using parser middleware
+5. **Bundling with Rolldown** for optimized deployment packages
+
+### Observability with AWS Lambda Powertools
+
+#### Logging
+
+The generator configures structured logging using AWS Lambda Powertools with automatic context injection via Middy middleware.
+
+```typescript
+export const handler = middy()
+  .use(injectLambdaContext(logger))
+  .handler(myFunction);
+```
+
+#### Tracing
+
+AWS X-Ray tracing is configured automatically via the `captureLambdaHandler` middleware. You can add custom subsegments to your traces:
+
+```typescript
+const tracer = new Tracer();
+
+export const myFunction = async (
+  event: z.infer<typeof EventBridgeSchema>,
+): Promise<void> => {
+  // Creates a new subsegment
+  const subsegment = tracer.getSegment()?.addNewSubsegment('custom-operation');
+  try {
+    // Your logic here
+  } catch (error) {
+    subsegment?.addError(error as Error);
+    throw error;
+  } finally {
+    subsegment?.close();
+  }
+};
+
+export const handler = middy()
+  .use(captureLambdaHandler(tracer))
+  .handler(myFunction);
+```
+
+#### Metrics
+
+CloudWatch metrics are collected automatically for each request via the `logMetrics` middleware. You can add custom metrics:
+
+```typescript
+const metrics = new Metrics();
+
+export const myFunction = async (
+  event: z.infer<typeof EventBridgeSchema>,
+): Promise<void> => {
+  metrics.addMetric("CustomMetric", MetricUnit.Count, 1);
+  metrics.addMetric("ProcessingTime", MetricUnit.Milliseconds, processingTime);
+};
+
+export const handler = middy()
+  .use(logMetrics(metrics))
+  .handler(myFunction);
+```
+
+### Type Safety
+
+<OptionFilter not when={{ eventSource: 'Any' }} description="eventSource provides a typed Zod schema for the incoming event">
+If you chose an `eventSource` when generating your lambda function, your function is instrumented with the [`parser` middleware from AWS Lambda Powertools](https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/parser/). For example:
+
+```typescript {4}
+export const myFunction = async (
+  event: z.infer<typeof EventBridgeSchema>,
+): Promise<void> => {
+  event.detail // <- type-safe with IDE autocompletion
+};
+
+export const handler = middy()
+  .use(parser({ schema: EventBridgeSchema }))
+  .handler(myFunction);
+```
+
+This provides compile-time type safety and runtime validation for your Lambda events.
+
+:::caution[Error Handling]
+If you do not want your handler to throw an error when the event does not conform to the schema, you can use the [`safeParse` option](https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/parser/#safe-parsing).
+:::
+
+:::tip[Custom Event Data]
+If you have custom data nested within an event, for example a DynamoDB stream or EventBridge event, you may benefit from using [Envelopes](https://docs.powertools.aws.dev/lambda/typescript/latest/utilities/parser/#envelopes) to provide type-safety for that custom data.
+:::
+</OptionFilter>
+
+<OptionFilter when={{ eventSource: 'Any' }} description="eventSource=Any — no parser middleware, event is typed as `any`">
+If you selected `Any` for your `eventSource`, the `parser` middleware is not wired in and the `event` parameter is typed as `any`. Regenerate the function with a specific `eventSource` if you want compile-time type safety and runtime validation.
+</OptionFilter>
+
+## Bundling
+
+<Snippet name="ts-bundle" />
+
+## Deploying your Function
+
+<Snippet name="lambda-function/deploying-your-function" parentHeading="Deploying your Function" />