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
/**
* Crawler page for agent detail (/agents/:id)
* -------------------------------------------
* GET /api/agent-detail-og?id=<agentId>
*
* Wired via vercel.json: when a crawler User-Agent hits /agents/<uuid>, a
* "has" condition rewrites to this endpoint. Real browsers never reach it, so
* this is the only version of the page a search engine or a link unfurler ever
* sees, and it has to carry the agent's real content rather than meta tags over
* a spinner. See the header of api/_lib/crawler-page.js.
*
* Mirrors api/avatar-detail-og.js.
*/
import { sql } from './_lib/db.js';
import { cors, method, wrap } from './_lib/http.js';
import { env } from './_lib/env.js';
import { isUuid } from './_lib/validate.js';
import { esc, isSearchCrawler, renderCrawlerPage, renderCrawlerNotFound } from './_lib/crawler-page.js';
import { isIndexableAgent } from './_lib/indexable-entity.js';
import { publicUrlOrNull } from './_lib/r2.js';
import { creationJsonLd } from './_lib/creation-jsonld.js';
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,OPTIONS' })) return;
// Crawler-only SSR read. Without this, a POST answered with a page instead
// of the 405 the advertised Allow set promises.
if (!method(req, res, ['GET'])) return;
const url = new URL(req.url, 'http://x');
const agentId = url.searchParams.get('id');
const origin = env.APP_ORIGIN || 'https://three.ws';
const ua = req.headers?.['user-agent'];
// Only a non-indexing scraper gets bounced to the app. An indexing crawler
// runs that script, lands back on this same URL behind the same UA branch,
// and loops on an identical response.
const redirect = !isSearchCrawler(ua);
if (!agentId || !isUuid(agentId)) {
return generic(res, origin, agentId, redirect);
}
let agent;
try {
[agent] = await sql`
SELECT i.id, i.name, i.description, i.skills, i.home_url,
i.erc8004_agent_id, i.chain_id, i.created_at, i.updated_at,
a.storage_key AS body_storage_key, a.size_bytes AS body_size_bytes,
u.username AS owner_username, u.display_name AS owner_display_name
FROM agent_identities i
-- The agent's 3D body, only when that avatar is itself public: a
-- private body's file must not surface through its agent's page.
LEFT JOIN avatars a
ON a.id = i.avatar_id AND a.deleted_at IS NULL AND a.visibility = 'public'
LEFT JOIN users u ON u.id = i.user_id AND u.deleted_at IS NULL
WHERE i.id = ${agentId} AND i.deleted_at IS NULL AND i.is_public = true
LIMIT 1
`;
} catch {
// A read failure is ours, not the URL's. 503 asks the crawler to come
// back; a 404 or a redirect here would drop a live page from the index.
return unavailable(res, origin);
}
if (!agent) {
// Agents and avatars have separate uuid spaces and links cross over
// (see resolveEntity in src/avatar-page.js). Send the crawler to the
// path that actually holds the entity instead of reporting nothing.
let avatar = null;
try {
[avatar] = await sql`
SELECT id FROM avatars
WHERE id = ${agentId} AND deleted_at IS NULL AND visibility = 'public' LIMIT 1
`;
} catch {
return unavailable(res, origin);
}
if (avatar) {
res.statusCode = 301;
res.setHeader('location', `${origin}/avatars/${agentId}`);
res.setHeader('cache-control', 'public, max-age=300');
res.end();
return;
}
return gone(res, origin);
}
const title = agent.name || 'Agent';
const baseDesc =
agent.description || 'An AI agent on three.ws, with a body, a place, and an identity.';
const skills = Array.isArray(agent.skills) ? agent.skills : [];
const skillSuffix = skills.length
? ` Skills: ${skills.slice(0, 4).join(', ')}${skills.length > 4 ? '…' : ''}.`
: '';
const desc = baseDesc + skillSuffix;
// Unfurl with the dynamic wallet TRADING CARD (api/og/agent.js) - the same
// living card shown on the page (avatar, vanity address, live net worth, P&L,
// reputation tier, finish), rendered from real data. The card embeds the
// avatar itself, so a shared link previews with identity + wallet, not a bare
// thumbnail. The card endpoint falls back to the brand image if it can't render.
const ogImage = `${origin}/api/og/agent?id=${encodeURIComponent(agentId)}`;
const pageUrl = `${origin}/agents/${agentId}`;
const facts = [];
if (skills.length) {
facts.push({
term: 'Skills',
detail: skills.slice(0, 12).map((s) => esc(s)).join(', '),
});
}
if (agent.erc8004_agent_id) {
facts.push({
term: 'On-chain identity',
detail: `ERC-8004 agent #${esc(agent.erc8004_agent_id)}${agent.chain_id ? ` on chain ${esc(agent.chain_id)}` : ''}`,
});
}
if (agent.home_url && /^https?:\/\//i.test(agent.home_url)) {
const h = esc(agent.home_url);
facts.push({ term: 'Home', detail: `<a href="${h}" rel="nofollow noopener">${h}</a>` });
}
if (agent.created_at) facts.push({ term: 'Registered', detail: isoDay(agent.created_at) });
res.statusCode = 200;
res.setHeader('content-type', 'text/html; charset=utf-8');
res.setHeader('cache-control', 'public, max-age=60, s-maxage=600, stale-while-revalidate=3600');
res.end(
renderCrawlerPage({
title,
desc,
pageUrl,
ogImage,
origin,
ogType: 'profile',
frameButton: `Meet ${title}`,
redirect,
// An untouched onboarding row is identical to every other one, so it
// unfurls and renders but never asks to be indexed.
noindex: !isIndexableAgent(agent),
trail: [
{ name: 'Home', path: '/' },
{ name: 'Agents', path: '/agents' },
{ name: title, path: `/agents/${agentId}` },
],
facts,
// No skill chips: the directory filters on ?q= over name and
// description, not on a skill facet, so a chip would look like a
// filter and return an unfiltered list. The skills are in the facts
// row and in featureList below.
actions: [
{ label: 'View in AR', href: `/agents/${agentId}/ar`, primary: true },
{ label: 'Agent directory', href: '/agents' },
{ label: 'Build an agent', href: '/create' },
],
related: [
{ label: 'Agent directory', href: '/agents' },
{ label: 'Agent economy', href: '/agent-economy' },
{ label: 'Agent marketplace', href: '/marketplace' },
{ label: 'Avatar gallery', href: '/gallery' },
],
// An agent is software, not a model, so it stays a
// SoftwareApplication (a CreativeWork subtype) and its 3D body rides
// along as the encoding, with the same render, creator and terms
// every creation page carries (api/_lib/creation-jsonld.js).
jsonLd: creationJsonLd({
origin,
pageUrl,
type: 'SoftwareApplication',
name: title,
description: desc,
glbUrl: publicUrlOrNull(agent.body_storage_key),
glbSizeBytes: agent.body_size_bytes,
image: ogImage,
creator: agent.owner_username
? { username: agent.owner_username, displayName: agent.owner_display_name }
: null,
dateCreated: agent.created_at,
dateModified: agent.updated_at,
extra: {
applicationCategory: 'AI agent',
operatingSystem: 'Web',
...(skills.length ? { featureList: skills.slice(0, 12) } : {}),
},
}),
}),
);
});
/** An id we cannot read: keep the unfurl useful, keep the URL out of the index. */
function generic(res, origin, agentId, redirect) {
const target = agentId ? `/agents/${encodeURIComponent(agentId)}` : '/agents';
res.statusCode = 200;
res.setHeader('content-type', 'text/html; charset=utf-8');
res.setHeader('cache-control', 'public, max-age=60, s-maxage=600');
res.end(
renderCrawlerNotFound({
heading: 'Agent on three.ws',
message: 'Open this agent on three.ws to see its body, its wallet, and what it can do.',
origin,
actions: [
{ label: 'Open the agent', href: target },
{ label: 'Agent directory', href: '/agents' },
],
redirect: redirect ? target : '',
}),
);
}
/** Nothing public lives at this id. 404 so the URL leaves the index cleanly. */
function gone(res, origin) {
res.statusCode = 404;
res.setHeader('content-type', 'text/html; charset=utf-8');
res.setHeader('cache-control', 'public, max-age=300');
res.end(
renderCrawlerNotFound({
heading: 'This agent is not public',
message:
'The agent behind this link was retired, or its owner keeps it private. The directory lists the ones that are live.',
origin,
actions: [
{ label: 'Agent directory', href: '/agents' },
{ label: 'Build an agent', href: '/create' },
],
}),
);
}
/** Our read failed. Ask the crawler to retry rather than losing the page. */
function unavailable(res, origin) {
res.statusCode = 503;
res.setHeader('content-type', 'text/html; charset=utf-8');
res.setHeader('retry-after', '120');
res.setHeader('cache-control', 'no-store');
res.end(
renderCrawlerNotFound({
heading: 'Agent temporarily unavailable',
message: 'three.ws could not load this agent just now. Please try again in a moment.',
origin,
actions: [{ label: 'Agent directory', href: '/agents' }],
}),
);
}
/** YYYY-MM-DD, the only precision a crawler page needs. */
function isoDay(v) {
const t = v instanceof Date ? v : new Date(v);
return Number.isNaN(t.getTime()) ? '' : t.toISOString().slice(0, 10);
}