Skip to content

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.

12.1 KB
Raw Blame
/**
 * Public agent index — browsable directory of all public agents.
 *
 *   GET /api/agents/public
 *       ?q=<search>          full-text search on name + description
 *       &skill=<slug>        filter by skill slug
 *       &sort=newest|popular|name|live  (default: popular)
 *       &limit=24            max 48
 *       &before=<iso>        cursor (created_at <) for pagination  (newest|popular|name)
 *       &offset=<n>          offset pagination                     (live)
 *       &network=mainnet     only show on-chain agents on this network
 *       &avatar=1            only agents whose avatar GLB is publicly readable
 *
 * Returns { agents, count, has_more, generated_at }. Each agent has the
 * public-safe fields: id, name, description, skills, avatar_thumbnail,
 * avatar_model_url (the GLB, only when the avatar is public or unlisted; the
 * desktop campus wears it), home_url, is_registered, chat_count, created_at,
 * onchain summary.
 *
 * The `live` sort powers the /agents-live "watch them work" wall: it ranks
 * agents by their MOST RECENT real on-chain/skill action (the same
 * `agent_actions` each card renders as a live terminal), so the wall leads with
 * agents that are genuinely doing something instead of a flood of freshly-created
 * placeholder agents. It also suppresses zero-signal placeholders — an agent left
 * on the onboarding default name with no activity, no chats and no on-chain
 * identity adds nothing to a live wall — and returns `last_action_at` /
 * `action_count` so the card can badge recency. First page (`offset=0`) also
 * carries `total` (the wall's addressable size) and `active_total` (agents with
 * any activity) for the header stats.
 *
 * Internal agents never list. An agent the platform made for itself (owned by a
 * `users.service_account` row) and never published is infrastructure, such as
 * the meter that budgets the marketplace chat bot's AI spend, not something to
 * browse. `is_public` defaults to true, so a provisioning script that forgets to
 * clear it would otherwise put that machinery on the public wall; every query
 * here therefore also requires "published, or owned by a person". The platform's
 * own published persona agents (service-account owned, published) still list,
 * and so do people's unpublished starter agents.
 *
 * Public, IP rate-limited, 30-second CDN cache.
 */

import { cors, json, method, wrap, rateLimited } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { sql } from '../_lib/db.js';
import { publicUrlOrNull, thumbnailUrl } from '../_lib/r2.js';

const SORTS = new Set(['newest', 'popular', 'name', 'live']);

// Onboarding / auto-generated default names. An agent still wearing one of these,
// with no activity, no chats and no on-chain identity, is a never-used placeholder
// — kept out of the live wall (it's still reachable via search and /agents).
const PLACEHOLDER_NAMES = ['My First Agent', 'Agent', 'Avatar', 'My Avatar', 'Untitled Agent', 'New Agent'];

// A failed query here degrades to an empty page rather than a 5xx, because a
// blank directory beats a broken one for a public browse surface. Log it anyway:
// without this, a DB outage or a migration that renamed a column reads to
// operators exactly like "nobody has published an agent yet".
function logQueryFailure(scope, err) {
	console.error(`[agents/public] ${scope} query failed:`, err?.message || err);
}

function mapAgent(r) {
	const meta   = r.meta || {};
	const onchain = meta.onchain || null;
	const thumbPub = r.avatar_visibility === 'public' || r.avatar_visibility === 'unlisted';
	const thumbnail = r.avatar_thumbnail_key && thumbPub ? thumbnailUrl(r.avatar_thumbnail_key) : null;
	// The body itself, under the same public/unlisted gate as /api/agents/:id.
	// Lets a crowd surface (the desktop campus) dress every agent from one call
	// instead of one profile fetch per agent.
	const modelUrl = r.avatar_storage_key && thumbPub ? publicUrlOrNull(r.avatar_storage_key) : null;

	return {
		id:                r.id,
		name:              r.name,
		description:       r.description || null,
		skills:            r.skills || [],
		avatar_thumbnail:  thumbnail,
		avatar_model_url:  modelUrl,
		home_url:          r.home_url || `/agents/${r.id}`,
		chat_count:        Number(r.chat_count) || 0,
		is_registered:     !!(onchain || meta.sol_mint_address || r.erc8004_agent_id || meta.erc8004_agent_id),
		onchain:           onchain ? { network: onchain.network, asset: onchain.sol_asset || null } : null,
		// On-chain ERC-8004 identity (public registry ids) so the agent-commerce
		// discovery tool can read each candidate's reputation without a second
		// round-trip. Falls back to the legacy meta field for older records.
		erc8004_agent_id:  r.erc8004_agent_id != null ? String(r.erc8004_agent_id) : (meta.erc8004_agent_id != null ? String(meta.erc8004_agent_id) : null),
		chain_id:          r.chain_id ?? null,
		created_at:        r.created_at,
		// Present only on the `live` sort — powers the card's recency badge.
		last_action_at:    r.last_action_at ?? null,
		action_count:      r.action_count != null ? Number(r.action_count) : undefined,
	};
}

export default wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
	if (!method(req, res, ['GET'])) return;

	const rl = await limits.publicIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl);

	const p = new URL(req.url, `http://${req.headers.host || 'x'}`).searchParams;
	const q      = (p.get('q') || '').trim().slice(0, 100);
	const skill  = (p.get('skill') || '').trim().toLowerCase();
	const sort   = SORTS.has(p.get('sort')) ? p.get('sort') : 'popular';
	const limit  = Math.min(48, Math.max(1, Number(p.get('limit') || 24)));
	const before = p.get('before') || null;
	const offset = Math.max(0, Math.min(5000, Number(p.get('offset') || 0) | 0));
	const onchainOnly = p.get('onchain') === '1' || p.get('onchain') === 'true';
	// avatar=1 keeps only agents that carry a publicly readable avatar GLB. Surfaces
	// that render or export the model itself (the Claude artifact builder, embeds)
	// need this: an agent with no avatar, or one whose avatar is private, cannot be
	// rendered at all and would offer the visitor a pick that can only fail.
	const avatarOnly = p.get('avatar') === '1' || p.get('avatar') === 'true';

	// ── live sort: activity-first, placeholder-suppressed, offset-paginated ──────
	if (sort === 'live') {
		const rows = await sql`
			select
				i.id, i.name, i.description, i.skills, i.home_url,
				i.created_at, i.meta, i.erc8004_agent_id, i.chain_id,
				a.thumbnail_key  as avatar_thumbnail_key,
				a.storage_key    as avatar_storage_key,
				a.visibility     as avatar_visibility,
				ac.last_action_at,
				coalesce(ac.action_count, 0) as action_count,
				coalesce(ch.chat_count, 0)   as chat_count
			from agent_identities i
			left join avatars a on a.id = i.avatar_id and a.deleted_at is null
			left join lateral (
				select max(created_at) as last_action_at, count(*)::int as action_count
				from agent_actions aa where aa.agent_id = i.id
			) ac on true
			left join lateral (
				select count(*)::int as chat_count
				from usage_events ue where ue.agent_id = i.id and ue.kind = 'llm'
			) ch on true
			where i.deleted_at is null
			  and i.is_public = true
			  and not (i.is_published is not true and exists (
			        select 1 from users su where su.id = i.user_id and su.service_account
			      ))
			  and (${!q} or (
			        to_tsvector('english', coalesce(i.name,'') || ' ' || coalesce(i.description,''))
			        @@ plainto_tsquery('english', ${q})
			      ))
			  and (${!skill} or i.skills @> ${[skill]}::text[])
			  and (${!onchainOnly} or (
			        i.meta->'onchain' is not null
			        or i.meta->>'sol_mint_address' is not null
			      ))
			  and (${!avatarOnly} or (
			        a.storage_key is not null
			        and a.visibility in ('public', 'unlisted')
			      ))
			  and (
			        ac.last_action_at is not null
			        or ch.chat_count > 0
			        or i.erc8004_agent_id is not null
			        or i.meta->'onchain' is not null
			        or i.meta->>'sol_mint_address' is not null
			        or (
			              coalesce(i.name,'') <> ''
			              and not (i.name = any(${PLACEHOLDER_NAMES}))
			              and i.name not like 'Selfie avatar%'
			           )
			      )
			order by ac.last_action_at desc nulls last, i.created_at desc
			limit ${limit + 1} offset ${offset}
		`.catch((err) => { logQueryFailure('live', err); return []; });

		const hasMore = rows.length > limit;
		const agents  = rows.slice(0, limit).map(mapAgent);

		// First page only: cheap platform-pulse counts for the header stats. Kept off
		// the paginated hot path so scrolling never re-runs the aggregate.
		let total = null;
		let activeTotal = null;
		if (offset === 0) {
			const [t] = await sql`
				select
					count(*)::int as total,
					count(*) filter (where exists (
						select 1 from agent_actions aa where aa.agent_id = i.id
					))::int as active_total
				from agent_identities i
				where i.deleted_at is null and i.is_public = true
				  and not (i.is_published is not true and exists (
				        select 1 from users su where su.id = i.user_id and su.service_account
				      ))
				  and (
				        exists (select 1 from agent_actions aa where aa.agent_id = i.id)
				        or exists (select 1 from usage_events ue where ue.agent_id = i.id and ue.kind = 'llm')
				        or i.erc8004_agent_id is not null
				        or i.meta->'onchain' is not null
				        or i.meta->>'sol_mint_address' is not null
				        or (
				              coalesce(i.name,'') <> ''
				              and not (i.name = any(${PLACEHOLDER_NAMES}))
				              and i.name not like 'Selfie avatar%'
				           )
				      )
			`.catch((err) => { logQueryFailure('live-totals', err); return [{}]; });
			total = t?.total ?? null;
			activeTotal = t?.active_total ?? null;
		}

		return json(res, 200, {
			agents,
			count:        agents.length,
			has_more:     hasMore,
			next_offset:  hasMore ? offset + limit : null,
			total,
			active_total: activeTotal,
			generated_at: new Date().toISOString(),
		}, { 'Cache-Control': 'public, max-age=30, stale-while-revalidate=120' });
	}

	// ── newest | popular | name: keyset pagination on created_at ─────────────────
	const rows = await sql`
		select
			i.id,
			i.name,
			i.description,
			i.skills,
			i.home_url,
			coalesce((
				select count(*)::int from usage_events ue
				where ue.agent_id = i.id and ue.kind = 'llm'
			), 0) as chat_count,
			i.created_at,
			i.meta,
			i.erc8004_agent_id,
			i.chain_id,
			a.thumbnail_key  as avatar_thumbnail_key,
			a.storage_key    as avatar_storage_key,
			a.visibility     as avatar_visibility
		from agent_identities i
		left join avatars a on a.id = i.avatar_id and a.deleted_at is null
		where i.deleted_at is null
		  and i.is_public = true
		  and not (i.is_published is not true and exists (
		        select 1 from users su where su.id = i.user_id and su.service_account
		      ))
		  and (${!q} or (
		        to_tsvector('english', coalesce(i.name,'') || ' ' || coalesce(i.description,''))
		        @@ plainto_tsquery('english', ${q})
		      ))
		  and (${!skill} or i.skills @> ${[skill]}::text[])
		  and (${!before}::boolean or i.created_at < ${before}::timestamptz)
		  and (${!onchainOnly} or (
		        i.meta->'onchain' is not null
		        or i.meta->>'sol_mint_address' is not null
		      ))
		  and (${!avatarOnly} or (
		        a.storage_key is not null
		        and a.visibility in ('public', 'unlisted')
		      ))
		order by
			${sort === 'newest' ? sql`i.created_at desc` :
			  sort === 'name'   ? sql`i.name asc` :
			                      sql`chat_count desc nulls last, i.created_at desc`}
		limit ${limit + 1}
	`.catch((err) => { logQueryFailure(sort, err); return []; });

	const hasMore = rows.length > limit;
	const agents  = rows.slice(0, limit).map(mapAgent);

	return json(res, 200, {
		agents,
		count:        agents.length,
		has_more:     hasMore,
		next_cursor:  hasMore ? agents[agents.length - 1].created_at : null,
		generated_at: new Date().toISOString(),
	}, { 'Cache-Control': 'public, max-age=30, stale-while-revalidate=120' });
});