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.
Getting started 🟢
Goal: put a talking 3D guide on a web page in about five minutes, with no build tools, no framework, and no account.
If you can edit an HTML file, you can do this.
Step 1 — Add one line
Open the HTML file for any page and paste this just before the closing
</body> tag:
<script
src="https://unpkg.com/@three-ws/page-agent/dist/page-agent.global.js"
data-page-agent
data-avatar="nova"
data-auto-narrate
defer></script>
Save it. Open the page in your browser.
That's the whole thing. A rigged avatar named Nova docks in the bottom-right corner and starts talking visitors through your page. A control bar lets them play/stop, mute, change the guide, or minimize it.
What just happened? The
data-page-agentattribute tells the script to auto-start. The otherdata-*attributes are its settings. The/dist/page-agent.global.jsbuild bundles everything it needs (including the 3D engine), so there's nothing else to install.
Hear nothing?
Browsers block audio until the visitor interacts with the page (a security rule — not a bug). Click anywhere, or click ▶ in the control bar. The avatar's mouth moves and captions show even before audio is allowed, so the guide never looks frozen. More in Troubleshooting.
Step 2 — Make it say what you want
By default the agent reads your page's headings and lead paragraphs. To control
exactly what it says, add a data-narrate attribute to any element:
<h1 data-narrate="Welcome! Let me show you around our new pricing page.">
Pricing
</h1>
<section data-narrate="Every plan includes unlimited projects and email support.">
…your normal content…
</section>
When the agent walks the page, it speaks the data-narrate text for those
elements (and highlights each one as it goes). Everything else is skipped. Full
details in Narrating your page.
Step 3 — Pick a different guide
There are nine rigged guides. Swap data-avatar to any id:
| id | who they are |
|---|---|
sol |
Calm, clear product guide (default) |
nova |
Upbeat, friendly host |
vera |
Composed, professional (British voice) |
atlas |
Confident, grounded |
echo |
Neutral, even-keeled |
lumen |
Minimal studio presenter |
kai |
Playful robot sidekick |
mira |
Expressive, full-body |
pax |
Laid-back explainer |
Want to offer only a few in the visitor's picker? List them:
<script
src="https://unpkg.com/@three-ws/page-agent/dist/page-agent.global.js"
data-page-agent
data-avatar="sol"
data-agents="sol,nova,kai"
data-auto-narrate
defer></script>
Step 4 — Position and behavior
Every setting is a data-* attribute. The common ones:
<script
src="https://unpkg.com/@three-ws/page-agent/dist/page-agent.global.js"
data-page-agent
data-avatar="vera"
data-position="bottom-left" <!-- bottom-right | bottom-left | top-right | top-left -->
data-greeting="Hi there — need a hand finding anything?"
data-collapsed <!-- start as a small pill the visitor can open -->
defer></script>
data-greeting="…"— speak a single welcome line on load (instead of touring the whole page).data-auto-narrate— tour the page on load. Add a value to narrate only part of it:data-auto-narrate=".tour-section"(a CSS selector).data-collapsed— start minimized as an "Ask a guide" pill.data-muted— start muted (the avatar still mouths the words + captions show).data-no-picker— hide the "change guide" button.data-no-controls— hide the whole control bar.
The complete attribute list is in the API reference.
When you outgrow the script tag
The script tag is perfect for static sites, landing pages, docs, and no-code builders. The moment you want to react to what the agent does — trigger narration on a button click, log which sections visitors heard, swap the guide based on the page — move up to the programmatic API:
<script type="module">
import { PageAgent } from 'https://unpkg.com/@three-ws/page-agent/dist/page-agent.mjs';
// (note: the .mjs build needs `three` available — see the frameworks guide)
const guide = new PageAgent({ agent: 'atlas', autoNarrate: true });
guide.on('segment', ({ text, el }) => {
console.log('now reading:', text);
});
document.querySelector('#help').addEventListener('click', () => {
guide.narrate('Sure — this button saves your draft.', { interrupt: true });
});
</script>
→ Continue with Framework integration for a clean setup
in React, Vue, Next, and friends, or the API reference for
everything PageAgent can do.
Cheat sheet
<!-- Simplest possible -->
<script src="https://unpkg.com/@three-ws/page-agent/dist/page-agent.global.js"
data-page-agent defer></script>
<!-- Tour the page with a chosen guide, bottom-left -->
<script src="https://unpkg.com/@three-ws/page-agent/dist/page-agent.global.js"
data-page-agent data-avatar="nova" data-position="bottom-left"
data-auto-narrate defer></script>
<!-- Greet only, muted, start collapsed, no picker -->
<script src="https://unpkg.com/@three-ws/page-agent/dist/page-agent.global.js"
data-page-agent data-greeting="Welcome back!" data-muted
data-collapsed data-no-picker defer></script>
Next: Narrating your page →