Skip to main content
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 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 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 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.
  • 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 the starting state

Every instance starts from an immutable starting World, so instances started from the same one begin in the same state. 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 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 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 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 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.