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.

9.4 KB
Raw Blame
// v1 agents: create, read, update, delete, and the running/stopped lifecycle.
//
// Agents are the same agent_identities rows every other surface reads; creation
// goes through createAgentIdentity (api/_lib/agent-create.js) so a v1 agent gets
// the identical custodial wallets, identity-integrity check and discovery pings
// as one made in the Studio. v1-only settings (model, temperature, strategy)
// live under meta.runtime.

import { sql } from '../db.js';
import { createAgentIdentity } from '../agent-create.js';
import { MODEL_CATALOG } from '../chat-models.js';
import { env } from '../env.js';
import { apiError, strParam, numParam } from './http.js';
import { getStrategy } from './strategies.js';
import { createAutomation } from './automations.js';
import {
	normalizeInferenceBudget,
	getInferenceBudget,
	resumeAfterBudgetChange,
	InferenceBillingError,
} from '../inference-billing.js';

const MAX_SKILLS = 30;

/** Public-safe v1 projection of an agent row, for its owner. */
export function serializeAgent(row) {
	const meta = row.meta || {};
	const runtime = meta.runtime || {};
	return {
		id: row.id,
		name: row.name,
		persona: row.description || null,
		systemPrompt: row.persona_prompt || null,
		model: runtime.model || null,
		temperature: runtime.temperature ?? null,
		strategy: runtime.strategy || null,
		inferenceBudget: serializeBudget(meta),
		skills: row.skills || [],
		status: row.status || 'running',
		statusChangedAt: row.status_changed_at || null,
		wallet: {
			solana: meta.solana_address || null,
			evm: row.wallet_address || null,
		},
		avatarId: row.avatar_id || null,
		isPublic: row.is_public !== false,
		url: `${env.APP_ORIGIN}/agents/${row.id}`,
		createdAt: row.created_at,
		updatedAt: row.updated_at || null,
	};
}

/** The owner-set inference budget in credits (USD), or null when uncapped. */
function serializeBudget(meta) {
	const b = getInferenceBudget(meta);
	if (!b) return null;
	const exhausted = meta.inference_budget?.exhausted || null;
	return {
		daily: b.daily_usd,
		monthly: b.monthly_usd,
		exhausted: exhausted ? { window: exhausted.window, at: exhausted.at } : null,
	};
}

/**
 * The validated `inferenceBudget` of a PATCH body as the meta fragment to
 * store: `{ inference_budget: {...} }`, or `{}` when the caller cleared it.
 * Absent from the body means untouched (undefined).
 */
function readBudget(body) {
	const raw = 'inferenceBudget' in body ? body.inferenceBudget : 'inference_budget' in body ? body.inference_budget : undefined;
	if (raw === undefined) return undefined;
	let budget;
	try {
		budget = normalizeInferenceBudget(raw);
	} catch (err) {
		if (err instanceof InferenceBillingError) throw apiError(400, 'invalid_parameter', err.message, { parameter: 'inferenceBudget' });
		throw err;
	}
	if (!budget) return {};
	return { inference_budget: { ...budget, updated_at: new Date().toISOString() } };
}

/**
 * Load an agent the caller owns, or throw 404 / 403.
 * @returns {Promise<object>} the agent_identities row
 */
export async function loadOwnedAgent(id, userId) {
	const [row] = await sql`SELECT * FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
	if (!row) throw apiError(404, 'not_found', 'No agent with that id.');
	if (row.user_id !== userId) throw apiError(403, 'forbidden', 'This agent belongs to another account.');
	return row;
}

function validateModel(model) {
	if (model == null) return null;
	if (typeof model !== 'string' || !MODEL_CATALOG[model]) {
		throw apiError(400, 'unknown_model', 'model must be an id from GET /api/v1/models.', { parameter: 'model' });
	}
	if (!MODEL_CATALOG[model].tools) {
		throw apiError(400, 'model_lacks_tools', 'That model has no tool-calling endpoint, so it cannot run an agent.', { parameter: 'model' });
	}
	return model;
}

function validateSkills(skills) {
	if (skills == null) return null;
	if (!Array.isArray(skills) || skills.length > MAX_SKILLS || skills.some((s) => typeof s !== 'string' || !/^[a-z0-9][a-z0-9-_]{0,39}$/i.test(s))) {
		throw apiError(400, 'invalid_parameter', `skills must be an array of up to ${MAX_SKILLS} skill ids.`, { parameter: 'skills' });
	}
	return [...new Set(skills)];
}

function readSettings(body, { partial }) {
	const out = {};
	if (!partial || 'name' in body) out.name = strParam(body.name, { name: 'name', max: 80, required: !partial });
	if ('persona' in body) out.persona = strParam(body.persona, { name: 'persona', max: 500 });
	if ('systemPrompt' in body) out.systemPrompt = strParam(body.systemPrompt, { name: 'systemPrompt', max: 8000 });
	if ('model' in body) out.model = validateModel(body.model);
	if ('temperature' in body) out.temperature = numParam(body.temperature, { name: 'temperature', min: 0, max: 2 });
	if ('skills' in body) out.skills = validateSkills(body.skills);
	if ('strategy' in body && body.strategy != null) {
		const s = getStrategy(body.strategy);
		if (!s) throw apiError(400, 'unknown_strategy', 'strategy must be an id from GET /api/v1/strategies.', { parameter: 'strategy' });
		out.strategy = s;
	}
	return out;
}

/** List the caller's agents, newest first, keyset-paginated. */
export async function listAgents(userId, { limit, cursor }) {
	let anchor = null;
	if (cursor) {
		[anchor] = await sql`SELECT created_at, id FROM agent_identities WHERE id = ${cursor} AND user_id = ${userId}`;
	}
	const rows = await sql`
		SELECT * FROM agent_identities
		WHERE user_id = ${userId} AND deleted_at IS NULL
		  AND (${anchor?.created_at ?? null}::timestamptz IS NULL
		       OR (created_at, id) < (${anchor?.created_at ?? null}::timestamptz, ${anchor?.id ?? null}::uuid))
		ORDER BY created_at DESC, id DESC
		LIMIT ${limit + 1}
	`;
	const hasMore = rows.length > limit;
	const items = rows.slice(0, limit);
	return { items: items.map(serializeAgent), hasMore, nextCursor: hasMore ? items.at(-1).id : null };
}

/**
 * Create an agent. A strategy preset fills skills, persona text and
 * temperature the caller left out, and installs its default automations
 * (which never spend). Returns `{ agent, automations }`.
 */
export async function createAgent(userId, body) {
	const s = readSettings(body, { partial: false });
	const strategy = s.strategy || null;
	const runtime = {
		model: s.model ?? null,
		temperature: s.temperature ?? strategy?.temperature ?? null,
		strategy: strategy?.id ?? null,
	};
	const created = await createAgentIdentity({
		userId,
		name: s.name,
		description: s.persona ?? null,
		skills: s.skills ?? strategy?.skills ?? null,
		personaPrompt: s.systemPrompt ?? strategy?.persona ?? null,
		meta: { runtime },
	});
	if (created.blocked) {
		throw apiError(409, 'identity_conflict', created.blocked.message, { integrity: created.blocked.integrity });
	}
	const agent = created.agent;
	const automations = [];
	for (const preset of strategy?.automations || []) {
		automations.push(await createAutomation({ agent, userId, body: preset, source: `strategy:${strategy.id}` }));
	}
	return { agent: serializeAgent(agent), automations };
}

/**
 * Patch an agent's settings. Unknown fields are ignored; meta is merged.
 * `inferenceBudget: { daily, monthly } | null` caps the credits its model calls
 * may burn (api/_lib/inference-billing.js); changing it clears a recorded
 * exhaustion and restarts an agent the budget had stopped.
 */
export async function updateAgent(agent, body) {
	const s = readSettings(body, { partial: true });
	const budget = readBudget(body);
	const runtime = { ...(agent.meta?.runtime || {}) };
	if ('model' in s) runtime.model = s.model;
	if ('temperature' in s) runtime.temperature = s.temperature;
	if (s.strategy) runtime.strategy = s.strategy.id;
	if ('strategy' in body && body.strategy == null) runtime.strategy = null;
	const [row] = await sql`
		UPDATE agent_identities SET
			name = COALESCE(${s.name ?? null}, name),
			description = CASE WHEN ${'persona' in s} THEN ${s.persona ?? null} ELSE description END,
			persona_prompt = CASE WHEN ${'systemPrompt' in s} THEN ${s.systemPrompt ?? null} ELSE persona_prompt END,
			skills = COALESCE(${s.skills ?? null}::text[], skills),
			meta = CASE WHEN ${budget !== undefined}
				THEN (meta - 'inference_budget') || ${JSON.stringify(budget || {})}::jsonb
				ELSE meta END || ${JSON.stringify({ runtime })}::jsonb,
			updated_at = now()
		WHERE id = ${agent.id} AND deleted_at IS NULL
		RETURNING *
	`;
	if (budget !== undefined && (await resumeAfterBudgetChange(agent.id, agent.meta))) {
		row.status = 'running';
	}
	return serializeAgent(row);
}

/** Soft-delete an agent; its automations stop and its open runs are cancelled. */
export async function deleteAgent(agent) {
	await sql.transaction([
		sql`UPDATE agent_identities SET deleted_at = now() WHERE id = ${agent.id}`,
		sql`UPDATE agent_automations SET enabled = false, updated_at = now() WHERE agent_id = ${agent.id}`,
		sql`
			UPDATE agent_runs SET status = 'cancelled', error = 'agent deleted', finished_at = now(), updated_at = now()
			WHERE agent_id = ${agent.id} AND status IN ('scheduled', 'queued', 'running', 'paused')
		`,
		sql`DELETE FROM agent_actions WHERE agent_id = ${agent.id}`,
		sql`DELETE FROM agent_memories WHERE agent_id = ${agent.id}`,
	]);
	return { id: agent.id, deleted: true };
}

/**
 * Move an agent between running and stopped. Stopping pauses its automations,
 * wallet intents and runs where they stand; starting resumes all of them.
 */
export async function setAgentStatus(agent, status) {
	const [row] = await sql`
		UPDATE agent_identities SET status = ${status}, status_changed_at = now(), updated_at = now()
		WHERE id = ${agent.id} AND deleted_at IS NULL
		RETURNING *
	`;
	return serializeAgent(row);
}