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
// Manifest loader — resolves agent://, ipfs://, https:// into a normalized manifest.
// See specs/AGENT_MANIFEST.md
import { Contract } from 'ethers';
import { IDENTITY_REGISTRY_ABI, REGISTRY_DEPLOYMENTS } from './erc8004/abi.js';
import { findAvatar3D } from './erc8004/queries.js';
import { resolveURI, fetchWithFallback } from './ipfs.js';
import { getEvmProvider } from './shared/evm-rpc-fallback.js';
const CHAIN_ALIASES = {
base: 8453,
'base-mainnet': 8453,
'base-sepolia': 84532,
ethereum: 1,
mainnet: 1,
};
export async function loadManifest(source, { rpcURL, registry: registryOverride } = {}) {
if (!source) throw new Error('loadManifest: source required');
if (source.startsWith('agent://')) {
return loadFromAgentURI(source, { rpcURL, registryOverride });
}
if (source.startsWith('ipfs://') || source.startsWith('ar://')) {
const url = resolveURI(source);
const json = await fetchManifestJSON(url);
return normalize(json, { baseURI: trimToDir(url) });
}
if (source.startsWith('http')) {
const json = await fetchManifestJSON(source);
return normalize(json, { baseURI: trimToDir(source) });
}
throw new Error(`Unsupported manifest source: ${source}`);
}
async function loadFromAgentURI(uri, { rpcURL, registryOverride }) {
// agent://{chain}/{agentId}
const m = uri.match(/^agent:\/\/([^/]+)\/(\d+)$/);
if (!m) throw new Error(`Malformed agent URI: ${uri}`);
const [, chainName, agentIdStr] = m;
const chainId = CHAIN_ALIASES[chainName.toLowerCase()] || Number(chainName);
if (!chainId) throw new Error(`Unknown chain: ${chainName}`);
const deployment = REGISTRY_DEPLOYMENTS[chainId];
const registryAddr = registryOverride || deployment?.identityRegistry;
if (!registryAddr) {
throw new Error(`No registry deployed on chain ${chainId}. Pass registry= override.`);
}
// Same-origin /api/evm-rpc proxy first (server failover), then the chain's
// public hosts; a caller-supplied rpcURL is pinned ahead of the public tail.
const provider = await getEvmProvider(chainId, { primaryUrl: rpcURL || null });
const registry = new Contract(registryAddr, IDENTITY_REGISTRY_ABI, provider);
const agentId = BigInt(agentIdStr);
const tokenURI = await registry.tokenURI(agentId);
if (!tokenURI) throw new Error(`Agent ${agentIdStr} on chain ${chainId} has no URI`);
const resolved = resolveURI(tokenURI);
const json = await fetchManifestJSON(resolved);
const manifest = normalize(json, { baseURI: trimToDir(resolved) });
// Ensure id is stamped on the manifest
manifest.id = {
...manifest.id,
chain: chainName,
chainId,
registry: registryAddr,
agentId: agentIdStr,
};
return manifest;
}
async function fetchManifestJSON(url) {
// Prefer fetchWithFallback if this is an IPFS URI we can detect.
let res;
try {
res = await fetch(url);
} catch {
res = await fetchWithFallback(url);
}
if (!res.ok) throw new Error(`Manifest fetch failed: ${url} (${res.status})`);
return res.json();
}
function isAbsoluteURI(uri) {
return /^(https?|ipfs|ar|data):/.test(uri);
}
// Convert either a full AGENT_MANIFEST or a bare ERC-8004 registration JSON
// into a uniform manifest object the runtime consumes.
export function normalize(json, { baseURI = '' } = {}) {
// Backend wrappers — `/api/avatars/:id` returns `{ avatar: {...} }`, list
// endpoints sometimes return `{ item: {...} }`. Unwrap once before the
// shape-detection branches below run on the empty outer object.
if (json && typeof json === 'object' && !json.spec && !json.type) {
if (json.avatar && typeof json.avatar === 'object') json = json.avatar;
else if (json.item && typeof json.item === 'object') json = json.item;
}
// Full manifest — spec: "agent-manifest/0.1"
if (json.spec && json.spec.startsWith('agent-manifest/')) {
const m = { ...json, _baseURI: baseURI };
m.body = m.body || {};
if (!m.body.uri && m.image) m.body.uri = m.image;
return m;
}
// ERC-8004 registration JSON — adapt to manifest shape
if (json.type && json.type.includes('eip-8004')) {
const registration = json.registrations?.[0] || {};
// The GLB lives in services[{name:'avatar'}] per our convention. The
// top-level `image` field is a 2D thumbnail (NFT-marketplace compat) —
// only fall back to it when no 3D body was declared.
const glbUri = findAvatar3D(json);
const imageUri = json.image && isAbsoluteURI(json.image) ? json.image : '';
return {
spec: 'agent-manifest/0.1',
_baseURI: baseURI,
_source: 'erc8004-registration',
id: { agentId: registration.agentId?.toString() },
name: json.name,
description: json.description,
image: imageUri || null,
body: { uri: resolveURI(glbUri || imageUri), format: 'gltf-binary' },
brain: { provider: 'none' },
voice: { tts: { provider: 'browser' }, stt: { provider: 'browser' } },
skills: [],
memory: { mode: 'local' },
tools: ['wave', 'lookAt', 'play_clip', 'setExpression', 'speak', 'remember'],
version: '0.1.0',
services: Array.isArray(json.services) ? json.services : [],
x402Support: !!json.x402Support,
embedPolicy: json.embedPolicy || null,
};
}
// Unknown / partial — best effort. Includes the avatar-detail shape
// (`model_url` / `url` / `base_model_url` + `thumbnail_url`) returned by
// `/api/avatars/:id`, which is the documented embed source.
const bodyURI =
json.body?.uri ||
json.model_url ||
json.url ||
json.base_model_url ||
json.image ||
json.model ||
'';
return {
spec: 'agent-manifest/0.1',
_baseURI: baseURI,
id: json.id ? { agentId: String(json.id) } : undefined,
name: json.name || 'Unnamed agent',
description: json.description || '',
image: json.thumbnail_url || json.image || null,
body: {
uri: bodyURI,
format: json.body?.format || json.content_type || 'gltf-binary',
},
brain: json.brain || {
provider: json.id ? 'anthropic' : 'none',
instructions: json.id
? `You are ${json.name || 'an AI agent'} on three.ws — a living, embodied 3D avatar.${json.description ? ' ' + json.description : ''} Be friendly and conversational. You can wave, play animations, and change expressions using your tools. When greeting someone, use the wave tool. Only use play_clip when the user explicitly asks for an animation.`
: undefined,
},
voice: json.voice || { tts: { provider: 'browser' }, stt: { provider: 'browser' } },
skills: json.skills || [],
memory: json.memory || { mode: 'local' },
tools: json.tools || ['wave', 'lookAt', 'play_clip', 'setExpression', 'speak', 'remember'],
version: json.version || '0.1.0',
};
}
function trimToDir(url) {
const i = url.lastIndexOf('/');
return i >= 0 ? url.slice(0, i + 1) : url;
}
// Load instructions.md, SKILL.md and other relative files referenced by the manifest
export async function fetchRelative(manifest, relPath) {
if (!manifest._baseURI) return null;
try {
const url = new URL(relPath, manifest._baseURI).href;
const res = await fetch(url);
if (!res.ok) return null;
return res.text();
} catch {
return null;
}
}