Stark Industries HQ is a Vercel template for spinning up named AI assistants — Friday, Pepper, and Happy — each with its own real email address and inbox, that coordinate with humans over email and execute multi-step tasks end-to-end. Built around AgentMail for email infrastructure, the Vercel AI SDK for the agent loop, and Exa for web search, the template ships as a Next.js 16 App Router application with three simultaneously mounted assistant panels.
What is Stark Industries HQ?
Stark Industries HQ is a boilerplate that demonstrates how to give AI agents an email identity rather than a chatbot widget. It takes environment variables for AgentMail, an AI provider (Anthropic or OpenAI), and Exa, and outputs a local or deployed web app with a Gmail-style inbox panel, a streaming chat panel that renders tool calls, and SSE-driven live updates. The template is created by AgentMail, and all assistant definitions live in TypeScript code in lib/assistants-seed.ts — there is no database.
Key Features
- Three role-specific assistants — Friday (multi-party scheduling), Pepper (vendors and operations), and Happy (inbound triage and security) each with different tool surfaces: send, reply, read, search, escalate; Happy adds block_sender, allow_sender, and list_filters as the inbound gatekeeper.
- Real-time inbox UI — Threads, messages, and live updates stream from AgentMail's WebSocket via a server-side SSE relay; a status dot shows Live / Reconnecting / Connecting / Disconnected states.
- Streaming agent loop with tool calls — The chat panel renders both text and tool-call activity (e.g., "reading inbox…", "sending email…") as the assistant works through a plan.
- Provider-agnostic AI — Defaults to Anthropic Claude (
claude-sonnet-4-6); setAI_PROVIDER=openaito use OpenAI'sgpt-4o, with model override viaAI_MODEL_ID. - Idempotent provisioning — Each assistant's id is passed as AgentMail's
clientId, so restarting the dev server does not create duplicate inboxes. - No database — Email state persists in AgentMail; assistants are code, making the template easy to extend and redeploy.
- WebSocket best practices — Durable AgentMail WS lives server-side, relayed to the browser as SSE with a 15-second heartbeat, abort on disconnect, and native EventSource auto-reconnect.
- Clean architecture — Next.js route handlers (
/api/chat,/api/threads,/api/thread/X,/api/events) separate the AI loop, REST reads, and SSE events.
Who is it for?
- Developers building AI agents that need to send, receive, and reason over email — this template is a working reference for AgentMail's SDK, including WebSocket subscription and idempotent inbox provisioning.
- Product teams prototyping AI operations or customer support agents — e.g., Happy triaging inbound mail and escalating to a principal email, or Pepper sourcing vendor quotes.
- Hackathon and demo builders — the project includes runnable example scenarios (Friday plans a dinner with three friends and books the restaurant) and deploys to Vercel with no database provisioning.
What can you do with Stark Industries HQ?
- Automate personal scheduling: Friday coordinates with friends over email threads, searches for venues via Exa, and sends confirmations — all from its own addressable inbox.
- Delegate vendor research: Pepper sources quotes from vendors and confirms bookings, with escalations forwarded to your principal email when human review is needed.
- Gatekeep your inbox: Happy applies block and allow list filters, reads inbound mail, and only escalates what is worth your attention.
How does Stark Industries HQ work?
The workflow is: install dependencies, copy .env.example to .env.local, fill in AGENTMAIL_API_KEY, AGENTMAIL_DOMAIN, an Anthropic or OpenAI key, EXA_API_KEY, and PRINCIPAL_EMAIL, then run pnpm dev. The app provisions each assistant's inbox through AgentMail, opens a server-side WebSocket that is piped to the browser as an SSE stream, and uses the Vercel AI SDK's useChat for the streaming agent loop. Missing environment variables surface as clear errors in the UI rather than silently failing.
FAQ
Does Stark Industries HQ require a database?
No. There is no database. Assistant definitions are TypeScript code, and all email-shaped state (inboxes, threads, messages) is persisted by AgentMail.
Which AI providers are supported?
Anthropic and OpenAI. The default is Anthropic Claude (claude-sonnet-4-6); set AI_PROVIDER=openai to switch to OpenAI's gpt-4o. You only need one provider API key.
What are the prerequisites to run it?
You need Node.js 22.x, pnpm (or npm/yarn/bun), an AgentMail account with at least one verified domain, an AI provider API key, and an Exa API key. Without a verified domain, assistants use the shared agentmail.to subdomain where common usernames may already be claimed, so you get suffixed addresses like [email protected].
Is there a demo mode that works without configuration?
No. The template intentionally has no demo mode — missing keys display descriptive errors in the UI. It assumes you have configured AgentMail, an AI provider, and Exa.
How does real-time email work on serverless Vercel functions?
Because Vercel route handlers cannot accept WebSocket upgrades, the template uses a server-side WebSocket to AgentMail relayed to the browser as SSE. EventSource auto-reconnects if the function times out, and a REST call on first mount populates the inbox before live events start.
