> ## 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 from traces

> Link traces to users, capture their app history, and choose a starting checkpoint for a World instance.

Hue maintains a World model for each of your users from completed traces, without any setting to turn on. The World model retains that user's history across apps and accounts. Each eligible trace adds evidence: what their apps held, as the agent read and changed it.

## Capture app history

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](https://docs.hue.run/guides/traces.md#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. Hue reads a trace's owner from the agent's own spans, each with its resource:
  * It reads the trace's local roots (spans whose parent is not in the trace) first. Only when they name nobody does it read the agent's other spans and the log records correlated with them.
  * It never reads a tool span or anything beneath it, so an account a tool acted on never becomes the trace's user.
  * An explicit entity pair wins over a user ID. Everything read at the deciding step must name the same user or entity, because a trace has one owner; otherwise the trace stays unresolved.
  * The [field glossary](https://docs.hue.run/agents/mcp-tools.md#field-glossary) lists the user keys Hue reads, including those of other instrumentations.
* **Record completed user requests.** Completed traces can contribute from any environment, with or without an environment label. Traces linked to Hue runs or World instances, and Hue evaluation or simulation traces, never add to a user's World. Deliberate capture exclusions still apply.
* **Import history.** Traces you bring in with [Bulk import existing traces](https://docs.hue.run/guides/import-traces.md#what-you-get-back) retain the origin the import recorded. Both that route and historical records sent over OTLP with a project key follow the capture rules above. Verification does not override capture exclusions.
* **Record real tool calls with content.** Capture content and record each tool call on its own span, with what Hue needs to [recognize the app](https://docs.hue.run/guides/traces.md#what-a-tool-call-needs-for-hue-to-recognize-the-app) it reached.
* **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 a checkpoint

A checkpoint instance starts with the retained values shown in its preview, including last-observed values after a change whose result is unknown. Explicit removals and field invalidations still apply, and missing fields stay absent. Later traces can add evidence about that time, including a message body recorded later. Records created after the checkpoint stay excluded. An instance's starting state stays fixed as new evidence arrives.

A World at a given time holds only the records that some trace placed there, or that the app's recorded responses prove existed and were visible to the account at that time. A creation timestamp alone is not that proof. The first trace of a new user therefore starts from a World without the records that trace read, and so does a case built from it. A returning user's World starts with what earlier traces established.

## Start an instance over MCP

When a stored trace's World capture is `retained`, its evidence is already in the owner's World model and needs no separate build. Check the trace's [World capture state](#why-a-trace-added-nothing-to-a-world-model), then use `list_world_models` and `get_world_model` to find the model. `start_instance` with `world_model_id`, a UTC time as `at` and an `idempotency_key` starts an instance of the user's World at that time and returns its app URLs and token once.

* **Preparing.** While Hue prepares the World, the call fails with `unavailable`, the message `World is preparing` and a retry delay. Call again with the same `idempotency_key` and arguments. Hue returns the same instance once it is ready.
* **Refused.** A refusal adds `preparation` to the error's `_meta` under `hue.run/error`. Its `state` is `insufficient_evidence` or `processing_limit`, which the same input never resolves, or `dependency_unavailable`, which you can retry. A refusal you can't retry also names the `failure_code` the reconstruction recorded, such as `unresolved_world`.

## Why a trace added nothing to a World model

Once Hue holds a trace's evidence, `get_trace` reports its World capture in `world`. Its `state` is `pending` until Hue classifies the trace's latest spans, including while the trace runs or an import holds it, then `retained` (the evidence is in the owner's World model), `unresolved` or `ineligible`. Hue doesn't classify a trace that an import excludes as evaluation or simulation traffic. `get_trace` keeps such a trace `pending`, and `get_trace_import` counts it in `progress.traces.excluded`. An unresolved or ineligible trace carries the `reason` Hue recorded, when it recorded one. [Bulk import](https://docs.hue.run/guides/import-traces.md#what-you-get-back) reports the state and reason of each trace the import released to World capture.

| Reason | State | Meaning |
| - | - | - |
| `missing_entity` | `unresolved` | No agent span names a user or entity; a user recorded only on a tool span doesn't count. Record a user ID on the agent's spans, or for an import see [Identity](https://docs.hue.run/guides/import-traces.md#identity). |
| `ambiguous_entity` | `unresolved` | The spans read at the deciding step name different users or entities. |
| `invalid_entity` | `unresolved` | An entity pair is missing one of its attributes, an ID or namespace holds a NUL character or malformed Unicode, or an ID is longer than 16 KiB or a namespace is longer than 128 bytes. |
| `owner_conflict` | `unresolved` | The trace now names a different user than the World model that already holds its evidence. Hue doesn't move evidence between users. |
| `excluded` | `ineligible` | The trace was deliberately excluded from World capture. |
| `evaluation` | `ineligible` | The trace is linked to a Hue run or World instance, or its spans carry a Hue run's execution ID. |
| `simulation` | `ineligible` | The trace's own spans show it used a Hue World instance or simulated app. |
| `erased` | `ineligible` | The user's World model was erased. |

Hue decides `excluded`, `evaluation` and `simulation` before it looks for an owner.


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