Building a good AI chat experience is more than just calling an LLM. You need streaming, stateful threads, memory / retrieval, tool calling, and enough guardrails (rate limits + usage tracking) to make it shippable.
That's why Convex Agents is interesting: it's a component that gives you a structured way to build agentic chat experiences on Convex, with persisted threads/messages and built-in context retrieval (hybrid vector/text search) — plus workflows, tool calls, and convenient debugging.
This repository is a production-leaning example: an embeddable chat widget for Next.js (or any React app) built on Convex Agents, with a polished UI and the "real-world" pieces most demos skip.
The UI uses HeroUI for a modern, polished look. Voice mode is enabled via AssemblyAI (record → upload → transcribe → continue the chat). You also get a configuration panel for tuning a specific chat (system prompt, tools, voice, streaming) and a usage table that tracks LLM tokens + speech-to-text seconds for cost-aware deployments.
What's included
- Browser widget (clean, responsive, ready to embed)
- Streaming chat powered by Convex Agents (threads + retrieval + workflows)
- Tool calling examples (extra context, geocoding, weather, YouTube transcript summarization)
- Voice messages: record → upload to Cloudflare R2 → transcribe with AssemblyAI → continue the chat
- Usage tracking (LLM tokens + speech-to-text seconds), so you can wire it into billing later
Tech stack
Next.js
App Router based UI and a clean foundation for an embeddable widget.
Convex
Database + functions with real-time queries, plus Convex Agents for threads, retrieval, tool calling and workflows — the backend that powers the widget.
OpenRouter
Unified access to multiple LLM providers (OpenAI optional).
AssemblyAI
Speech-to-text for voice messages.
Cloudflare R2
Temporary audio storage via presigned uploads (keeps large files off your app server).
Run it locally
Install
npm install
Start Convex
npx convex dev
Start Next.js
npm run dev
Open source
The complete codebase is available on GitHub under the MIT license — check out the repo.