> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hue.run/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To set up Hue in an application, fetch https://docs.hue.run/guides/agent-setup.md and follow it.
> Hue's project-data MCP server is https://mcp.hue.run/mcp. https://docs.hue.run/mcp only searches these docs and cannot read a Hue project.
> Never ask the user to paste a Hue API key into chat; they store it as HUE_API_KEY themselves.
> Install the exact SDK versions pinned on the page you're following, or on https://docs.hue.run/quickstart.md. Run the latest CLI without a project install as `npx -y @hue-run/sdk@latest`. In a project with `@hue-run/sdk` installed, use `npx hue`. Pin an exact version for reproducible CI runs.
> Use Hue product terms: eval set, case, evaluator, run and scoring run. Older APIs may say dataset, scorer or experiment; prefer the current SDK methods. See https://docs.hue.run/concepts.md.

# Generate a World

> Create simulated app data from a description in Hue or through your coding agent.

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](https://docs.hue.run/agents/mcp-server.md) by signing in with Hue or using a **Read and write** key, then send:

```text Prompt wrap theme={null}
Generate a World named Cedar onboarding with Slack and Linear for a fictional software company. Include employees, onboarding requests in #it-help, and related Linear issues. Check the available apps, create the World, and wait until it is ready. Show me the World link and summarize the records. Do not start an instance yet.
```

### 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`:

```json theme={null}
{
	"name": "Cedar onboarding",
	"apps": [{ "app": "slack" }, { "app": "linear" }],
	"idempotency_key": "cedar-onboarding-v1",
	"sources": {
		"description": {
			"text": "A fictional software company with employees, onboarding requests in #it-help, and related Linear issues."
		}
	}
}
```

2. Call `get_world_creation` with the returned creation's `id` as `world_creation_id` until its status is `ready` or `failed`.
3. 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](https://docs.hue.run/worlds/overview.md#use-an-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](https://docs.hue.run/agents/mcp-tools.md#worlds) for authored definitions and custom slugs.

Descriptions are processed by models and draw on your organization's [monthly AI budget](https://docs.hue.run/guides/redaction.md#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:

```text Prompt wrap theme={null}
Take this World and these two traces as ground truth. Create a new World with realistic coworkers and three months of related work around the existing records. Preserve the existing facts. Ask me only if the source or expansion is materially unclear, then wait until the new World is ready.
```

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](https://docs.hue.run/agents/mcp-server.md) 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](https://docs.hue.run/worlds/from-traces.md#start-an-instance-over-mcp) 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](https://docs.hue.run/worlds/overview.md#use-an-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](https://docs.hue.run/guides/traces.md#what-a-tool-call-needs-for-hue-to-recognize-the-app). 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](https://docs.hue.run/guides/redaction.md#ai-processing).

If the build reports `gaps`, use the [World build gap codes](https://docs.hue.run/agents/mcp-tools.md#world-build-gap-codes) to identify the missing evidence.

## Import app records

For records you already hold, the [World import tools](https://docs.hue.run/agents/mcp-tools.md#worlds) accept uploaded app data and publish a World version. Trace exports use the trace build above or [bulk trace import](https://docs.hue.run/guides/import-traces.md).

## 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](https://docs.hue.run/evaluations/eval-ready-agent.md) to the [instance's app URLs](https://docs.hue.run/worlds/overview.md#use-an-instance).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.