strands-agents · hsaenzG · Sep 24, 2026
diff --git a/typescript/02-deploy/02-nextjs-vercel-adapter/.dockerignore b/typescript/02-deploy/02-nextjs-vercel-adapter/.dockerignore
@@ -0,0 +1,11 @@
+node_modules
+.next
+.git
+.env
+.env.*
+!.env.example
+.sessions
+npm-debug.log
+Dockerfile
+.dockerignore
+README.md
diff --git a/typescript/02-deploy/02-nextjs-vercel-adapter/.env.example b/typescript/02-deploy/02-nextjs-vercel-adapter/.env.example
@@ -0,0 +1,33 @@
+# ---------------------------------------------------------------------------
+# Model provider — the Vercel AI SDK owns the provider; Strands wraps it.
+# ---------------------------------------------------------------------------
+# Which provider to use: "bedrock" (default) or "openai".
+MODEL_PROVIDER=bedrock
+
+# --- Amazon Bedrock (default) ---
+# Uses the standard AWS credential chain. On Vercel, set these as env vars.
+AWS_REGION=us-east-2
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+# Optional session token if using temporary credentials.
+# AWS_SESSION_TOKEN=
+# Override the default Bedrock model id if desired.
+# Amazon Nova Pro (free-tier friendly) via cross-region inference profile.
+BEDROCK_MODEL_ID=us.amazon.nova-pro-v1:0
+
+# --- OpenAI (optional; set MODEL_PROVIDER=openai) ---
+OPENAI_API_KEY=
+OPENAI_MODEL_ID=gpt-4o-mini
+
+# ---------------------------------------------------------------------------
+# Sessions — Strands persists conversation state via pluggable storage.
+# ---------------------------------------------------------------------------
+# "memory" (default), "file", or "s3".
+SESSION_BACKEND=memory
+
+# --- file backend ---
+SESSION_DIR=./.sessions
+
+# --- s3 backend (recommended for serverless / AgentCore container path) ---
+SESSION_S3_BUCKET=
+SESSION_S3_PREFIX=sessions/
diff --git a/typescript/02-deploy/02-nextjs-vercel-adapter/.gitignore b/typescript/02-deploy/02-nextjs-vercel-adapter/.gitignore
@@ -0,0 +1,45 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+!.env.example
+
+# strands session store (file backend)
+/.sessions
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
diff --git a/typescript/02-deploy/02-nextjs-vercel-adapter/AGENTS.md b/typescript/02-deploy/02-nextjs-vercel-adapter/AGENTS.md
@@ -0,0 +1,9 @@
+<!-- BEGIN:nextjs-agent-rules -->
+
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+<!-- END:nextjs-agent-rules -->
diff --git a/typescript/02-deploy/02-nextjs-vercel-adapter/Dockerfile b/typescript/02-deploy/02-nextjs-vercel-adapter/Dockerfile
@@ -0,0 +1,25 @@
+# syntax=docker/dockerfile:1
+
+# ---- Build the Next.js app (standalone output) ----
+FROM node:22-slim AS builder
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci
+
+COPY . .
+RUN npm run build
+
+# ---- Run ----
+FROM node:22-slim AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+ENV PORT=3000
+
+# Standalone output bundles only what the server needs.
+COPY --from=builder /app/.next/standalone ./
+COPY --from=builder /app/.next/static ./.next/static
+COPY --from=builder /app/public ./public
+
+EXPOSE 3000
+CMD ["node", "server.js"]
diff --git a/typescript/02-deploy/02-nextjs-vercel-adapter/README.md b/typescript/02-deploy/02-nextjs-vercel-adapter/README.md
@@ -0,0 +1,170 @@
+# Strands × Vercel AI SDK — Next.js Template
+
+A `create-next-app`-shaped chat sample where the **Vercel AI SDK owns the client and the providers**, and **[Strands Agents](https://strandsagents.com) runs the loop, tools, sessions, and hooks** inside the Next.js route handler through the **`VercelModel` adapter**. One-click deploy to Vercel, plus a container path to Amazon Bedrock AgentCore.
+
+## Overview
+
+### Sample Details
+
+| Information            | Details                                                                 |
+|------------------------|-------------------------------------------------------------------------|
+| **Agent Architecture** | Single-agent                                                            |
+| **Native Tools**       | `calculator`, `current_time`                                            |
+| **Custom Tools**       | None (Zod-typed tools defined inline in `lib/tools.ts`)                 |
+| **MCP Servers**        | None                                                                    |
+| **Use Case Vertical**  | Developer tooling / Conversational AI                                   |
+| **Complexity**         | Intermediate                                                            |
+| **Model Provider**     | Amazon Bedrock (default) or OpenAI                                      |
+| **SDK Used**           | Strands Agents SDK (TypeScript) + Vercel AI SDK                         |
+
+### Architecture
+
+![Architecture — AI SDK on the client, Strands on the server](./images/architecture.png)
+
+The route handler translates Strands stream events into the AI SDK UI message
+stream protocol (`text-delta`, `tool-input-available`, `tool-output-available`),
+so `useChat` renders tokens and tool activity as they arrive.
+
+### Key Features
+
+- **AI SDK on the client** — `useChat` from `@ai-sdk/react` manages the conversation and streaming UI.
+- **Strands on the server** — the agent loop, Zod-typed tools, session persistence, and lifecycle hooks run in `app/api/chat/route.ts`.
+- **`VercelModel` adapter** — Strands wraps any Vercel AI SDK provider (`@ai-sdk/amazon-bedrock`, `@ai-sdk/openai`, …). Switch providers with one env var, no code changes.
+- **One-click deploy to Vercel** — ships as a serverless Node function.
+- **Container path to Amazon Bedrock AgentCore** — the same agent, served over the AgentCore HTTP contract (`/ping` + `/invocations`) on an ARM64 container.
+
+## Prerequisites
+
+- Node.js **18+**
+- One model provider configured:
+  - **Amazon Bedrock** (default): AWS credentials and [model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access-modify.html) enabled for the configured model, **or**
+  - **OpenAI**: an `OPENAI_API_KEY`.
+- (Optional) Docker, for the AgentCore / Node host container paths.
+
+## Setup
+
+1. **Configure environment variables:**
+   ```bash
+   cp .env.example .env.local
+   # then fill in credentials (see Configuration below)
+   ```
+
+2. **Install dependencies:**
+   ```bash
+   npm install
+   ```
+
+## Usage
+
+**Run the dev server:**
+```bash
+npm run dev
+```
+
+Open http://localhost:3000. Try:
+
+- *"what is 128 divided by 4?"* → calls the `calculator` tool
+- *"what time is it in America/Mexico_City?"* → calls the `current_time` tool
+
+## Configuration
+
+All configuration is via environment variables — see [`.env.example`](./.env.example).
+
+### Model provider (the AI SDK owns the provider; Strands wraps it)
+
+| Variable | Default | Description |
+|---|---|---|
+| `MODEL_PROVIDER` | `bedrock` | `bedrock` or `openai`. |
+| `AWS_REGION` | `us-east-1` | Region for Amazon Bedrock. |
+| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | — | AWS credentials (Bedrock). |
+| `BEDROCK_MODEL_ID` | `us.anthropic.claude-sonnet-4-20250514-v1:0` | Bedrock model id. |
+| `OPENAI_API_KEY` | — | Required when `MODEL_PROVIDER=openai`. |
+| `OPENAI_MODEL_ID` | `gpt-4o-mini` | OpenAI model id. |
+
+To switch to OpenAI, set `MODEL_PROVIDER=openai` and `OPENAI_API_KEY` — no code changes.
+
+### Sessions (Strands persists conversation state)
+
+| Variable | Default | Description |
+|---|---|---|
+| `SESSION_BACKEND` | `memory` | `memory`, `file`, or `s3`. |
+| `SESSION_DIR` | `./.sessions` | Directory for the `file` backend. |
+| `SESSION_S3_BUCKET` | — | Bucket for the `s3` backend. |
+| `SESSION_S3_PREFIX` | `sessions/` | Key prefix for the `s3` backend. |
+
+## Deploy to Vercel
+
+![Vercel serverless architecture](./images/1-vercel-serverless.svg)
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fstrands-agents%2Fsamples%2Ftree%2Fmain%2Ftypescript%2F02-deploy%2F02-nextjs-vercel-adapter&project-name=strands-nextjs-vercel-adapter&repository-name=strands-nextjs-vercel-adapter&env=MODEL_PROVIDER,AWS_REGION,AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY&envDescription=Model%20provider%20and%20credentials.%20See%20.env.example.&envLink=https%3A%2F%2Fgithub.com%2Fstrands-agents%2Fsamples%2Fblob%2Fmain%2Ftypescript%2F02-deploy%2F02-nextjs-vercel-adapter%2F.env.example)
+
+The `/api/chat` route runs on the Node.js runtime. Set your provider env vars in
+the Vercel dashboard (see Configuration). For persistence across serverless
+instances, use `SESSION_BACKEND=s3`.
+
+## Container path → Amazon Bedrock AgentCore
+
+The same Strands agent (`lib/agent.ts`) is also served over the AgentCore HTTP
+contract: `GET /ping` and `POST /invocations` (SSE streaming) on `0.0.0.0:8080`,
+ARM64.
+
+![Amazon Bedrock AgentCore container architecture](./images/2-agentcore-container.svg)
+
+```bash
+# Run the AgentCore runtime locally
+npm run agentcore
+curl localhost:8080/ping
+curl -N -X POST localhost:8080/invocations \
+  -H 'content-type: application/json' \
+  -d '{"prompt":"what is 21 * 2?","sessionId":"demo"}'
+
+# Build the ARM64 image for AgentCore
+docker build --platform linux/arm64 -f agentcore/Dockerfile -t strands-agentcore .
+```
+
+Push the image to Amazon ECR and create an AgentCore Runtime pointing at it. Use
+`SESSION_BACKEND=s3` so conversation state survives across instances. See the
+[AgentCore HTTP protocol contract](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-http-protocol-contract.html).
+
+## Container path → any Node host
+
+A production `Dockerfile` (standalone Next.js output) is included for running the
+full web app anywhere:
+
+![Docker on any Node host architecture](./images/3-docker-node-host.svg)
+
+```bash
+docker build -t strands-nextjs .
+docker run -p 3000:3000 --env-file .env.local strands-nextjs
+```
+
+## Project Structure
+
+| Component | File(s) | Description |
+|---|---|---|
+| Chat UI | `app/page.tsx` | Client chat UI (`useChat`). |
+| API route | `app/api/chat/route.ts` | Strands loop bridged to the AI SDK UI stream. |
+| Model | `lib/model.ts` | Provider selection → `VercelModel`. |
+| Tools | `lib/tools.ts` | Zod-typed tools. |
+| Hooks | `lib/hooks.ts` | `LoggingPlugin` — lifecycle hooks. |
+| Sessions | `lib/session.ts` | Pluggable session storage. |
+| Agent | `lib/agent.ts` | Assembles the `Agent`. |
+| AgentCore | `agentcore/` | Container path to Amazon Bedrock AgentCore. |
+
+## Additional Resources
+
+- [Strands Agents](https://strandsagents.com) · [`VercelModel` adapter](https://github.com/strands-agents/harness-sdk/blob/main/strands-ts/src/models/vercel.ts)
+- [Vercel AI SDK](https://ai-sdk.dev) · [`useChat`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat)
+- [Amazon Bedrock AgentCore](https://docs.aws.amazon.com/bedrock-agentcore/)
+
+---
+
+## Disclaimer
+
+This sample is provided for educational and demonstration purposes only. It is not intended for production use without further development, testing, and hardening.
+
+For production deployments, consider:
+- Implementing appropriate content filtering and safety measures
+- Following security best practices for your deployment environment
+- Conducting thorough testing and validation
+- Reviewing and adjusting configurations for your specific requirements
diff --git a/typescript/02-deploy/02-nextjs-vercel-adapter/agentcore/Dockerfile b/typescript/02-deploy/02-nextjs-vercel-adapter/agentcore/Dockerfile
@@ -0,0 +1,21 @@
+# syntax=docker/dockerfile:1
+#
+# Amazon Bedrock AgentCore Runtime image.
+# AgentCore requires an ARM64 container that serves /ping + /invocations on :8080.
+# Build:  docker build --platform linux/arm64 -f agentcore/Dockerfile -t strands-agentcore .
+FROM --platform=linux/arm64 node:22-slim
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci
+
+COPY lib ./lib
+COPY agentcore ./agentcore
+COPY tsconfig.json ./
+
+ENV NODE_ENV=production
+ENV PORT=8080
+EXPOSE 8080
+
+# tsx runs the TypeScript entrypoint directly (no separate build step).
+CMD ["npx", "tsx", "agentcore/server.ts"]