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.

5.6 KB
Raw Blame

@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.js build 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.