Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
@three-ws/page-agent — Documentation
A rigged 3D AI agent that talks your visitors through any web page. This is the full documentation. If you just want the elevator pitch and a one-line install, the package README has it.
New here? Start with Getting started. It takes ~5 minutes and assumes nothing.
Learning path
The docs are tiered. Pick your level — each guide links forward to the next.
🟢 Basic — "I want a guide on my site, today."
| Guide | What you'll learn |
|---|---|
| Getting started | Add the agent with one script tag. No build step, no framework, no account. |
| Narrating your page | Make the agent read the right things, in the right order, in your own words. |
| Troubleshooting & FAQ | "No voice?" "Avatar won't load?" — the usual snags and their fixes. |
🟡 Medium — "I'm wiring this into a real app."
| Guide | What you'll learn |
|---|---|
| Framework integration | Clean setup for React, Next.js, Vue, Svelte, Astro, and no-code (Webflow/WordPress). |
| Recipes | Copy-paste solutions: analytics, gated tours, multi-language, route-aware narration, and more. |
| API reference | Every option, method, event, and type — the complete contract. |
🔴 Advanced — "I want to push it further."
| Guide | What you'll learn |
|---|---|
| Custom avatars | Bring your own rigged GLB. Rigging, visemes, idle/talk clips, framing. |
| Building blocks | Drop the default UI. Compose AvatarStage, SpeechNarrator, AvatarPicker, and the lipsync engine into your own experience. |
| Contributing | Add an agent, write a lipsync driver, ship a framework adapter — and the open roadmap of things worth building. |
The three ways to use it
Everything in these docs is one of three integration styles. They share the same engine; you can move between them as your needs grow.
┌─────────────────────────────────────────────────────────────────┐
│ 1. Zero-JS script tag <script ... data-page-agent> │ 🟢 basic
│ Drop one tag. Done. │
├─────────────────────────────────────────────────────────────────┤
│ 2. <page-agent> element <page-agent auto-narrate> │ 🟢 basic
│ Declarative HTML. Methods + events on the element. │
├─────────────────────────────────────────────────────────────────┤
│ 3. new PageAgent(config) import { PageAgent } │ 🟡 medium
│ Full programmatic control: narrate(), events, live swaps. │
├─────────────────────────────────────────────────────────────────┤
│ 4. Building blocks AvatarStage + SpeechNarrator + … │ 🔴 advanced
│ Your own UI around the rendering/speech/lipsync engine. │
└─────────────────────────────────────────────────────────────────┘
Mental model in 30 seconds
PageAgent is a thin controller that composes four pieces:
PageAgent ─┬─ AvatarStage three.js scene. Loads the rigged GLB, frames it
│ (bust/upper/full), keeps it alive with an idle
│ clip or procedural breathing + blink.
├─ SpeechNarrator A speech queue on the Web Speech API. Picks a
│ voice per agent and drives lipsync on the frame loop.
├─ AvatarPicker Accessible modal so the *visitor* chooses a guide.
└─ lipsync text → timed visemes → morph-target influences.
No backend, no API key, no audio files. Speech is the browser's
SpeechSynthesis; lipsync is a deterministic text-to-viseme heuristic advanced
on three.js's render loop. When speech is unavailable or muted, the avatar still
"talks" visually and captions render — narration never silently stalls.
Requirements
- A modern browser with WebGL. (Speech is best in Chrome/Edge/Safari; see Troubleshooting for the Firefox caveat.)
three>= 0.150 as a peer dependency only for the bundler/ESM path. The CDN/dist/page-agent.global.jsbuild inlines three, so the script-tag path needs nothing.
Where the assets come from
Avatars stream from the public three.ws asset host
(https://three.ws/avatars/*.glb) by default — real, ready to use, no setup. To
self-host, point assetBase (or an agent's url) at
your own CDN. See Custom avatars.
Questions, bugs, ideas → open an issue or read CONTRIBUTING. Part of the three.ws platform for building, animating, rigging, and monetizing 3D AI agents.