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.

6.6 KB
Raw Blame
// LangChain JS `tool()` definitions for three.ws's generative 3D pipeline:
// forge a model from text, rig it for animation, render a turntable preview,
// animate it from a text prompt, and chat with a three.ws agent persona.
// forge/rig/render call the free, no-auth /api/mcp-studio server; animate
// calls the paid, x402-gated /api/mcp server and never pays on the caller's
// behalf (see `createAnimateTool`'s doc comment); agentChat calls the public
// /api/chat SSE endpoint.

import { tool } from '@langchain/core/tools';
import { z } from 'zod';
import { callThreeWsTool, callThreeWsChat, toolResultText } from './client.js';

/**
 * Build all five three.ws tools bound to one configuration, ready to pass
 * into `createAgent({ tools })` / `.bindTools(tools)`.
 * @param {object} [config]
 * @param {string} [config.baseUrl] override for self-hosted / staging deployments
 * @param {string} [config.apiKey] three.ws API key, only needed for the animate tool
 */
export function createThreeWsTools(config = {}) {
	return [createForgeTool(config), createRigTool(config), createRenderTool(config), createAnimateTool(config), createAgentChatTool(config)];
}

export function createForgeTool({ baseUrl } = {}) {
	return tool(
		async ({ prompt, tier }) => {
			const res = await callThreeWsTool({ baseUrl, surface: 'free', tool: 'forge_free', args: { prompt, ...(tier ? { tier } : {}) } });
			if (!res.ok) return [`forge failed: ${res.error}`, { ok: false, error: res.error }];
			return [toolResultText(res.result), { ok: true, raw: res.result.structuredContent ?? null }];
		},
		{
			name: 'three_ws_forge',
			description:
				'Generate a textured, downloadable 3D model (GLB) from a text prompt. Free, no API key required. ' +
				'Describe a single object, character, or creature.',
			schema: z.object({
				prompt: z.string().min(3).max(1000).describe('What to model, e.g. "a friendly round robot mascot, glossy white plastic".'),
				tier: z.enum(['draft', 'standard', 'high']).optional().describe('Detail level; standard is the default.'),
			}),
			responseFormat: 'content_and_artifact',
		},
	);
}

export function createRigTool({ baseUrl } = {}) {
	return tool(
		async ({ glbUrl }) => {
			const res = await callThreeWsTool({ baseUrl, surface: 'free', tool: 'rig_mesh', args: { glb_url: glbUrl } });
			if (!res.ok) return [`rig failed: ${res.error}`, { ok: false, error: res.error }];
			return [toolResultText(res.result), { ok: true, raw: res.result.structuredContent ?? null }];
		},
		{
			name: 'three_ws_rig',
			description:
				'Auto-rig a static 3D model (GLB) into an animation-ready model: adds a humanoid skeleton and skin ' +
				'weights. Free, no API key required. Provide the GLB URL of a model (e.g. one three_ws_forge just produced).',
			schema: z.object({
				glbUrl: z.string().url().describe('http(s) URL to the static GLB mesh to rig.'),
			}),
			responseFormat: 'content_and_artifact',
		},
	);
}

export function createRenderTool({ baseUrl } = {}) {
	return tool(
		async ({ glbUrl, views, size }) => {
			const res = await callThreeWsTool({
				baseUrl,
				surface: 'free',
				tool: 'look_at_model',
				args: { glb_url: glbUrl, ...(views ? { views } : {}), ...(size ? { size } : {}) },
			});
			if (!res.ok) return [`render failed: ${res.error}`, { ok: false, error: res.error }];
			return [toolResultText(res.result), { ok: true, raw: res.result.structuredContent ?? null }];
		},
		{
			name: 'three_ws_render',
			description:
				'Render a turntable preview of any public .glb: several angles as images, plus its geometry stats and ' +
				'a plain reading of what they mean. Free, no API key required, works on any public https .glb.',
			schema: z.object({
				glbUrl: z.string().url().describe('Public https URL of the .glb to look at.'),
				views: z
					.array(z.enum(['front', 'three-quarter', 'side', 'back', 'top', 'bottom']))
					.max(6)
					.optional()
					.describe('Angles to render. Default: three-quarter, front, side, back.'),
				size: z.number().int().min(128).max(1024).optional().describe('Pixel size of each square frame. Default 512.'),
			}),
			responseFormat: 'content_and_artifact',
		},
	);
}

/**
 * Animate a rigged GLB from a text prompt. This is a PAID, x402-gated tool on
 * three.ws's main MCP server: calling it without a payment returns the raw
 * x402 PaymentRequired challenge as the tool's artifact instead of a model,
 * and this package never signs or sends that payment for you. Resolve the
 * challenge with your own x402 client against your own wallet (e.g. the
 * `x402-fetch` package), then pass the resulting header value in as
 * `xPayment`.
 */
export function createAnimateTool({ baseUrl, apiKey } = {}) {
	return tool(
		async ({ glbUrl, prompt, xPayment }) => {
			const res = await callThreeWsTool({
				baseUrl,
				surface: 'paid',
				tool: 'text_to_animation',
				args: { glb_url: glbUrl, prompt },
				apiKey,
				xPayment,
			});
			if (res.paymentRequired) {
				return [
					'payment required: this is a paid three.ws tool. Resolve res.artifact.challenge with your own x402 client and retry with xPayment set.',
					{ ok: false, paymentRequired: true, challenge: res.challenge },
				];
			}
			if (!res.ok) return [`animate failed: ${res.error}`, { ok: false, error: res.error }];
			return [toolResultText(res.result), { ok: true, raw: res.result.structuredContent ?? null }];
		},
		{
			name: 'three_ws_animate',
			description:
				'Retarget a text-described motion onto a rigged humanoid GLB (e.g. one three_ws_rig just produced). PAID: ' +
				'returns an x402 payment challenge unless a pre-signed X-PAYMENT value is supplied.',
			schema: z.object({
				glbUrl: z.string().url().describe('http(s) URL to a rigged GLB to animate.'),
				prompt: z.string().min(1).max(500).describe('The motion to generate, e.g. "wave hello", "walk forward".'),
				xPayment: z.string().optional().describe('A pre-signed x402 X-PAYMENT header value from your own wallet/x402 client.'),
			}),
			responseFormat: 'content_and_artifact',
		},
	);
}

export function createAgentChatTool({ baseUrl } = {}) {
	return tool(
		async ({ message, agentId }) => {
			const done = await callThreeWsChat({ baseUrl, message, agentId });
			return [done.reply, { ok: true, model: done.model, provider: done.provider }];
		},
		{
			name: 'three_ws_agent_chat',
			description: 'Send a message to a three.ws agent (or the default viewer agent) and get its reply. Free, no API key required.',
			schema: z.object({
				message: z.string().min(1).describe('What to say to the agent.'),
				agentId: z.string().uuid().optional().describe('A specific three.ws agent UUID; omit for the default agent.'),
			}),
			responseFormat: 'content_and_artifact',
		},
	);
}