Skip to main content
Describe a company, its people, and the work you want your agent to handle. Hue generates the app data and publishes a World version you can reuse. You do not need production traces or a connection to a real app account.

​
Trial organizations

If you received a trial invitation from Hue, start in Worlds → Created. Once setup is ready, the demo project includes five ready-to-use Worlds and three example tiles under Users. The Users tiles remain visible but locked, with Upgrade account for access on hover or keyboard focus. Any verified member can open Agent prompt from Worlds, including after the creation allowance is used. Copy the prompt from Create world with your agent into a trusted coding agent. The prompt includes a project key for direct requests, so you do not need to install or connect an MCP server. Keep the prompt out of logs, source control and shared conversations. If the prompt does not load, choose Try again. An owner or admin can explicitly choose Create replacement key, including while setup is preparing or failed. The short tour shows the Created grid, opens a World’s starting apps and records, and finishes with the agent prompt. The preview selects and starts no instance. Replay it from Settings → Account → Take Worlds tour. An owner or admin can invite teammates from Settings → Organization, including while setup is preparing or needs a retry. They join the same organization and share its allowances. Trial allowances apply across the organization for its lifetime:
  • Three additional World creations or AI-generated versions of existing Worlds. The preloaded Worlds do not use this allowance.
  • Five World instance starts, including starts from preloaded Worlds. Restarts, resets, reproductions, forks and continuations also use this allowance.
You can delete Worlds after setup is ready. Deleting Worlds, stopping instances, or letting instances expire does not restore used allowances. Creating a World does not start an instance automatically. Inspect the ready World before choosing to start one.

​
Generate in Hue

  1. In a full-access organization, open Worlds and choose Create world.
  2. Under Or build your own, select Generate and choose an App.
  3. Describe the company in Company, and set the World name. For Slack, Acts as selects a user or bot.
  4. Choose Generate world. When generation finishes, inspect the starting data before starting an instance.

​
Generate with your coding agent

Connect to the Hue MCP server by signing in with Hue or using a Read and write key, then send:
Prompt

​
Call MCP directly

On an organization connection, pass the chosen project_id in every call.
  1. Call list_apps to find app slugs, then create_world with a name, apps, an idempotency_key, and sources.description.text:
  1. Call get_world_creation with the returned creation’s id as world_creation_id until its status is ready or failed.
  2. When ready, open world_creation.url and inspect the report. To run an agent, pass the ready world_version_id and a separate idempotency_key to start_instance, then connect to the instance.
Reuse each operation’s key when retrying it. Generation can return before planning finishes, so keep polling the same creation rather than submitting another. If it fails, inspect the reported reason before retrying. Creation publishes a version without starting an instance. Each app entry accepts an optional account to distinguish accounts of the same app. Omit sources for empty app data. Use dry_run: true to preview the outline and cost estimate without creating a World. See the World tool reference for authored definitions and custom slugs. Descriptions are processed by models and draw on your organization’s monthly AI budget.

​
Create an expanded variation

Ask your coding agent to create a separate, fuller World using an existing World and selected traces as ground truth. For example:
Prompt
Call create_world_variation with an idempotency_key, a new name, the expansion description, and one source:
  • world_version_id for an immutable World version.
  • world_model_id with at for a retained user’s World at a represented UTC time.
Optional trace_ids select up to eight completed traces whose World evidence is retained. Their observations must belong to the source accounts and agree with the facts at the source time. Set share_samples: true only when you want models to see bounded source names and text; it defaults to off. Use dry_run: true for a preview. If Hue is still preparing the source, retry the same call and idempotency key as directed. Once accepted, poll get_world_creation until ready or failed. A successful variation creates a new World with its own version. Retrying the same request returns that creation. The source World keeps its data and versions. To add a version to the same World, use create_world with sources.description.extend: true instead. Variations fill the apps already present, with one account per app and the existing generator capability limits. They omit the optional generated PDF attachments. Conflicting or unresolved facts, or incompatible accounts, require clarification. Generated additions and filled fields are labeled in the report. No instance starts automatically.

​
Build a World from one trace

To debug one failed task from a trace Hue doesn’t hold, an agent connected to the Hue MCP server can build a World from the exported trace, for the apps the build supports. The build tools are in the worlds toolset, and ?toolsets=debug or all lists them too. When a stored trace’s World capture is retained, start an instance of its user’s World instead.
  1. Export the complete trace, every observation with its inputs and outputs, and keep source credentials out of the export. The build reads two formats:
    • OTLP JSON (format: "otlp_json"): an object with resourceSpans.
    • Langfuse observations (format: "langfuse_observations"): a bare observations array, {"data": [...]} or {"observations": [...]}.
  2. Call create_world_from_trace with the export as trace_json, and the task and any facts you know, such as the project the task belongs to. trace_json takes up to 256 KiB and context up to 64 KiB. For a larger export, up to 25 MiB, reserve an upload with prepare_trace_upload, send the exact bytes with an HTTP PUT to its upload_url within 15 minutes, confirm it with complete_trace_upload and pass its upload_id. The upload URL is on a Vercel Blob storage host, not app.hue.run, so a network that restricts outbound hosts must allow it.
  3. Follow get_world_build until the build is ready, then connect to its instance.
The build first reads the trace and maps each tool call to an app, then derives the World’s records from those calls. Only the model phases after that read context. Context therefore doesn’t help a build that fails while reading or mapping the trace, such as invalid_trace or no_mapped_calls: change what the trace records instead; see What a tool call needs. If a later phase reports missing evidence, add the facts it names in a new build. Building sends redacted trace content and the context you supply to models; see AI processing. If the build reports gaps, use the World build gap codes to identify the missing evidence.

​
Import app records

For records you already hold, the World import tools accept uploaded app data and publish a World version. Trace exports use the trace build above or bulk trace import.

​
Run your agent in the World

Use the instance returned by the trace build, or call start_instance with a ready creation or import’s world_version_id and an idempotency_key. Reuse the start key when retrying that operation. Then connect your agent to the instance’s app URLs.