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.
Template catalog
| Id | Seeded on create | Summary |
|---|---|---|
blank | No | Empty project — you upload your first build. |
voice-starter | Yes | Starter agent covering every speech event type. |
echo | Yes | Echo debug — voice finals plus DataChannel chat. |
echo-dc | Yes | Data-channel echo only — no TTS. |
world-sync | Yes | Simple data-only pose sync — JSON onDataChannelMessage, one in-memory agent, no Redis. See Data-only world sync. |
world-sync-binary | Yes | Binary pose sync — onDataChannelBinary plus broadCastBinaryToClients with a 12-byte ArrayBuffer. See Data-only world sync. |
game-sync | Yes | Authoritative multi-object sync sample for real-time games. Live worlds cap at 25 objects. Uses binary world snapshots and Project Redis when AGENT_REDIS_URL is set. See Data-only world sync. |
voice-showcase | Yes | Conversational demo — greeting, name, menu (weather, count, recipe, fun fact). Available in the dashboard create-project picker and seeded on create from the prebuilt @voicethere/agent bundle. |
recording-consent | Yes | Consent on session connect, pause around name and birthdate, resume only when allowed. Available in the dashboard create-project picker and seeded on create from the prebuilt @voicethere/agent bundle. See Conversation recording. |
positional-tts | Yes | Voice+Data demo — TTS orbits each listener with per-client setTtsPose. See Positional mix & orbiting TTS. |
spatial-showcase | Yes | Voice+Data spatial audio showcase — orbiting sine tone and TTS, positional clip soundboard, and proximity room. Visitors join with { "type": "join", "demo" } on the DataChannel. See Spatial audio showcases. |
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.
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.