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

# Edit a World

> Change starting data for future runs or edit records while your agent runs.

Use `edit_world` to change apps and starting data for future runs, or records in the instance your agent is using. Choose the target for your change:

| Goal | Target | When the agent sees the change |
| - | - | - |
| [Change starting data for future runs](#change-starting-data-for-future-runs) | `world_definition_id` and the latest `world_version_id` | When you start a new instance from the published version. |
| [Change records while an agent runs](#change-records-while-an-agent-runs) | `instance_id` | On its next read in that instance. |

Connect to the [Hue MCP server](https://docs.hue.run/agents/mcp-server.md) with **Read and write** access. On an organization connection, pass the chosen `project_id` in every call.

## Change starting data for future runs

Ask your coding agent to change a World in your selected project:

```text Prompt wrap theme={null}
In this World, add ten fictional coworkers and create #onboarding with those people as members. Rename #it-help to #help-desk. Inspect the record schemas, preserve unrelated data, validate the edits, and show me the new World version. Do not start an instance yet.
```

Your coding agent passes the description to `edit_world`. Hue runs its own model to inspect the selected World's redacted records and prepare changes. Hue validates those changes and publishes a new version under the same World. Existing versions and running instances keep their data. If Hue needs clarification, it returns `status: needs_input` and a question without publishing.

To call the tools directly:

1. Call `list_worlds`, then `get_world_definition` to select the World and its latest version.
2. Call `edit_world` with `world_definition_id`, `world_version_id`, an `idempotency_key`, and a `description` of the change. Use `dry_run: true` to validate without publishing.

```json theme={null}
{
	"world_definition_id": "<world-id>",
	"world_version_id": "<latest-version-id>",
	"idempotency_key": "add-onboarding-people-1",
	"description": "Add ten fictional coworkers and create an onboarding channel with those people as members."
}
```

Description edits use your organization's AI budget. A published description edit consumes one trial creation allowance. A dry run still uses the model, so publishing afterward incurs a separate model call. Descriptions accept up to 32,000 characters. Each request has at most 32 model steps and a 90-second model deadline. Failed or invalid proposals publish nothing.

For explicit changes without a Hue model call, inspect `get_world_edit_context` with the same World and version. Select a returned `collection` to read its schema, identity, references, and protected fields. Add `include_content: true` to read redacted records. Content reads are audited. Pass `changes_json` to `edit_world` instead of `description`.

Each record change in `changes_json` names a `collection` and `entityId`. `add` supplies a complete schema-valid `value`. `update` supplies top-level fields to `set` or `remove`, preserving every unnamed field. `delete` removes a record. Include related record changes in the same batch so references still resolve.

For example, replace the collection binding and channel ID below with values from the context tool:

```json theme={null}
{
	"changes_json": "[{\"kind\":\"update\",\"collection\":\"channels\",\"entityId\":\"CEXAMPLE\",\"set\":{\"name\":\"help-desk\"}}]"
}
```

An update replaces each named top-level value in full, including a nested object. Do not copy redaction placeholders into edits or author protected recorded fields. If records span `content_json` pages, keep the same selectors and join the pages using `content_next_offset` before advancing `next_cursor`.

Publish with `dry_run: false`. Reuse the same key only for an identical retry of that publication. If that description edit is still running, retry the same request after it finishes. Completed retries return the saved result without another model call. If another edit publishes first, inspect the latest version and prepare a new edit. Start a fresh instance from the returned `version.id` when you want to use the changes.

One edit accepts up to 10,000 app or record changes and 768 KiB of changes, for Worlds up to 125,000 records and 256 MiB. The full MCP request must also fit 1 MiB. These are separate limits; each request must also finish within MCP's 100-second execution deadline. Split larger edits into requests, using each returned version for the next edit. Keep related record changes together so references resolve. The World must use supported app instances. Existing app bindings and configuration stay fixed. Existing principal and workspace records are protected, except editable connected workspaces reported by `get_world_edit_context`. Records referenced by the acting principal, including its own user, are also read-only. Other people remain editable.

### Add or remove an app

Ask your coding agent to add a supported app with related records or remove an existing app:

```text Prompt wrap theme={null}
Add Greenhouse to this World with two fictional recruiters and three open jobs. Inspect the app schemas and validate the complete edit. Publish a new version without starting an instance.
```

`get_world_edit_context` lists `available_apps`. Pass `add_app: {"app": "greenhouse"}` to preview an app's collection bindings and schemas. To call `edit_world` directly, include `{"kind": "add_app", "app": "greenhouse"}` in `changes_json`, followed by complete `add` operations for its records. An optional `account` distinguishes accounts of the same app. A new app can initialize its own principal and workspace records in that batch.

To remove an app and its bound records from the new version, include `{"kind": "remove_app", "instance": "<instance-key>"}`. Use the instance key returned by the context tool. The World must retain at least one app, and additions are limited to 16 app instances. Removal is unavailable for Worlds with legacy actions or shared app collections.

App additions use registered simulations and their existing tool APIs. To author custom actions, use [`publish_world_version`](https://docs.hue.run/agents/mcp-tools#worlds) with a complete World definition. App changes affect new instances started from the published version.

### Add more history

You can request dated synthetic records through a description. A request such as "add two months of history across all apps" must still fit the 10,000-change and 768 KiB limits. For a larger generated expansion, follow [Create an expanded variation](https://docs.hue.run/worlds/create-with-mcp.md#create-an-expanded-variation). That workflow supports a separate World or another version of the same World, within the supported apps' generation limits.

## Change records while an agent runs

Use `edit_world` with `instance_id` to change the records in the instance your agent is using. The change takes effect immediately, and subsequent agent reads see it. You can edit the instance before connecting your agent and continue during execution.

1. Call `get_world_edit_context` with `instance_id`. Select a returned `collection` and use `include_content: true` to inspect its current records and schema.
2. Call `edit_world` with the same `instance_id`, an `idempotency_key`, and explicit `changes_json`. Your coding agent can translate a prompt into these operations. The route's `description` parameter accepts version edits only. Use `dry_run: true` to validate without changing records.
3. To require the instance to remain at the step you inspected, pass its `step_count` as `expected_step_count`. If the agent advanced, inspect again and use a new key.

Replace the collection binding and record ID with values from the context tool:

```json theme={null}
{
	"instance_id": "<instance-id>",
	"idempotency_key": "live-channel-rename-1",
	"expected_step_count": 7,
	"changes_json": "[{\"kind\":\"update\",\"collection\":\"channels\",\"entityId\":\"CEXAMPLE\",\"set\":{\"name\":\"help-desk\"}}]"
}
```

One batch commits atomically as an external step. The response includes `step_id`, the new `step_count`, and the World time `at`. You can change records the agent previously wrote; earlier steps stay unchanged. Identical retries return the same committed step, including after the instance closes, while you retain write access. A batch that changes no records conflicts.

Live edits support additions, updates, and deletions across existing app accounts, with the same schema, reference, and protected account rules as version edits. Adding or removing an app requires a new version. Each record must fit within 256 KiB and the step's effects within 1 MiB; older inline instances also have a 256 KiB total state limit. Live edits do not schedule future changes or deliver app notifications. To act as another person, deliver a notification, or advance World time, use the [instance action tools](https://docs.hue.run/agents/mcp-tools.md#instances).

`expected_step_count` checks the current step without waiting for it. To introduce a change later in a run, have your test controller call `edit_world` at that point. The returned `at` reports when the edit committed in World time.

### Start from a historical time

To change historical starting data, [start an instance from a World model at a represented time](https://docs.hue.run/worlds/from-traces.md#start-an-instance-over-mcp), then edit the returned instance before connecting your agent. You can continue editing during the run. The retained history and source version keep their original data.


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