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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// <agent-stage> — shared scene host for multiple <agent-3d> children.
// See specs/STAGE_SPEC.md
import { Group, Vector3 } from 'three';
import { Viewer } from './viewer.js';
const FORMATIONS = ['row', 'circle', 'freeform'];
const STAGE_STYLE = `
:host {
display: block;
position: relative;
width: 100%;
height: 480px;
contain: layout style;
}
:host([hidden]) { display: none; }
.stage-canvas {
position: absolute;
inset: 0;
width: 100%;
height: 100%;
}
.stage-canvas canvas { display: block; }
::slotted(agent-3d) {
position: absolute;
pointer-events: none;
}
`;
class AgentStageElement extends HTMLElement {
static get observedAttributes() {
return ['formation'];
}
constructor() {
super();
this.attachShadow({ mode: 'open' });
this._viewer = null;
this._agents = [];
this._initialized = false;
}
connectedCallback() {
this._renderShell();
this._initViewer();
this._mo = new MutationObserver(() => this._repositionAll());
this._mo.observe(this, { childList: true });
}
disconnectedCallback() {
try {
this._mo?.disconnect();
} catch {}
for (const a of [...this._agents]) this.unregisterAgent(a.element);
try {
this._viewer?.dispose?.();
} catch {}
this._viewer = null;
this._initialized = false;
}
attributeChangedCallback(name) {
if (name === 'formation') this._repositionAll();
}
get formation() {
const f = this.getAttribute('formation') || 'row';
return FORMATIONS.includes(f) ? f : 'row';
}
get viewer() {
return this._viewer;
}
_renderShell() {
const style = document.createElement('style');
style.textContent = STAGE_STYLE;
this.shadowRoot.appendChild(style);
const box = document.createElement('div');
box.className = 'stage-canvas';
box.part = 'stage';
this.shadowRoot.appendChild(box);
this._canvasBox = box;
const slot = document.createElement('slot');
this.shadowRoot.appendChild(slot);
}
_initViewer() {
if (this._initialized) return;
// A device/browser that can't grant a WebGL context (GPU blocklist, context
// budget exhausted, headless) makes the Viewer constructor throw "Error
// creating WebGL context". connectedCallback runs this synchronously, so an
// unguarded throw escapes as an uncaught error and blanks the host page.
// Degrade instead: leave _viewer null (registerAgent/unregisterAgent already
// null-check it) so child agents simply don't render rather than crash.
try {
this._viewer = new Viewer(this._canvasBox, { kiosk: true });
} catch (err) {
this._viewer = null;
this._initialized = true;
return;
}
// Default framing for a human-scale stage.
this._viewer.defaultCamera.position.set(0, 1.55, 3.4);
this._viewer.defaultCamera.lookAt(0, 1.2, 0);
this._viewer.controls.target.set(0, 1.2, 0);
this._viewer.controls.update();
try {
this._viewer.updateLights?.();
} catch {}
try {
this._viewer.updateEnvironment?.();
} catch {}
this._viewer.invalidate();
this._initialized = true;
}
// --- Called by <agent-3d> children that detect this parent stage ---
registerAgent(element, { id, group, manifest }) {
const finalId = this._uniqueId(id || manifest?.name || 'agent');
const rec = { id: finalId, element, group, manifest };
this._agents.push(rec);
this._viewer?.scene.add(group);
this._repositionAll();
this.dispatchEvent(
new CustomEvent('stage:agent-joined', {
detail: { agentId: finalId, element, manifest },
bubbles: true,
composed: true,
}),
);
return finalId;
}
unregisterAgent(element) {
const i = this._agents.findIndex((a) => a.element === element);
if (i < 0) return;
const [rec] = this._agents.splice(i, 1);
try {
this._viewer?.scene.remove(rec.group);
} catch {}
disposeGroup(rec.group);
this._repositionAll();
this.dispatchEvent(
new CustomEvent('stage:agent-left', {
detail: { agentId: rec.id, element: rec.element },
bubbles: true,
composed: true,
}),
);
}
_uniqueId(base) {
let id = base;
let n = 1;
const taken = new Set(this._agents.map((a) => a.id));
while (taken.has(id)) id = `${base}-${n++}`;
return id;
}
// --- Public API ---
getAgents() {
return this._agents.map(({ id, group, manifest, element }) => ({
agentId: id,
name: manifest?.name || id,
position: [
+group.position.x.toFixed(3),
+group.position.y.toFixed(3),
+group.position.z.toFixed(3),
],
element,
}));
}
broadcast(fromId, event) {
const detail = { from: fromId, event };
for (const a of this._agents) {
if (a.id === fromId) continue;
a.element.dispatchEvent(new CustomEvent('stage:message', { detail }));
}
this.dispatchEvent(
new CustomEvent('stage:message', {
detail,
bubbles: true,
composed: true,
}),
);
}
async routeMessage(fromId, toId, text) {
const target = this._agents.find((a) => a.id === toId);
if (!target) return { ok: false, error: `No agent "${toId}" on stage` };
try {
const reply = await target.element.say(`[from ${fromId}] ${text}`);
return { ok: true, reply: reply?.text || '' };
} catch (e) {
return { ok: false, error: e?.message || String(e) };
}
}
async addAgent(manifest) {
const el = document.createElement('agent-3d');
if (manifest && typeof manifest === 'object') {
el._inlineManifest = manifest;
}
if (!el.hasAttribute('eager')) el.setAttribute('eager', '');
this.appendChild(el);
return el;
}
removeAgent(agentId) {
const rec = this._agents.find((a) => a.id === agentId);
if (rec) rec.element.remove();
}
// --- Formation / layout ---
_repositionAll() {
const n = this._agents.length;
if (!n || !this._viewer) return;
for (let i = 0; i < n; i++) {
const { element, group, manifest } = this._agents[i];
const slot = this._slotFor(i, n);
group.position.copy(slot.world);
group.lookAt(0, slot.world.y + 1.0, slot.world.z + 5.0);
// Sub-rect for this child's chrome overlay
element.style.position = 'absolute';
element.style.left = slot.dom.left;
element.style.top = slot.dom.top;
element.style.width = slot.dom.width;
element.style.height = slot.dom.height;
element.style.pointerEvents = 'none';
}
this._viewer.invalidate();
}
_slotFor(i, n) {
const f = this.formation;
const w = 1 / Math.max(n, 1);
if (f === 'circle') {
const angle = (i / n) * Math.PI * 2;
const r = Math.max(0.8, 0.4 * n);
return {
world: new Vector3(Math.sin(angle) * r, 0, -Math.cos(angle) * r + r * 0.5),
dom: {
left: `${i * w * 100}%`,
top: '0',
width: `${w * 100}%`,
height: '100%',
},
};
}
if (f === 'freeform') {
return {
world: new Vector3(0, 0, 0),
dom: { left: '0', top: '0', width: '100%', height: '100%' },
};
}
// row
const spacing = 1.1;
const x = (i - (n - 1) / 2) * spacing;
return {
world: new Vector3(x, 0, 0),
dom: {
left: `${i * w * 100}%`,
top: '0',
width: `${w * 100}%`,
height: '100%',
},
};
}
}
function disposeGroup(group) {
group.traverse((o) => {
if (o.geometry) {
try {
o.geometry.dispose();
} catch {}
}
if (o.material) {
const mats = Array.isArray(o.material) ? o.material : [o.material];
for (const m of mats) {
for (const k of Object.keys(m)) {
const v = m[k];
if (v && v.isTexture) {
try {
v.dispose();
} catch {}
}
}
try {
m.dispose();
} catch {}
}
}
});
if (group.parent) group.parent.remove(group);
}
if (!customElements.get('agent-stage')) {
customElements.define('agent-stage', AgentStageElement);
}
export { AgentStageElement };