Skip to main content
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 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 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 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 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:
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, 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 reports the state and reason of each trace the import released to World capture. Hue decides excluded, evaluation and simulation before it looks for an owner.