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
// Resolve a hosted agent by id against the backend API, producing an in-memory
// manifest shaped like a file-based one so the rest of the <agent-3d> boot
// path (manifest.body.uri, manifest.brain, manifest.skills, manifest._baseURI)
// works unchanged.
export class AgentResolveError extends Error {
constructor(code, message, { status } = {}) {
super(message);
this.name = 'AgentResolveError';
this.code = code;
if (status !== undefined) this.status = status;
}
}
// Map a stored ElevenLabs voice_settings object (snake_case, as persisted by
// PUT /api/agents/:id/voice) to the camelCase options ElevenLabsTTS accepts.
// Omits absent fields so the TTS client falls back to its own defaults.
function voiceSettingsToConfig(vs) {
if (!vs || typeof vs !== 'object') return {};
const out = {};
if (vs.stability != null) out.stability = vs.stability;
if (vs.similarity_boost != null) out.similarityBoost = vs.similarity_boost;
if (vs.style != null) out.style = vs.style;
if (vs.use_speaker_boost != null) out.useSpeakerBoost = vs.use_speaker_boost;
return out;
}
function ttsConfigFromManifestVoice(voice, { origin, agentId }) {
const provider = voice?.provider || 'browser';
if (provider !== 'elevenlabs' || !voice?.voice_id) return { provider: 'browser' };
return {
provider: 'elevenlabs',
voiceId: voice.voice_id,
proxyURL: `${origin}/api/tts/eleven`,
// Lets the proxy serve this clip on the owner's own ElevenLabs key, so an
// embed speaks for visitors too.
agentId,
...(voice.model ? { modelId: voice.model } : {}),
...voiceSettingsToConfig(voice.settings),
};
}
/**
* Resolve a hosted agent id to the in-memory manifest the element boots from.
*
* Reads the agent's public manifest, GET {origin}/api/agents/:id/manifest. That
* document is the embed contract: anonymous, CDN-cacheable, and served with
* `access-control-allow-origin: *`, so the same request works from three.ws and
* from any third-party page. It also carries the owner's gesture slots and
* routines, which the element applies at boot.
*
* `origin` must be the three.ws API base the element was loaded from, never the
* host page's origin: on example.com a site-absolute path asks example.com for
* the agent, 404s, and the embed falls back to a default body named "Agent".
*
* @param {string} agentId
* @param {{ origin?: string, fetchFn?: typeof fetch, signal?: AbortSignal }} [opts]
*/
export async function resolveAgentById(
agentId,
{
origin = typeof location !== 'undefined' ? location.origin : '',
fetchFn = fetch,
signal,
} = {},
) {
if (!agentId) throw new AgentResolveError('not_found', 'agentId required');
const boundFetch = fetchFn.bind(typeof globalThis !== 'undefined' ? globalThis : undefined);
const endpoint = `${origin}/api/agents/${encodeURIComponent(agentId)}/manifest`;
let res;
try {
// Public document: no cookies, so the wildcard CORS answer is usable
// from any origin and shared caches can serve it.
res = await boundFetch(endpoint, { credentials: 'omit', signal });
} catch (err) {
if (err?.name === 'AbortError') throw err;
throw new AgentResolveError(
'network',
`network error fetching ${endpoint}: ${err.message || err}`,
);
}
// 400 is the API's answer to an id that is not a uuid: no such agent.
if (res.status === 404 || res.status === 400)
throw new AgentResolveError('not_found', `agent ${agentId} not found`, {
status: res.status,
});
if (!res.ok)
throw new AgentResolveError('network', `request failed: ${endpoint} (${res.status})`, {
status: res.status,
});
let doc;
try {
doc = await res.json();
} catch (err) {
throw new AgentResolveError('network', `invalid JSON from ${endpoint}: ${err.message || err}`);
}
const id = doc?.id || agentId;
const bodyUri = doc?.body?.uri;
if (!bodyUri) throw new AgentResolveError('no_avatar', `agent ${agentId} has no avatar bound`);
const skills = Array.isArray(doc.skills)
? doc.skills.map((s) => (typeof s === 'string' ? { name: s } : s)).filter(Boolean)
: [];
const registration = Array.isArray(doc.registrations) ? doc.registrations[0] : null;
const chainId = registration?.agentRegistry
? Number(String(registration.agentRegistry).split(':')[1]) || undefined
: undefined;
return {
spec: 'agent-manifest/0.1',
name: doc.name || 'Agent',
description: doc.description || '',
id: { agentId: id, ...(chainId ? { chainId } : {}) },
body: { uri: bodyUri, format: 'gltf-binary' },
brain: {},
voice: {
tts: ttsConfigFromManifestVoice(doc.voice, { origin, agentId: id }),
stt: { provider: 'browser' },
},
skills,
memory: { mode: 'local', namespace: id },
tools: ['wave', 'lookAt', 'play_clip', 'setExpression', 'speak', 'remember'],
...(doc.animationSlots ? { animationSlots: doc.animationSlots } : {}),
...(Array.isArray(doc.choreographies) ? { choreographies: doc.choreographies } : {}),
version: '0.1.0',
_baseURI: `${origin}/agent/${id}/`,
_source: 'agent-id',
};
}
/**
* Resolve an avatar UUID to a bare-body manifest via GET /api/avatars/:id.
* Used by the `<agent-3d avatar-id="...">` attribute so embedders can hand off
* a stable avatar identifier instead of a raw GLB URL.
*
* Always uses credentials: 'omit' — the public-visibility branch of the API
* returns 200 without a session; private avatars 404 to anonymous callers, which
* is the correct boundary for cross-origin embeds.
*
* @param {string} avatarId
* @param {{ origin?: string, fetchFn?: typeof fetch, signal?: AbortSignal }} [opts]
*/
export async function resolveByAvatarId(
avatarId,
{
origin = typeof location !== 'undefined' ? location.origin : '',
fetchFn = fetch,
signal,
} = {},
) {
if (!avatarId) throw new AgentResolveError('not_found', 'avatarId required');
const boundFetch = fetchFn.bind(typeof globalThis !== 'undefined' ? globalThis : undefined);
const endpoint = `${origin}/api/avatars/${encodeURIComponent(avatarId)}`;
let res;
try {
res = await boundFetch(endpoint, { credentials: 'omit', signal });
} catch (err) {
if (err?.name === 'AbortError') throw err;
throw new AgentResolveError(
'network',
`network error fetching ${endpoint}: ${err.message || err}`,
);
}
if (res.status === 404)
throw new AgentResolveError('not_found', `avatar ${avatarId} not found`, { status: 404 });
if (!res.ok)
throw new AgentResolveError('network', `request failed (${res.status})`, {
status: res.status,
});
let data;
try {
data = await res.json();
} catch (err) {
throw new AgentResolveError('network', `invalid JSON from ${endpoint}`);
}
const avatar = data?.avatar;
const modelUrl = avatar?.model_url || avatar?.url;
if (!modelUrl)
throw new AgentResolveError('no_url', `avatar ${avatarId} has no model url`);
return {
spec: 'agent-manifest/0.1',
_baseURI: '',
_source: 'avatar-id',
name: avatar.name || 'Avatar',
body: { uri: modelUrl, format: 'gltf-binary' },
brain: { provider: 'none' },
voice: { tts: { provider: 'browser' }, stt: { provider: 'browser' } },
skills: [],
};
}