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.

feat(agents): pick the model per message and bill a named paid model at its list price against the agent budget

nirholasaca6f78bda92
diff --git a/api/_lib/agent-message.js b/api/_lib/agent-message.js
new file mode 100644
index 000000000..7fd209d38
--- /dev/null
+++ b/api/_lib/agent-message.js
@@ -0,0 +1,123 @@
+// One agent turn on a chosen model: persona in, answer out.
+//
+// The model is decided by api/_lib/agent-model.js (per-message override, then
+// the agent's default, then the platform chain). This module runs the turn:
+// the agent's persona and the server tool note as the system prompt, the
+// read-only tool registry (api/_lib/agent-tools.js) when the model can call
+// tools, and the shared step loop (api/_lib/agent-loop.js), which fails over
+// across the chain before any byte streams.
+//
+// It does no billing and writes no thread rows: callers own those, because
+// they differ (the v1 messages API bills credits and writes the owner's thread;
+// call_agent answers a stranger and writes nothing). Every caller gets back the
+// same summary: the answer, the model that actually served it, token usage,
+// platform cost, and the tool calls made.
+
+import { agentToolSchemas, agentToolHandlers } from './agent-tools.js';
+import { AGENT_SYSTEM_NOTE, createAgentLoop, finalAnswer, initialLoopState, loopFinished } from './agent-loop.js';
+import { modelChain } from './agent-model.js';
+
+const MAX_TOOL_ROUNDS = 4;
+const MAX_PERSONA_CHARS = 8000;
+
+/**
+ * The system prompt an agent answers under: its persona (or a name and
+ * description fallback), the platform's one-coin rule, and the tool note when
+ * tools are offered.
+ * @param {{ name?: string, description?: string, persona_prompt?: string, system_prompt?: string, meta?: object }} agent
+ * @param {{ tools: boolean }} o
+ */
+export function agentSystemPrompt(agent, { tools }) {
+ const name = String(agent?.name || 'this agent').trim() || 'this agent';
+ const persona = String(agent?.persona_prompt || agent?.system_prompt || agent?.meta?.brain?.instructions || '').trim();
+ const desc = String(agent?.description || '').trim();
+ const parts = [persona ? persona.slice(0, MAX_PERSONA_CHARS) : `You are ${name}, an agent on three.ws.${desc ? ` ${desc}` : ''}`];
+ parts.push(
+ 'If tokens or coins come up, the only coin you may name, endorse, or recommend is $THREE ' +
+ '(contract FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump).',
+ );
+ if (tools) parts.push(AGENT_SYSTEM_NOTE);
+ return parts.join('\n\n');
+}
+
+/**
+ * Run one turn.
+ *
+ * @param {object} o
+ * @param {object} o.agent agent_identities row (name, persona_prompt, description, meta)
+ * @param {string} o.message the user's message
+ * @param {Array<{role:'user'|'assistant', content:string}>} [o.history] prior turns, oldest first
+ * @param {string|null} [o.model] resolved catalog id, or null for the platform chain
+ * @param {number|null} [o.temperature]
+ * @param {string} [o.operationId]
+ * @returns {Promise<{
+ * content: string, model: string|null, provider: string|null, tools: boolean,
+ * usage: { input: number, output: number, estimated: boolean },
+ * costMicroUsd: number|null, modelCalls: object[],
+ * toolCalls: Array<{ name: string, args: object, error: string|null }>,
+ * }>}
+ */
+export async function runAgentMessage({ agent, message, history = [], model = null, temperature = null, operationId }) {
+ const { chain, tools } = modelChain(model);
+ if (!chain.length) {
+ throw Object.assign(new Error('No language model is reachable on this deployment right now.'), {
+ status: 503,
+ code: 'llm_unavailable',
+ expose: true,
+ });
+ }
+
+ const messages = [
+ { role: 'system', content: agentSystemPrompt(agent, { tools }) },
+ ...history.filter((m) => m && (m.role === 'user' || m.role === 'assistant') && m.content),
+ { role: 'user', content: String(message) },
+ ];
+
+ const modelCalls = [];
+ const toolCalls = [];
+ const loop = createAgentLoop({
+ chain,
+ toolSchemas: tools ? agentToolSchemas() : [],
+ toolHandlers: tools ? agentToolHandlers() : {},
+ maxToolRounds: MAX_TOOL_ROUNDS,
+ ...(temperature != null ? { temperature } : {}),
+ onEvent: (event) => {
+ if (event.kind === 'model_call') modelCalls.push(event);
+ if (event.kind === 'tool_result') toolCalls.push({ name: event.tool, args: event.args, error: event.error || null });
+ if (event.kind === 'tool_blocked') toolCalls.push({ name: event.tool, args: event.args, error: `blocked: ${event.reason}` });
+ },
+ });
+
+ let { state, context } = initialLoopState({
+ operationId: operationId || `msg-${Date.now().toString(36)}`,
+ messages,
+ maxSteps: MAX_TOOL_ROUNDS * 2 + 3,
+ });
+ while (!loopFinished(state, context)) {
+ ({ state, context } = await loop.step(state, context));
+ }
+ if (state.status === 'error') {
+ const detail = String(state.error?.message || state.error || 'the model could not answer').slice(0, 300);
+ throw Object.assign(new Error(detail), { status: 502, code: 'model_failed', expose: true });
+ }
+
+ const last = modelCalls.at(-1) || null;
+ const usage = { input: 0, output: 0, estimated: false };
+ let costMicroUsd = 0;
+ for (const call of modelCalls) {
+ usage.input += call.usage?.input || 0;
+ usage.output += call.usage?.output || 0;
+ if (call.usage?.estimated) usage.estimated = true;
+ costMicroUsd = costMicroUsd == null || call.costMicroUsd == null ? null : costMicroUsd + call.costMicroUsd;
+ }
+ return {
+ content: finalAnswer(state),
+ model: last?.model || model,
+ provider: last?.provider || null,
+ tools,
+ usage,
+ costMicroUsd,
+ modelCalls,
+ toolCalls,
+ };
+}
diff --git a/api/_lib/agent-model.js b/api/_lib/agent-model.js
new file mode 100644
index 000000000..0e4bdf099
--- /dev/null
+++ b/api/_lib/agent-model.js
@@ -0,0 +1,127 @@
+// Which model answers one message or run, and the provider chain that serves it.
+//
+// Every surface that talks to an agent (the v1 messages API, the MCP call_agent
+// tool, the agent-screen concierge, the chat gateways, v1 runs) asks this module
+// the same two questions, so a model picked in one place means the same thing
+// everywhere:
+//
+// 1. Which model? A per-message override wins, then the agent's default, then
+// the platform's free-first chain (no model named).
+// 2. Which chain? The chosen model's own routes first (model-roster.js routes
+// for an open model, its single lane otherwise), then the platform chain
+// behind them, so a dead route degrades to another model's answer instead
+// of an error.
+//
+// A model without tool calling is refused for runs (a run IS a tool loop) and
+// allowed for chat, where the turn simply runs without tools.
+//
+// An agent's default model can live in three places, written by different
+// surfaces over the years. They are read in this order:
+// meta.runtime.model the v1 Agents API and the agent editor's picker
+// meta.brain.provider the MCP create_agent tool and the brain picker
+// meta.brain.model the old Library brain tab
+// Only an id the model catalog knows counts; anything else (a retired brain
+// key, a raw upstream id) is ignored and the platform chain answers.
+
+import { MODEL_CATALOG, resolveModelId, isPaidModel } from './chat-models.js';
+import { providerChain, providerChainFor } from './llm-tool-chain.js';
+import { rosterTransports } from './model-routes.js';
+
+/** A model choice the caller has to fix: unknown id, no tools for a run, sign-in needed. */
+export class ModelChoiceError extends Error {
+ /**
+ * @param {number} status
+ * @param {string} code
+ * @param {string} message
+ */
+ constructor(status, code, message) {
+ super(message);
+ this.name = 'ModelChoiceError';
+ this.status = status;
+ this.code = code;
+ this.expose = true;
+ }
+}
+
+/** The catalog id for `id` (a retired id maps forward), or null when the catalog does not know it. */
+export function catalogModelId(id) {
+ if (typeof id !== 'string' || !id.trim()) return null;
+ const resolved = resolveModelId(id.trim());
+ return MODEL_CATALOG[resolved] ? resolved : null;
+}
+
+/** Whether a catalog model can call tools. */
+export function modelHasTools(id) {
+ const model = catalogModelId(id);
+ return Boolean(model && MODEL_CATALOG[model].tools);
+}
+
+/**
+ * The agent's default model, or null when it has none the catalog knows.
+ * @param {object|null|undefined} meta agent_identities.meta
+ */
+export function agentDefaultModel(meta) {
+ const m = meta && typeof meta === 'object' ? meta : {};
+ for (const candidate of [m.runtime?.model, m.brain?.provider, m.brain?.model]) {
+ const id = catalogModelId(candidate);
+ if (id) return id;
+ }
+ return null;
+}
+
+/**
+ * Decide the model for one message or run.
+ *
+ * @param {object} o
+ * @param {string|null} [o.requested] per-message (or per-run) override
+ * @param {object|null} [o.agentMeta] the agent's meta, for its default
+ * @param {'chat'|'run'} [o.purpose]
+ * @param {boolean} [o.signedIn] false clamps paid models away
+ * @returns {{ model: string|null, source: 'message'|'agent'|'platform', tools: boolean }}
+ * @throws {ModelChoiceError}
+ */
+export function resolveMessageModel({ requested = null, agentMeta = null, purpose = 'chat', signedIn = true } = {}) {
+ if (requested != null && requested !== '') {
+ const model = catalogModelId(requested);
+ if (!model) {
+ throw new ModelChoiceError(400, 'unknown_model', `Unknown model "${String(requested).slice(0, 80)}". Pick an id from GET /api/models.`);
+ }
+ const tools = MODEL_CATALOG[model].tools === true;
+ if (purpose === 'run' && !tools) {
+ throw new ModelChoiceError(400, 'model_lacks_tools', `${model} has no tool calling, so it can chat but cannot run a task. Pick a model with tool support for runs.`);
+ }
+ if (!signedIn && isPaidModel(model)) {
+ throw new ModelChoiceError(401, 'sign_in_required', `${model} is a paid model. Sign in to use it, or pick a free model.`);
+ }
+ return { model, source: 'message', tools };
+ }
+
+ const fallback = agentDefaultModel(agentMeta);
+ if (fallback) {
+ const tools = MODEL_CATALOG[fallback].tools === true;
+ if (purpose === 'run' && !tools) {
+ throw new ModelChoiceError(400, 'model_lacks_tools', `This agent's default model (${fallback}) has no tool calling, so it cannot run a task. Name a tool-capable model for this run, or change the agent's default.`);
+ }
+ // A signed-out visitor never spends the platform's paid keys, even on an
+ // agent whose owner picked a paid default: the free chain answers them.
+ if (!signedIn && isPaidModel(fallback)) return { model: null, source: 'platform', tools: true };
+ return { model: fallback, source: 'agent', tools };
+ }
+ return { model: null, source: 'platform', tools: true };
+}
+
+/**
+ * The provider chain for a resolved model, and whether the turn may offer tools.
+ * A chat-only model leads with its own routes and runs without tools; the
+ * platform chain stays behind it (also without tools for that turn) so the
+ * message is still answered when every route of the model is down.
+ * @param {string|null} model a catalog id, or null for the platform chain
+ * @returns {{ chain: object[], tools: boolean }}
+ */
+export function modelChain(model) {
+ if (!model) return { chain: providerChain(), tools: true };
+ if (MODEL_CATALOG[model]?.tools) return { chain: providerChainFor(model), tools: true };
+ const own = MODEL_CATALOG[model]?.provider === 'roster' ? rosterTransports(model) : [];
+ const seen = new Set(own.map((r) => `${r.name}|${r.model}`));
+ return { chain: [...own, ...providerChain().filter((p) => !seen.has(`${p.name}|${p.model}`))], tools: false };
+}
diff --git a/api/_lib/inference-billing.js b/api/_lib/inference-billing.js
index 349c41d3b..1b16fa931 100644
--- a/api/_lib/inference-billing.js
+++ b/api/_lib/inference-billing.js
@@ -163,11 +163,13 @@ export function applyInferenceBudget(meta, budget) {
/**
* Every credit_ledger action that is model spend on behalf of one agent, booked
* with ref_type 'agent' and ref_id = the agent id: the flat three-ws/agent rate
- * (chat completions, the strategy loop) and the metered spend of a v1 run's
- * paid model lanes. The per-agent budget is judged against all of them, so an
- * agent cannot outrun its budget by spending through a different surface.
+ * (chat completions, the strategy loop), the metered spend of a v1 run's paid
+ * model lanes, and a v1 chat message that named a paid model and was billed at
+ * its list price (api/_lib/agents-v1/billing.js). The per-agent budget is
+ * judged against all of them, so an agent cannot outrun its budget by spending
+ * through a different surface or by naming an expensive model.
*/
-export const AGENT_SPEND_ACTIONS = Object.freeze([INFERENCE_ACTION, 'agent_run_step']);
+export const AGENT_SPEND_ACTIONS = Object.freeze([INFERENCE_ACTION, 'agent_run_step', 'agent.model']);
/** Inference credits an agent has burned today and this month (UTC). */
export async function agentInferenceSpend(agentId) {
@@ -182,7 +184,7 @@ export async function agentInferenceSpend(agentId) {
)::int AS calls_today
FROM credit_ledger
WHERE ref_type = 'agent' AND ref_id = ${String(agentId)}
- AND action IN (${AGENT_SPEND_ACTIONS[0]}, ${AGENT_SPEND_ACTIONS[1]})
+ AND action = ANY(${AGENT_SPEND_ACTIONS})
AND created_at >= (date_trunc('month', now() AT TIME ZONE 'UTC') AT TIME ZONE 'UTC')
`;
return {
@@ -391,6 +393,10 @@ export async function resumeAfterBudgetChange(agentId, previousMeta) {
* the full price (the call was admitted with a thin balance), the remaining
* balance is taken instead and the shortfall reported, never a negative balance.
*
+ * `priceUsd` replaces the published-rate price for a call that named a paid
+ * model and is billed at that model's list price; `billedModel` records the
+ * model id the price is for.
+ *
* @returns {Promise<{ chargedUsd: number, pricedUsd: number, balanceUsd: number, shortfallUsd: number, replay: boolean }>}
*/
export async function chargeInference({
@@ -403,10 +409,15 @@ export async function chargeInference({
estimated = false,
provider = null,
model = null,
+ priceUsd = null,
+ billedModel = INFERENCE_MODEL_ID,
}) {
- const pricedUsd = priceInference({ inputTokens, outputTokens });
+ const pricedUsd =
+ Number.isFinite(priceUsd) && priceUsd > 0
+ ? Math.max(INFERENCE_MIN_CALL_USD, Math.ceil(priceUsd * 1e6 - 1e-9) / 1e6)
+ : priceInference({ inputTokens, outputTokens });
const meta = {
- model: INFERENCE_MODEL_ID,
+ model: billedModel,
agent_id: agentId,
api_key_id: apiKeyId,
input_tokens: inputTokens,
@@ -461,7 +472,7 @@ export async function inferenceUsage({ userId, agent = null }) {
SELECT COALESCE(SUM(-amount_usd), 0)::float8 AS spent7,
COUNT(*)::int AS calls7
FROM credit_ledger
- WHERE user_id = ${userId} AND action IN (${AGENT_SPEND_ACTIONS[0]}, ${AGENT_SPEND_ACTIONS[1]})
+ WHERE user_id = ${userId} AND action = ANY(${AGENT_SPEND_ACTIONS})
AND (${agentId}::text IS NULL OR (ref_type = 'agent' AND ref_id = ${agentId ? String(agentId) : null}))
AND created_at > now() - interval '7 days'
`,
@@ -481,7 +492,7 @@ export async function inferenceUsage({ userId, agent = null }) {
COALESCE(SUM((meta->>'input_tokens')::bigint), 0)::bigint AS input_tokens,
COALESCE(SUM((meta->>'output_tokens')::bigint), 0)::bigint AS output_tokens
FROM credit_ledger
- WHERE user_id = ${userId} AND action IN (${AGENT_SPEND_ACTIONS[0]}, ${AGENT_SPEND_ACTIONS[1]})
+ WHERE user_id = ${userId} AND action = ANY(${AGENT_SPEND_ACTIONS})
AND (${agentId}::text IS NULL OR (ref_type = 'agent' AND ref_id = ${agentId ? String(agentId) : null}))
AND created_at >= (date_trunc('month', now() AT TIME ZONE 'UTC') AT TIME ZONE 'UTC')
`,