> ## 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.

# Worlds

> Understand how Hue builds Worlds from your traces, choose a starting state, and connect your agent to an isolated instance.

A World is the starting state of the apps your agent works in: the mailboxes, channels and records it reads and changes. When your agent runs against a World, it uses a World instance: an isolated copy of that starting state whose changes affect nothing else. Hue answers the agent's app calls from the instance, in each app's own format, and records every call and change.

Worlds let you rerun a real user's task with the same starting data each time. Your agent runs in your process with its own model and prompts; Hue serves the apps it calls. [Simulations](/evaluations/simulations) describes the apps Hue simulates.

## Worlds and traces

Hue maintains a World model for each of your users from your production traces, without any setting to turn on. The World model retains that user's history across apps and accounts. Each trace adds evidence: what their apps held, as the agent read and changed it. A World at a chosen time holds what Hue knew was true then, including facts a later trace revealed about that moment. A later trace can fill in the body of a message that already existed at that time, but nothing created afterwards is included, and new evidence never changes an instance that is already running or finished.

Hue builds these Worlds only from what your traces record. It never fetches data from your real apps, and a World never holds your app credentials. To make a user's World complete:

* **Identify the user.** [Attach a stable user ID](/guides/traces#identify-users) to every request's root span. For an entity other than a user, such as a team, set both `hue.world.entity.namespace` and `hue.world.entity.id` on the root span instead.
* **Mark production traffic.** Set `deployment.environment.name` to `production` on the resource. Traces from other environments, and traces your evaluation runs and Worlds record, never add to a user's World.
* **Import history through the import route.** Traces you bring in with [Bulk import existing traces](/guides/import-traces#what-you-get-back) add to Worlds by the origin the import recorded. Imported records sent any other way, over OTLP with a project key, count only when they declare `production` themselves, so an imported evaluation or synthetic recording never becomes a user's history.
* **Record real tool calls with content.** Capture content and record each tool call on its own span, with the MCP server identity on MCP calls; see [Traces and spans](/guides/traces#record-what-actually-happened).
* **Name the account behind each tool call.** Hue recognizes the account for some apps from their recorded calls. For other apps, or a user with several accounts of one app, set these attributes on the tool span:

| Tool-span attribute | Value |
| - | - |
| `hue.connection.provider_id` | The app, such as `google.gmail`. |
| `hue.connection.account_id` | Your stable ID for this user's connection to the app. |
| `hue.connection.generation` | A positive integer; increase it when the connection is replaced. |
| `hue.connection.scope` | Optional: a stable partition of the app, such as a workspace. |
| `hue.connection.principal` | Optional: the app's acting identity, when the app needs one. |

In TypeScript, set them inside `hue.tool` with `trace.getSpan(hue.getContext())?.setAttributes(...)`; in Python, use `tool.otel_span.set_attributes(...)` inside `with hue.tool(...) as tool`. A tool argument or a matching email address does not identify an account, and these attributes never hold OAuth tokens or credentials.

## Choose the starting state

Every instance starts from an immutable starting World, so instances started from the same one begin in the same state.

| Starting state | Use it when | How |
| - | - | - |
| A user's World at a chosen time | Reproducing what a real user's apps held | Open the user's World in **Worlds**, set **World time (UTC)** and choose **Start instance**. |
| A case's World | Evaluating your agent on a recorded task | A case built from a production trace uses that user's World at the trace's start time when Hue can tie the trace's app calls to the user's accounts, and otherwise a World built from the trace alone. `hue eval` starts a fresh instance for each case of a run; see [Run your agent](/evaluations/run-your-agent). |
| A World version | Trying your agent on a World you authored or built | Start an instance from the version's page in **Worlds**, or with `start_instance` over MCP. |
| A World built from one trace | Debugging one failed task | Submit the trace with `create_world_from_trace` over MCP; see [below](#build-a-world-from-one-trace). |
| A definition in your repository | Fixtures you maintain beside your agent's code | Publish it with the TypeScript SDK's [World client](/reference/typescript#world-client). |

A run fixes its starting Worlds when it begins, and each case execution, including a retry, gets its own instance. To reproduce an earlier instance of a user's World, select it on the World's page and choose **Run original**: Hue starts a fresh instance from the same starting World, without the earlier agent's changes. Reproducing needs the original evidence to still be retained.

## Use an instance

An instance gives your agent a URL for each app the World includes and a world token to use as the app's credential.

* **URLs.** Each app keeps its real API paths under a Hue base URL: `https://app.hue.run/api/sim/<real host>/<real path>`. Gmail's REST API becomes `https://app.hue.run/api/sim/gmail.googleapis.com/gmail/v1`, and Slack's Web API becomes `https://app.hue.run/api/sim/slack.com/api/`. Replace only the base URL in your agent's existing client; [Connect your agent](/evaluations/eval-ready-agent#framework-setup) covers clients that need more.
* **World token.** Send the token where the real credential went, usually `Authorization: Bearer <token>`. It is scoped to one instance and expires with it. It is not a Hue project key, and it cannot reach your real apps or other instances.

In an evaluation, `hue eval` passes these to your agent as environment variables, `HUE_SIM_<SURFACE>_URL` and `HUE_WORLD_TOKEN`. [Connect your agent](/evaluations/eval-ready-agent) adds one helper so the agent uses them during an evaluation and its production values otherwise.

To use an instance by hand:

1. Start it as above. An instance you start this way lasts up to four hours.
2. Read its connection values: the **Sim URL & Token** tab on the instance in Hue, or `get_instance_connections` over MCP, which returns each app's URL, protocol and where the token goes. Revealing them needs write access and is audited. Keep the token in your agent's secret configuration.
3. Point the agent's app clients at those values and run the task.
4. Inspect what happened: the instance's **State** and **Server** tabs in Hue, or `get_instance_state`, `list_instance_requests`, `list_instance_steps` and `get_instance_diff` over MCP.
5. Stop the instance when the attempt ends. For a fresh attempt, restart an instance of an authored World, or start another instance of a user's World. A stopped instance's data and requests stay inspectable.

Starting, restarting, stopping and revealing connections need a **Read and write** key or a sign-in connection. A **Read** connection can inspect saved instances. The [MCP tools](/agents/mcp-tools#worlds) reference lists every World tool and its arguments.

## Build a World from one trace

To debug a single failed task, an agent connected to the [Hue MCP server](/agents/mcp-server) with `?toolsets=debug` can build a World from one exported trace, for the apps the build supports.

1. Export the complete trace, every observation with its inputs and outputs, as Langfuse observations or OTLP JSON, and keep source credentials out of the export.
2. Call `create_world_from_trace` with the export, the task and any facts you know, such as the project the task belongs to. Larger exports upload first with `prepare_trace_upload` and `complete_trace_upload`.
3. Follow `get_world_build` until the build is ready, then use its instance as above. If the build 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](/guides/redaction#ai-processing).


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