Strands Agent Demo by Dave Xia

An interactive SvelteKit demo powered by the AWS Strands Agents SDK (@strands-agents/sdk). The app runs a model-driven, multi-step agent loop with calculator and live weather tools. Built with Svelte 5, styled with Tailwind CSS, and optimized for secure server-side processing.

Repository: github.com/xxdxxd/strands-agent

---

🔒 Configuration & API Keys

Use an environment file or container environment variables rather than hardcoding credentials in the UI or source code. This keeps API keys out of the client bundle and version control.

Config File

The application reads OPENAI_API_KEY and OPENAI_BASE_URL from the server environment. In local development and production (npm run start), the server loads a root .env file automatically via the dotenv package (see src/lib/server/env.ts and src/hooks.server.ts).

1. Locate the .env.example template in the root directory.
2. Duplicate it and rename it to .env:

   cp .env.example .env

3. Open .env and specify your credentials:

   # Your OpenRouter or OpenAI API Key
   OPENAI_API_KEY="your_actual_api_key"
   
   # Base URL (defaults to OpenRouter if not specified)
   OPENAI_BASE_URL="https://openrouter.ai/api/v1"

If no server-side key is configured, you can still enter an API key in the left sidebar at runtime. The /api/health endpoint reports whether a host key is present.

---

🐧 Run Locally on Ubuntu Linux (Node.js)

Follow these steps to run the app directly on Ubuntu without Docker.

1. Update Packages & Install Prerequisites

Ensure standard system tools and Node.js v20.x or higher are installed.

# Update Ubuntu package lists
sudo apt update && sudo apt upgrade -y

# Install curl, git, and build essentials
sudo apt install -y curl git build-essential

# Install Node.js LTS (v20.x) via NodeSource
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Verify installation versions
node -v
npm -v

2. Clone or Copy the Project

Navigate to the project root directory:

cd /path/to/strandsAgentDemo-main

3. Install Project Dependencies

npm install

Note: The project includes a root .npmrc with legacy-peer-deps=true so @strands-agents/sdk installs cleanly alongside its optional peer dependencies.

4. Configure Environment Variables

cp .env.example .env

Edit .env and set your API credentials.

5. Run the Development Server

This starts SvelteKit’s unified dev server for both the UI and API routes:

npm run dev

Open the app at:

• Dev URL: http://localhost:3000

To use a different port:

npm run dev -- --port 5173

6. Build and Run in Production Mode

Compile the client and server bundles with SvelteKit’s Node adapter, then start the production server:

npm run build
npm run start

Open the app at:

• Production URL: http://localhost:3000

For production, export environment variables in your shell or pass them through your process manager. The Node adapter reads PORT (default 3000) and HOST (default 0.0.0.0).

---

🐳 Run Locally on Ubuntu Linux (Docker)

The included Dockerfile builds a production image on Ubuntu 22.04 with Node.js 20, compiles the SvelteKit app, and runs the Node adapter output from build/index.js.

1. Install Docker on Ubuntu

sudo apt update
sudo apt install -y ca-certificates curl gnupg

# Add Docker's official GPG key and repository
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Optional: run Docker without sudo
sudo usermod -aG docker "$USER"
newgrp docker

docker --version

2. Build the Docker Image

From the project root:

cd /path/to/strandsAgentDemo-main
docker build -t strands-agent .

3. Start the Container

Map container port 3000 to your host and provide API credentials as environment variables:

docker run -d \
  --name strands-agent-container \
  -p 3000:3000 \
  -e OPENAI_API_KEY="your-actual-api-key-here" \
  -e OPENAI_BASE_URL="https://openrouter.ai/api/v1" \
  strands-agent

If you omit OPENAI_API_KEY, the UI still loads, but you must enter a key in the sidebar before chat requests will work.

4. Access the Web App

Open:

• http://localhost:3000

Check container health:

curl http://localhost:3000/api/health

5. View Logs, Stop, and Remove the Container

# Follow application logs
docker logs -f strands-agent-container

# Stop and remove the container
docker stop strands-agent-container
docker rm strands-agent-container

Optional: Run with an Env File

Instead of passing secrets on the command line, mount a local .env file:

docker run -d \
  --name strands-agent-container \
  -p 3000:3000 \
  --env-file .env \
  strands-agent

---

🛠️ Features Overview

• Strands Agents SDK: Server-side orchestration in src/lib/server/agent.ts uses Agent, OpenAIModel, and agent.stream() with a 6-turn limit. Tools are declared in src/lib/server/strands-tools.ts via Strands tool() + Zod schemas.
• OpenAI-compatible models: Works with OpenRouter or any OpenAI-compatible API (OPENAI_BASE_URL, OPENAI_API_KEY).
• SvelteKit server routes: All model calls run inside /src/routes/api/* so API keys never reach the browser.
• Reasoning trail UI: The chat timeline renders streamed Strands events (model turns, tool calls, tool output, errors) in ReasoningView.svelte.
• Svelte 5 runes: Uses $state, $derived, and $effect for reactive UI updates and chat session persistence in localStorage.
• Git leak protection: .gitignore excludes .env files from commits.

---

🧠 Why is the Build Process Long in Sandbox?

If you notice that npm run build or the workspace compilation takes several seconds or minutes, this is entirely normal and expected. Here is why:

1. Virtualized Container Resource Constraints: In online sandboxes and cloud environments, resources (CPU, RAM, Disk I/O) are shared across multiple tenants. Node compilation is highly CPU-bound and Disk I/O-intensive, which slows down during high container concurrency.
2. SvelteKit Double Compile Phase: During vite build, Vite compiles two separate bundles: a client-side bundle (for the browser UI) and a server-side bundle (for SSR/node-adapter runtime handling).
3. Tailwind compilation & post-processing: The Tailwind CSS engine scans the project for classes, transforms them, and optimizes them into a single CSS payload for compression.
4. Adapter Optimization: SvelteKit's Node adapter post-processes the compiled bundles into a standalone entrypoint in the build/ directory.