@three-ws/create-agent

@three-ws/create-agent

One command from a sentence to a rigged, animated 3D agent you can embed anywhere. npm create @three-ws/agent "a friendly cartoon astronaut"

npx -y @three-ws/create-agent
View on GitHubStar the repo

@three-ws/create-agent

One command from a sentence to a rigged 3D character you can put on your site.

npm create @three-ws/agent "a friendly cartoon astronaut in a glossy white suit"

three.ws building "a friendly cartoon astronaut in a glossy white suit"
  a rigged humanoid, free lane, no account needed

· sent to the three.ws forge
· generating the figure (15s)
· generating the figure, then the skeleton (60s)
✓ model ready
· downloading the model

Friendly Cartoon Astronaut is ready in 94s

  folder  a-friendly-cartoon-astronaut/
          index.html
          agent.json
          README.md
          agent.glb (3.4 MB)
  viewer  https://three.ws/viewer?src=…

  Paste this anywhere:

  <script type="module" src="https://three.ws/agent-3d/latest/agent-3d.js"></script>

  <agent-3d body="https://three.ws/cdn/…/rigged.glb"
            name="Friendly Cartoon Astronaut"
            style="width:100%;max-width:420px;height:520px"></agent-3d>

  Open the demo:  npx serve a-friendly-cartoon-astronaut

No account. No API key. No signup. The generation runs on the three.ws free lane, and the platform's own provider keys cover it.

#What you get

File What it is
agent.glb The model, with a humanoid skeleton, so it can be posed and animated. Opens in Blender, Unity, Godot, or any glTF tool.
index.html A working demo page. Double click it.
agent.json The record: prompt, hosted URLs, backend, timing.
README.md How to embed it and where to go next.

#Options

npm create @three-ws/agent "a knight in worn steel armor" --out ./knight
npm create @three-ws/agent --photo https://example.com/me.jpg --name "Me"
npm create @three-ws/agent "a small ceramic frog figurine" --object
Option Meaning
--photo <url> Build from a public https reference image instead of a description
--out <dir> Where to write the project (default: a slug of the description)
--name <name> Display name (default: derived from the description)
--object An object or prop (mesh only, free lane) instead of a rigged character
--no-download Keep the hosted model URL, skip writing agent.glb
--json Print the result as JSON and nothing else
--origin <url> API origin (default https://three.ws)

Describe one full-body humanoid in a neutral standing pose for the best rig. Lead with the subject, then materials and colours: the free lane conditions on roughly the first 77 characters, so front-load what matters.

#Programmatic use

import { createAgent } from '@three-ws/create-agent';

const made = await createAgent({
	prompt: 'a friendly cartoon astronaut',
	out: './astro',
	onProgress: ({ message }) => console.log(message),
});

made.result.glbUrl; // hosted, durable
made.result.rigged; // true
made.dir; // absolute path to the project
Export What it does
createAgent(opts) The whole pipeline: generate, scaffold, download
callForge({ tool, args, ... }) One forge call (forge_avatar or forge_free)
downloadModel(url) Fetch the model bytes with a deadline
projectFiles(...), demoPage(...), embedSnippet(...) The scaffold, as pure functions
ForgeError Carries code: timeout, unreachable, no_model, rpc_error, http_<status>

Everything takes { fetchImpl, signal, origin }, so it runs against a local three.ws, a proxy, or a test double.

#How long it takes

A rigged character is generation plus rigging, usually one to three minutes; rigging is the slow half. An --object is faster. Every call carries an explicit deadline (10 minutes) and reports real elapsed time, never an invented progress bar. If the deadline hits, the job may still finish: finished models land at https://three.ws/creations.

#License

Apache-2.0