Skip to content

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.

4.9 KB
Raw Blame

Recipes 🟡

Copy-paste solutions to common needs. Each assumes a guide instance:

import { PageAgent } from '@three-ws/page-agent';
const guide = new PageAgent({ agent: 'sol' });

Trigger the tour from a button (not on load)

Leave autoNarrate off and start it on demand:

const guide = new PageAgent({ agent: 'nova', collapsed: true });
document.querySelector('#take-tour').addEventListener('click', () => {
  guide.narratePage({ greet: true });
});

"Explain this" buttons

function explain(text) {
  return () => guide.narrate(text, { interrupt: true });
}
document.querySelector('#save').addEventListener('click', explain('This saves a draft — it won't publish.'));
document.querySelector('#publish').addEventListener('click', explain('Publish makes your changes live for everyone.'));

Only tour first-time visitors

if (!localStorage.getItem('toured')) {
  guide.on('ready', () => guide.narratePage({ greet: true }));
  localStorage.setItem('toured', '1');
}

Track which segments visitors actually hear (analytics)

guide.on('segment', ({ text, el }) => {
  analytics.track('guide_segment', { id: el.id || el.tagName, text: text.slice(0, 80) });
});
guide.on('state', (s) => analytics.track('guide_' + s));   // speaking / idle

Sync your UI to the speaking state

guide.on('state', (s) => {
  document.body.classList.toggle('guide-speaking', s === 'speaking');
});
.guide-speaking #hero { filter: brightness(0.9); transition: filter .3s; }

Route-aware narration in a SPA

Re-tour the new view whenever the route changes:

function onRouteChange() {
  guide.stop();
  guide.narratePage({ selector: '[data-view]:not([hidden]) [data-narrate]' });
}
// React Router: useEffect on location. Vue Router: router.afterEach. etc.

Multi-language narration

Pick the agent's voice via the catalog's voice profile, and feed translated copy. The simplest approach is your own strings keyed by document.documentElement.lang:

const COPY = {
  en: ['Welcome — let me show you around.', 'Start by connecting your wallet.'],
  es: ['Bienvenido — te muestro el sitio.', 'Empieza conectando tu cartera.'],
};
const lines = COPY[document.documentElement.lang] || COPY.en;
guide.on('ready', async () => { for (const l of lines) await guide.narrate(l); });

Voice availability is the browser's, not ours — the visitor must have a voice for that language installed. See Troubleshooting.

Pause speech when the tab is hidden

document.addEventListener('visibilitychange', () => {
  if (document.hidden) guide.stop();
});

Restrict and brand the picker

const guide = new PageAgent({
  agent: 'vera',
  agents: ['vera', 'atlas', 'sol'],   // only these appear in the picker
});

For a custom title/subtitle or a filtered roster, build your own picker — see Building blocks.

Switch guide based on context

// Match the agent to dark/light mode, locale, persona, A/B bucket, anything.
const prefersDark = matchMedia('(prefers-color-scheme: dark)').matches;
guide.setAgent(prefersDark ? 'echo' : 'nova');

Respect a "reduce/disable" preference

const wantsQuiet = matchMedia('(prefers-reduced-motion: reduce)').matches
  || localStorage.getItem('guide-off') === '1';

const guide = new PageAgent({
  agent: 'sol',
  muted: wantsQuiet,        // visual only, no audio
  autoNarrate: !wantsQuiet, // don't auto-tour if they opted out
});

(The avatar already softens its motion under prefers-reduced-motion.)

Lazy-load the agent (defer the 3D cost)

Only construct it when the visitor is likely to want it — on idle, first scroll, or a click:

let guide;
function ensureGuide() {
  if (!guide) guide = new PageAgent({ agent: 'nova' });
  return guide;
}
requestIdleCallback(ensureGuide);                 // or:
addEventListener('scroll', ensureGuide, { once: true });

With the script tag, the global build is one request; load it defer or inject the tag on interaction.

Read a form error aloud

form.addEventListener('invalid', (e) => {
  guide.narrate(`Heads up: ${e.target.validationMessage}`, { interrupt: true });
}, true);

Clean teardown (SPA / component unmount)

// React: return () => guide.dispose() from useEffect
// Vue: onBeforeUnmount(() => guide.dispose())
// Vanilla:
window.addEventListener('beforeunload', () => guide.dispose());

Chain narration with awaits

guide.on('ready', async () => {
  await guide.narrate('Three things to know.');
  await guide.narrate('One: it's all client-side.');
  await guide.narrate('Two: pick any guide. Three: it speaks your copy.');
});

More patterns welcome — send a PR (see CONTRIBUTING).

← Docs home · API reference → · Troubleshooting →