Stark Industries HQ - Agentic Email Assistants

A Vercel template for spinning up named AI assistants that each have their own email address. They coordinate over email with real people, read their own inbox, and execute end-to-end - Friday plans a dinner with three friends and books the restaurant; Pepper sources quotes from vendors and confirms the booking; Happy triages your inbound mail and only escalates what's worth your attention.

Powered by AgentMail, the AI SDK, and Exa. Provider-agnostic - works with Anthropic or OpenAI, your pick.

TL;DR

1
pnpm install
2
cp .env.example .env.local           # then fill in the keys
3
pnpm dev

Open http://localhost:3000. Click an example scenario. Watch the assistant call tools, send real email, and stream replies back as participants respond - all visible in the inbox panel in real time.

The template ships with three Tony-Stark-flavored assistants:

What this template demonstrates

• Agent identity over email. Each assistant has a real, addressable inbox. People can CC them, reply to them, and treat them as participants - not as a chatbot widget.
• Real-time inbox UI. Threads, messages, and live updates streamed from AgentMail's WebSocket and rendered Gmail-style.
• Streaming agent loop with tool calls. The chat panel renders text and tool calls (reading inbox…, sending email…) as the assistant works through a multi-step plan.
• Idempotent provisioning. Restarting the dev server doesn't create duplicate inboxes - each assistant's id is passed as AgentMail's clientId.
• Role-gated tools. Friday and Pepper share the outbound toolset; Happy additionally gets block_sender, allow_sender, list_filters as the gatekeeper.
• Modal thread viewer with quoted-reply collapse (anything after On … wrote: is hidden behind a ··· pill).
• No database. Assistants live in lib/assistants-seed.ts as code. AgentMail is the persistence layer for everything email-shaped.

How it works

1
┌────────────────────────────────────────────────────────────┐
2
          │                       Browser (Vercel)                     │
3
          │                                                            │
4
          │  ┌─────────┐  ┌─────────┐  ┌─────────┐                     │
5
          │  │ Friday  │  │ Pepper  │  │  Happy  │  ← all 3 mounted,   │
6
          │  │  panel  │  │  panel  │  │  panel  │    CSS toggles      │
7
          │  └─────────┘  └─────────┘  └─────────┘    which is shown   │
8
          │       │  ▲          │ ▲          │ ▲                       │
9
          │       │  │ EventSource(SSE) per inbox (auto-reconnect)     │
10
          │       │  │  + useChat (Vercel AI SDK)                      │
11
          └───────┼──┼──────────┼─┼──────────┼─┼──────────────────────┘
12
                  ▼  │          ▼ │          ▼ │
13
          ┌────────────────────────────────────────────────────────────┐
14
          │           Next.js route handlers (Vercel functions)        │
15
          │                                                            │
16
          │  /api/chat       ←  streamText + tools, UI Message Stream  │
17
          │  /api/threads    ←  client.inboxes.threads.list            │
18
          │  /api/thread/X   ←  client.threads.get                     │
19
          │  /api/events     ←  SSE relay around                       │
20
          │                     client.websockets.connect              │
21
          └────────────────────────────────────────────────────────────┘
22
                                       │
23
                                       ▼  AgentMail WS + REST
24
          ┌────────────────────────────────────────────────────────────┐
25
          │                       AgentMail                            │
26
          │   inboxes, threads, messages, lists, real-time events      │
27
          └────────────────────────────────────────────────────────────┘

Prerequisites

• Node.js 22.x (or whatever your Next 16 deployment target requires).
• pnpm (the template uses pnpm lockfile, but npm / yarn / bun work fine - just regenerate the lock).
• An AgentMail account with at least one verified domain (dashboard). Without a verified domain, assistants provision under the shared agentmail.to subdomain, where common usernames like friday are already globally claimed (the template's suffix-retry logic handles that, but you'll get friday-3oac@agentmail.to instead of friday@yourdomain.com).
• An AI provider API key - either Anthropic (console.anthropic.com) or OpenAI (platform.openai.com). Pick whichever you already have; toggle via AI_PROVIDER env.
• An Exa API key (dashboard.exa.ai).

Quick start

1
git clone https://github.com/agentmail-to/agentmail-template-starkhq
2
cd agentmail-template-starkhq
3
pnpm install
4
cp .env.example .env.local
5
# fill in AGENTMAIL_API_KEY, AGENTMAIL_DOMAIN, your AI provider key
6
# (ANTHROPIC_API_KEY or OPENAI_API_KEY), EXA_API_KEY, and PRINCIPAL_EMAIL
7
pnpm dev

Open http://localhost:3000.

Deploy to Vercel

Deploy

No database to provision. Just paste the five environment variables when prompted.

Environment variables

Missing keys surface as clear errors in the UI (Missing required env var: …) rather than silently no-op'ing. There is no "demo mode" - the template assumes you've configured what it needs.

Stack & tools

WebSocket best practices (and what they look like here)

Realtime on Vercel serverless has two big constraints:

1. You can't host a long-lived WebSocket server in a Next.js route handler - serverless functions terminate per request.
2. You can't safely embed your long-lived AgentMail API key in the browser - it has full org access.

The standard answer is a server-side WS → browser-side SSE relay, with the realtime service (AgentMail) holding the durable connection. That's what this template does:

1
AgentMail WS  ◄── server-side ──►  SSE stream  ◄── EventSource (auto-reconnect)
2
(durable)         Next.js route                    in browser
3
                  (one per assistant)

Best practices implemented

What the WS protocol looks like

The AgentMail WS speaks JSON. After connect, the server sends:

1
{ "type": "subscribe",
2
  "inbox_ids": ["friday-3oac@agentmail.to"],
3
  "event_types": ["message.received", "message.sent", "message.delivered"] }

Each event arrives as:

1
{ "type": "event",
2
  "eventType": "message.received",
3
  "eventId": "...",
4
  "message": { ... },
5
  "thread":  { ... } }

We forward each event as a single SSE frame (data: <json>\n\n) to the browser, which deserializes and upserts the thread into the inbox list.

Why not "real" WebSockets browser-to-server?

Two reasons. (1) Vercel route handlers can't accept WS upgrades - they're request/response only. (2) The user-facing UX is identical: SSE gives you server-push, EventSource auto-reconnects, no manual handling needed. The transport difference is invisible. If you ever need full duplex from the browser (rare for an inbox UI), you'd run the WS layer outside Vercel (Cloudflare Workers, Fly, Railway, etc.).

License

MIT - go build cool things.