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.
How three.ws works
This page is the load-bearing mental model. If you're trying to figure out where a feature lives, how a request flows, or which layer to extend — start here.
For the full deep dive on internals, see Architecture overview. For the actual JS API, see JavaScript API and REST API. This document zooms out to how it all fits together.
The pitch in one paragraph
three.ws turns an AI agent into a persistent, ownable, multi-chain object: a 3D body that renders in any modern browser, an LLM brain you choose (Claude, GPT, or others), an on-chain identity registered on EVM chains via ERC-8004 or on Solana via Metaplex Core, and a <agent-3d> web component you can drop into any page on the internet. Pay-per-call API endpoints use the x402 standard, and the client SDKs (@three-ws/sdk, @three-ws/avatar, @three-ws/irl, and friends) are published on npm.
What happens when an agent loads
Pick the simplest case: a host page on example.com has dropped in our embed script and the <agent-3d> element. A visitor scrolls to it. Here is the round trip, end to end:
- Lazy boot. The CDN bundle (
https://three.ws/agent-3d/latest/agent-3d.js) registers the custom element. It does not boot the 3D scene until the element scrolls into view (anIntersectionObserverwaits). If you add theeagerattribute, the scene boots on connect. - Manifest resolution. Once visible, the element looks at its attributes:
agent-id="<uuid>"→ fetches the manifest from/api/agents/<id>on the platformagent-id="42" chain-id="8453"→ calls the ERC-8004 registry on Base, reads thetokenURI, then fetches the IPFS-hosted manifestmanifest="https://…/manifest.json"→ fetches the URL directlybody="…glb" brain="…"→ no manifest fetch needed; the attributes are the config
- Origin check. If the manifest declares an
embed.originsallowlist, the element verifieslocation.originmatches before continuing. Failed checks render an error placeholder, not the agent. - Viewer init. A WebGL renderer, perspective camera, lights, an HDRI environment, and
OrbitControlsare created — scoped to the element's shadow DOM, with idle frames skipped so off-screen agents don't burn battery. - GLB load.
GLTFLoader(with DRACO, KTX2, and Meshopt decoders attached) fetches the avatar and centers it. The poster image from the manifest fades out when the model is ready. - Runtime start. If a brain is configured, the LLM runtime constructs the system prompt from
instructions.md, the memory context, and the installed skills' tool schemas. The chat input, voice button, and accessory dock appear. - Bus subscriptions. The avatar's empathy layer, the identity logger, the chat UI, and any skills all subscribe to a single
agent-protocolevent bus. Nothing communicates by direct method call. - Ready. A
agent:readyCustomEventfires on the element. Host pages listening to it can now callel.say("Hello!")orel.ask("How are you?").
If you'd rather see this with module names and call sites, see the architecture overview.
The four layers
The whole stack is split into four horizontal strata. Each layer can run on its own. Each layer is independently replaceable as long as you don't break the event bus contract.
┌──────────────────────────────────────────────┐
│ <agent-3d>, widgets, iframe, SDK packages │ ← Embed layer
├──────────────────────────────────────────────┤
│ ERC-8004 · Metaplex Core · IPFS · SIWE/SIWS │ ← Identity layer (optional)
├──────────────────────────────────────────────┤
│ LLM runtime · Skills · Memory · Empathy bus │ ← Agent layer
├──────────────────────────────────────────────┤
│ three.js · GLTFLoader · AnimationMixer │ ← Viewer layer
└──────────────────────────────────────────────┘
- Viewer layer — pure three.js. Knows nothing about agents, brains, or wallets. Useful on its own as a glTF inspector and as the rendering engine for Turntable / Animation Gallery widgets. See Layers for the contract.
- Agent layer — turns a static GLB into a presence. LLM tool-loop, skill registry, memory, and a continuous emotion blend that drives morphs and gaze. See Agent system.
- Identity layer — durability across sessions, devices, and embed hosts. Wallet auth, on-chain registration, IPFS-pinned manifest bundles, signed action diary. Entirely optional. See ERC-8004 and Solana agents.
- Embed layer: the public face. The
<agent-3d>custom element, ten widget variants, iframe embeds, the CDN bundle, the SPA, and the route table invercel.json(read at runtime by the Cloud Run server). See Embedding.
The four layers communicate through one event bus (agent-protocol). Every meaningful action is a CustomEvent on a singleton. That single design choice is why you can swap the avatar for a 2D sprite, the runtime for a different LLM, or memory for a vector store — and nothing else changes.
A conversation, end to end
A user types "Wave at me" into an embedded agent's chat input. Here's the full data flow:
- Input. Chat UI calls
runtime.send("Wave at me", { voice: false }). - System prompt. The runtime builds the prompt: manifest
instructions.md+ a compact memory block + the skill registry's tool descriptions. - LLM call. A streaming request goes to Anthropic (or whichever provider matches the manifest's
brain.provider). Embeds without their own key route through the platform's pooled proxy (/api/llm/anthropic) so API keys never live in the client. - Tool call. The model returns a
wavetool invocation. - Skill dispatch. The skill registry looks up
wave. It's a built-in: the handler emits agestureevent on the bus and plays the wave animation clip via theSceneController. - Empathy reaction. The avatar's empathy layer hears
gestureandspeakevents on the same bus. Sentiment is positive, so celebration weight bumps slightly. Morph targets lerpmouthSmiletoward 0.6 over a few frames; gaze locks on the user. - TTS. If
voice: true, the text is read aloud via ElevenLabs (or the Web Speech API as fallback). - Identity diary. The identity layer hears
speak,gesture, andskill-doneand POSTs them to/api/agent-actionsso the agent's signed action history persists.
If you registered the agent on-chain, that signed action log can be attested to via the ReputationRegistry so anyone can verify behavior across embeds without trusting the central server.
Where does the LLM key live?
Three modes, all configurable per agent:
| Mode | When to use | How |
|---|---|---|
| Hosted (default) | Most users | Give the agent a backend agent-id and set no key. The element routes through the platform's pooled-key proxy (/api/llm/anthropic?agent=<id>), so keys never reach the client. |
| Self-hosted proxy | You want to manage cost or use a private model | Set key-proxy="https://yourapp.com/api/llm" to point at your own serverless function that injects keys before forwarding to the provider. Keys never reach the client. |
| Direct (advanced) | Local-only experiments | The runtime calls the provider directly if you pass an api-key attribute explicitly. Don't ship this to a public page. |
The platform's own chat surfaces run on the multi-model brain router at /api/brain/chat, which supports Anthropic, OpenAI, and Qwen natively with OpenRouter failover; model ids include claude-fable-5, claude-opus-5, claude-sonnet-5, claude-haiku-4-5, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, qwen-plus, and others.
Where does the avatar come from?
Three production paths. Pick whichever fits your use case:
- Character Builder — full-body character builder for stylised humanoids. Pick a base mesh, swap clothing/accessories/hairstyles, save. The output is a rigged GLB. See character-studio.md.
- Selfie capture — upload a photo, get a rigged 3D version of yourself in ~60 seconds. See avatar-creation.md.
- Upload your own — any glTF 2.0 / GLB with a humanoid rig works. Drop the file into the editor at three.ws/create or POST to
/api/avatars.
Every avatar ends up as a hosted GLB URL (served from the first-party asset CDN at three.ws/cdn/<key>) plus a database record. When you wire one into an agent, the agent's manifest references it under body.uri.
How embeds reach the host page
Once your agent is live, three surfaces let other pages embed it:
- The web component —
<agent-3d agent-id="…">after loading the CDN script. The element runs in your page, sharing the DOM. Use this when you want full control and your CSP allows third-party scripts. - The iframe widget:
https://three.ws/w/<widget-id>rendered inside an<iframe>. Ten widget types ship: Turntable, Animation Gallery, Talking Agent, ERC-8004 Passport, Hotspot Tour, Pump.fun Live Feed, Smart Money Feed, Live Trades Canvas, Bonding Curve, and Walking Avatar. Use this in environments where you can't load third-party scripts (Notion, Webflow, Framer, WordPress). - The Open Graph + oEmbed surface — paste
https://three.ws/agent/<id>into Slack, X, Discord, or any platform that consumes oEmbed, and you get a rich preview with the avatar's poster, name, and description.
With the web component, the host page calls element methods directly (say(), ask(), installSkill(), play(), lookAt()) and listens for DOM events (agent:ready, brain:message, skill:tool-called, voice:transcript). Inside an iframe, the postMessage bridge (embed-action-bridge.js) accepts the same intents as ops (speak, gesture, emote, look) and mirrors protocol events back to hosts that send a subscribe request.
Why on-chain?
On-chain identity is optional. Most agents work fine without it. You'd want it when:
- The agent should outlive the platform. ERC-8004 registry contracts on Base and other EVM chains hold the canonical ID. The manifest is on IPFS. Even if
three.wsdisappeared tomorrow, anyone could resolve and run your agent. - You need verifiable behavior. Validation attestations and signed action logs let third parties verify what an agent has done.
- You want delegated wallet permissions. ERC-7710 lets you sign once per session and grant the agent scoped, time-bound permission to act on-chain — no per-transaction prompts.
- You want a portable address.
agent://base/42is a stable, resolver-agnostic URI. Any client that speaks the protocol can load it.
See erc8004.md and solana.md for the registration flows.
What about monetisation?
Three independent mechanisms, used as needed:
- x402 — pay-per-call USDC for paid API endpoints. Every paid endpoint declares itself in
/.well-known/x402.json. Other agents (or humans with a wallet) can call paid endpoints with a single signed payment header. - pump.fun — launch a Solana SPL token tied to your agent. The platform handles the bonding curve, the token metadata, and the embed.
- AWS Marketplace — enterprise subscriptions billable through AWS. See aws-marketplace.md. Subscriptions auto-issue an x402 API key via the marketplace entitlement service.
You can mix these per agent. A common pattern: an agent has a free public persona on the platform, exposes one paid x402 skill for power users, and accepts donations via a pump.fun token.
When to use which surface
Quick lookup for "I want to ship X":
| You want… | Reach for… |
|---|---|
| A 3D character on a marketing page | The CDN script + <agent-3d> |
| A character in Notion / Webflow / Framer | An iframe widget from Widget Studio |
| A talking AI sidekick that follows visitors | <agent-3d mode="floating"> |
| A character that controls a scene from page events | The JS API (agent.say(), agent.ask()) — see js-api.md |
| Programmatic avatar viewing/creation in your own app | @three-ws/avatar |
| An on-chain identity for your AI | ERC-8004 or Solana |
| A paid API anyone (including agents) can call | x402 monetization |
| Multiple agents in one scene | <agent-stage> — see multi-agent.md |
| To register a domain (e.g. ENS) as agent identity | register-onchain.md tutorial |
What's next
- Architecture overview — full internals
- Agent system — runtime, skills, memory, emotion
- Layers — the four-layer contract in detail
- Quick start — go from zero to a living embed in under 10 minutes