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 — LobeHub Plugin
Embeds a rigged 3D avatar agent into any LobeHub instance via the plugin manifest + iframe bridge.
Install into a LobeHub fork
- Open your LobeHub instance → Settings → Plugins → Custom Plugin.
- Enter the manifest URL:
https://three.ws/api/lobehub/manifest - Install. LobeHub fetches the manifest, registers the four tools (
render_agent,speak,gesture,emote), and renders the iframe at/lobehub/iframe/inside chat messages. - Optionally pre-validate an agent before rendering:
POST /api/lobehub/handshakewith{ agentId, hostOrigin }.
postMessage contract
All messages share the envelope:
{ "v": 1, "ns": "3d-agent", "type": "<string>", "id": "<optional>", "payload": {} }
Host → embed (inbound)
| type | payload | effect |
|---|---|---|
host:hello |
{ hostName, hostVersion, capabilities } |
Triggers embed:hello reply |
host:ping |
{} |
Triggers embed:pong reply |
host:action |
{ action: { type, payload } } |
Dispatches to avatar |
host:pause |
{} |
Pauses the viewer |
host:resume |
{} |
Resumes the viewer |
host:theme |
{ mode: 'dark'|'light'|'transparent', accent? } |
Sets background + accent |
host:set-agent |
{ agentId } |
Reloads iframe with new agent |
Accepted action types for host:action.action.type: speak, gesture, emote.
Embed → host (outbound)
| type | payload | when |
|---|---|---|
embed:hello |
{ embedVersion, agentId, capabilities } |
On load and on host:hello |
embed:ready |
{ agentId, name, avatarUrl } |
Avatar fully loaded |
embed:blocked |
{ reason } |
Embed-policy check failed |
embed:error |
{ code, message, phase } |
Boot or runtime error |
embed:action |
{ action: { type, payload, timestamp, agentId } } |
Mirrors every dispatched action |
embed:resize |
{ width, height, contentHeight } |
On element resize (debounced 100ms) |
embed:pong |
{} |
Reply to host:ping |
Origin rules
chat.lobehub.comandlobechat.aiare trusted unconditionally.- Pass
?host=<encoded-origin>to narrow trust to a single parent origin. localhost/127.0.0.1/.localare trusted in development (logged, not blocked).- Unknown origins are permitted but logged — public agents may embed anywhere.
Legacy compat
The format { __agent: <id>, type: 'action', action } from existing embedders is accepted for one version. Migrate to the v1 envelope.
Acceptance-test handshake
For quick integration testing, posting { type: 'handshake' } from any origin returns { type: 'ready', agentId } without envelope wrapping. This is NOT the production protocol.
What this plugin does NOT yet support
- Host-auth / SIWE: embedding a user-auth token so the iframe can call authed APIs on behalf of the LobeHub user (spec: the lobehub-embed campaign, host-auth handoff work order, in git history).
- Tool-call relay: structured LobeHub
tool_call→ action mapping; today the relay passes raw action objects (spec: the lobehub-embed campaign, action-passthrough work order, in git history). - LobeHub marketplace submission: the manifest is hosted in this repo; no registry entry exists yet (spec: the lobehub-embed campaign, plugin-submission work order, in git history).
- MCP tool semantics — the
apientries point at/api/mcpbut thetooldispatch mapping from LobeHub's tool-call format to MCP JSON-RPC is not wired. - Emote public API —
host:actionwithtype: emotedispatches aCustomEventon the element but<agent-3d>has no publicemote()method; internal routing depends on element.js wiring.
Related specs
The five work orders of the lobehub-embed campaign (manifest design, the full postMessage
protocol, auth handoff, tool relay, plugin submission) were retired from prompts/ once the
shipped half landed. They remain readable in git history; nothing outside history references
them, so the paths above are names, not links.