Agent templates
When you create a project in the dashboard, you pick an agent template. Templates with a pre-built bundle are seeded on create — the platform uploads and promotes a starter agent.js from the public @voicethere/agent package. Choose blank when you will build and upload your own bundle from scratch.
The CLI does not accept a --template flag on projects create. Use the dashboard picker for seeded starters, or copy a template locally and deploy with the CLI.
After create, edit seeded template source in the dashboard Code tab — see Dashboard code editor. Any voice agent can call play() for clip playback — see Clip playback.
Where to configure
- Dashboard: Create project → Template dropdown. Optional toggles: relay speech events, chat enabled, voice enabled, echo prefix.
- CLI: No template selector — create with
voicethere projects create, then build, upload, promote, and deploy your bundle.
Available templates
The list follows the installed @voicethere/agent release. If a later release removes a template, existing projects keep it and show it as retired; new projects can't pick it.
| Template id | Name | What it does |
|---|---|---|
blank | Blank | Empty project — you upload your first build. |
echo | Echo (voice + chat) | Echo debug agent with voice finals and DataChannel chat. |
echo-dc | Echo debug (DC events only) | Data-channel-only echo agent without TTS. |
language-switch | Language switch | Detects the caller's language and switches speech recognition and voice mid-call, with a holding message and an unavailable notice. See Voice language switch. |
voice-starter | Voice starter | Starter agent covering every speech event. |
world-sync | World sync (JSON) | Data-only pose broadcast over onDataChannelMessage. One agent, no Redis. See Data-only world sync. |
world-sync-binary | World sync (binary) | Data-only ArrayBuffer poses with onDataChannelBinary. One agent, no Redis. See Data-only world sync. |
game-sync | Game sync (multi-object DC) | Authoritative multi-object sync sample for real-time games. See Data-only world sync. |
voice-showcase | Voice showcase | Conversational demo: greeting, name, menu (weather, count, recipes, fun facts). |
recording-consent | Recording consent | Asks recording consent on connect, pauses for name and birthdate, resumes only if allowed. See Conversation recording. |
positional-tts | Orbiting TTS | Voice+Data demo: a TTS speaker circles each listener with per-client poses. See Positional mix & orbiting TTS. |
spatial-showcase | Spatial audio showcase | Voice+Data demo: orbiting sine tone and TTS, positional soundboard, and a proximity room via DataChannel join. See Spatial audio showcases. |
webhooks | Inbound webhooks | Verifies inbound webhooks with HMAC, then fans out over DataChannel and speech. See Webhooks. |
webhooks-redis | Inbound webhooks (Redis) | Webhook handler with a Redis shared counter and DataChannel fan-out. See Webhooks. |
Seeded package.json
When a template is seeded on create, the platform also loads a root package.json into the Code tab workspace alongside the template TypeScript. It pins @voicethere/agent and includes npm scripts for local build, verify, upload, deploy, and source sync — the same files you see in the dashboard can be used with @voicethere/cli once the project is linked.
Redis-backed templates (game-sync, redis-sync, webhooks-redis) also declare ioredis in dependencies. The blank template does not seed source or package.json — use Add package.json in the Code tab when you are ready.
game-sync caps live worlds at 25 objects and uses Project Redis when AGENT_REDIS_URL is set.
Create-time options
Dashboard template settings (stored on the project):
relay_speech_events— forward speech pipeline events to the agent (default on).chat_enabled— DataChannel text chat path.voice_enabled— voice / STT/TTS path.echo_prefix— prefix for echo templates (e.g.you said:).
Local copy from @voicethere/agent
Product templates live as TypeScript sources under templates/<id>/ in the agent repo (for example templates/echo/agent.ts; world-sync examples are templates/world-sync/and templates/game-sync/). Clone or browse:
git clone https://github.com/voicethere/agent.git cd agent npm install npx @voicethere/agent build --entry templates/echo/agent.ts --outfile dist/agent.js
Build, verify, upload, deploy
npx @voicethere/agent verify and dashboard upload run the same checks. With @voicethere/agent 0.5.1+, a bundle may register only onWebhook (inbound HTTP) or only onSessionStart (session bootstrap) — you do not need speech or DataChannel handlers for verify to pass. See Inbound webhooks for webhook-only agents.
# In your agent repo (linked with voicethere projects use) npm install @voicethere/agent @voicethere/cli npx @voicethere/agent build --entry src/agent.ts --outfile dist/agent.js voicethere build validate voicethere build upload -m "From echo template" voicethere build list voicethere build promote <build-uuid> voicethere deploy --wait
deploy --wait promotes when needed and rolls the active build to cloud runners. See Quickstart for the full path.