Worlds

A world is a simulated system of connected services and records. A blueprint describes its starting state and tasks. This walkthrough models a company’s invoice triage workflow. Compile checks the blueprint. Launch starts the twins, saves a world version, and creates the task suite. Every launch is a new version with new twins. Use a configured SDK client. The examples share that client and the IDs returned by earlier steps.

Methods

Method	HTTP	Does
`worlds.examples.list()`	`GET /v1/worldsmith/examples`	List built-in example blueprints.
`worlds.compile(blueprint)`	`POST /v1/worldsmith/compile`	Validate a blueprint without launching.
`worlds.create(blueprint, idempotency_key, ...)`	`POST /v1/worldsmith/worlds`	Launch a world, or a new version of one.
`worlds.list()`	`GET /v1/worldsmith/worlds`	List saved worlds.
`worlds.retrieve(world_id)`	`GET /v1/worldsmith/worlds/{worldId}`	Read a world: status, twins, tasks.
`worlds.wait(world_id)`	polls the above	Block until the world is `ready` or `failed`.
`worlds.versions.list(world_id)`	`GET .../versions`	List a world’s versions, newest first.
`worlds.materialize(world_id)`	`POST .../materialize`	Retry task setup.
`worlds.activity.list(world_id)`	`GET .../activity`	Requests across the world’s twins.
`worlds.lifecycle.list(world_id)`	`GET .../lifecycle`	Start, stop, and reset events.

Full request and response schemas are under Worldsmith endpoints in the sidebar.

Launch a world

Get a blueprint

Export one from the dashboard, write one in the blueprint format, or load the built-in example identified by the triage-duplicate-invoice task key:

Python

example = next((e for e in client.worlds.examples.list().items
                if any(t.key == "triage-duplicate-invoice"
                       for t in e.blueprint.scenario.tasks)), None)
if example is None:
    raise RuntimeError("The duplicate-invoice example is not available")
blueprint = example.blueprint

const example = (await client.worlds.examples.list()).items.find((e) =>
  (e.blueprint.scenario.tasks ?? []).some((t) => t.key === "triage-duplicate-invoice"));
if (!example) throw new Error("The duplicate-invoice example is not available");
const blueprint = example.blueprint;

const example = (await client.worlds.examples.list()).items.find((e) =>
  (e.blueprint.scenario.tasks ?? []).some((t) => t.key === "triage-duplicate-invoice"));
if (!example) throw new Error("The duplicate-invoice example is not available");
const blueprint = example.blueprint;

examples, err := client.Worlds.Examples.List(ctx)
if err != nil { return err }
var blueprint chronicle.WorldBlueprint
found := false
for _, example := range examples.Items {
    for _, task := range example.Blueprint.Scenario.Tasks {
        if task.Key == "triage-duplicate-invoice" {
            blueprint, found = example.Blueprint, true
            break
        }
    }
    if found { break }
}
if !found { return fmt.Errorf("the duplicate-invoice example is not available") }

let example = client.worlds().examples().list().await?.items.into_iter()
    .find(|e| e.blueprint.scenario.tasks.iter().any(|t| t.key == "triage-duplicate-invoice"))
    .ok_or("The duplicate-invoice example is not available")?;
let blueprint = example.blueprint;

Compile it

Compiling is fast and creates nothing. It returns problems (must be empty to launch), warnings, and a preview of each twin’s seed and each task.

Python

preview = client.worlds.compile(blueprint=blueprint)
if preview.problems:
    raise SystemExit(preview.problems)
print(preview.warnings)

preview, err := client.Worlds.Compile(ctx, chronicle.WorldCompileParams{Blueprint: blueprint})
if err != nil {
    return err
}
if len(preview.Problems) > 0 {
    return fmt.Errorf("blueprint problems: %v", preview.Problems)
}
fmt.Println(preview.Warnings)

let preview = client.worlds().compile(WorldCompileParams { blueprint: blueprint.clone() }).await?;
if !preview.problems.is_empty() {
    return Err(format!("blueprint problems: {:?}", preview.problems).into());
}
println!("{:?}", preview.warnings);

An invalid blueprint is not an error; the problems come back in the result.

Launch it

Pass an idempotency key so a retry returns the same world instead of launching a second one. ttl_hours is how long the twins live (default 72, max 720).

Python

world = client.worlds.create(
    blueprint=blueprint,
    idempotency_key="launch-1",
    ttl_hours=24,
)
world_id = world.world.id

world, err := client.Worlds.Create(ctx, chronicle.WorldCreateParams{
    Blueprint:      blueprint,
    IdempotencyKey: "launch-1",
    TTLHours:       24,
})
if err != nil {
    return err
}
worldID := world.World.ID

let world = client.worlds().create(WorldCreateParams {
    blueprint: blueprint.clone(),
    idempotency_key: "launch-1".into(),
    ttl_hours: Some(24),
    ..Default::default()
}).await?;
let world_id = world.world.id.clone();

A retry with the same key returns the existing world. The same key with a different blueprint is a 409.

Wait for it to be ready

Launching takes a minute or two. wait polls until the world is ready or failed.

Python

world = client.worlds.wait(world_id, timeout=180)
if world.status != "ready":
    raise RuntimeError(f"World {world_id}: {world.status}; {world.launch_error}")
for twin in world.twins:
    print(twin.id, twin.service, twin.status)  # keep tokens in memory
if world.evaluation is not None:
    print(world.evaluation.status, world.evaluation.task_suite_id)

world = await client.worlds.wait(worldId, { timeout: 180_000 });
if (world.status !== "ready") throw new Error(`World ${worldId}: ${world.status}; ${world.launchError}`);
for (const twin of world.twins) console.log(twin.id, twin.service, twin.status);
if (world.evaluation) console.log(world.evaluation.status, world.evaluation.taskSuiteId);

world = await client.worlds.wait(worldId, { timeout: 180_000 });
if (world.status !== "ready") throw new Error(`World ${worldId}: ${world.status}; ${world.launchError}`);
for (const twin of world.twins) console.log(twin.id, twin.service, twin.status);
if (world.evaluation) console.log(world.evaluation.status, world.evaluation.taskSuiteId);

waitCtx, cancel := context.WithTimeout(ctx, 3*time.Minute)
defer cancel()
world, err = client.Worlds.Wait(waitCtx, worldID)
if err != nil { return err }
if world.Status != "ready" {
    return fmt.Errorf("world %s: %s; %v", worldID, world.Status, world.LaunchError)
}
for _, twin := range world.Twins { fmt.Println(twin.ID, twin.Service, twin.Status) }
if world.Evaluation != nil { fmt.Println(world.Evaluation.Status, world.Evaluation.TaskSuiteID) }

let world = client.worlds().wait(&world_id, Duration::from_secs(180)).await?;
if world.status != "ready" {
    return Err(format!("world {}: {:?}; {:?}", world_id, world.status, world.launch_error).into());
}
for twin in &world.twins { println!("{} {} {}", twin.id, twin.service, twin.status); }
if let Some(evaluation) = &world.evaluation {
    println!("{} {}", evaluation.status, evaluation.task_suite_id);
}

When status is ready, each twin’s base_url and token are live. Point your agent at them (see Twins), or run the world’s task suite with an evaluation once evaluation.status is also ready. Explore the example company and its connected records to see how the blueprint appears in the product.If status is failed, read launch_error and each twin’s error. The response contains live tokens, so keep it out of logs and source control.

Worldsmith task for ENG-2 and the finance handoff, with the Linear-state and Slack-message scorers — The built-in duplicate-invoice task shows the instruction, expected outcome, and two generated scorers in Worldsmith.

Open the task image. Explore the task and its connected records.

The world object

Field	What it is
`world.id`	The ID of this version. Use it in every world method.
`version.number`, `version.root_world_id`	Which launch this is, and the ID shared by all versions of the same world.
`status`	`forging`, `ready`, `degraded`, `failed`, or `retired`.
`launch_error`	Why the launch failed, when it did.
`twins[]`	Each service: `id`, `service`, `status`, `base_url`, `token`, `error`.
`evaluation`	Task setup: `status`, `task_suite_id`, `environment_id`, `environment_version_id`, and `tasks[]` with each task’s `task_id` and `title`.
`blueprint`	The blueprint as launched.

evaluation.status is materializing, ready, or failed, separate from the world’s status. If it’s failed, worlds.materialize(world_id) retries the setup and returns the updated world. A world with no tasks has no evaluation.

SDK and HTTP fields

The endpoint reference shows the HTTP JSON schema. SDKs expose the same data with a consistent page type and the naming convention of your language:

HTTP JSON	SDK view
`examples`, `worlds`, `activities`, or `events` on list responses	`page.items` (Go: `page.Items`).
`hasMore`, `nextCursor`	`has_next_page()` / `get_next_page()` and language equivalents. The SDK carries the cursor; see Pagination.
`world.blueprint`	`result.blueprint`, the blueprint used for this launch.
`launchError`, `version.rootWorldId`, `twins[].baseUrl`	Python/Rust: `launch_error`, `root_world_id`, `base_url`; TS/JS retain camelCase; Go uses `LaunchError`, `RootWorldID`, `BaseURL`.
`evaluation.taskSuiteId`, `evaluation.tasks[].taskId`	`task_suite_id`, `tasks[].task_id` in Python/Rust; camelCase in TS/JS; `TaskSuiteID`, `TaskID` in Go.
`activities[].activity.requestId`, `.method`, `.path`, `.status`	Each SDK item has `request_id`, `request.method`, `request.path`, and `response.status`, with the same language naming rules.
`activities[].twinInstanceId`, `.service`, `.mutations`	The SDK activity item keeps its twin ID, service, and mutation summary together. Twin activity detail adds before/after records.

The blueprint export below writes only the blueprint, suitable for the blueprint.json input used by the compile and launch endpoint examples. WORLD_ID in those examples is world.id; WORLD_LAUNCH_KEY is your stable idempotency key for one launch. Configure them in your process environment, alongside CHRONICLE_API_URL and CHRONICLE_API_KEY.

Retry task setup

Twin readiness and task setup are separate. After the world is ready, read evaluation.status before starting an evaluation. While it is materializing, retrieve the same world again later. If it is failed, retry setup with the same world ID:

Python

world = client.worlds.materialize(world_id)
if world.evaluation is None or world.evaluation.status != "ready":
    raise RuntimeError(f"Task setup is not ready for world {world_id}; inspect its evaluation details")
suite_id = world.evaluation.task_suite_id

world = await client.worlds.materialize(worldId);
if (world.evaluation?.status !== "ready") throw new Error(`Task setup is not ready for world ${worldId}`);
const suiteId = world.evaluation.taskSuiteId;

world = await client.worlds.materialize(worldId);
if (world.evaluation?.status !== "ready") throw new Error(`Task setup is not ready for world ${worldId}`);
const suiteId = world.evaluation.taskSuiteId;

world, err = client.Worlds.Materialize(ctx, worldID)
if err != nil { return err }
if world.Evaluation == nil || world.Evaluation.Status != "ready" {
    return fmt.Errorf("task setup is not ready for world %s", worldID)
}
suiteID := world.Evaluation.TaskSuiteID
fmt.Println(suiteID)

let world = client.worlds().materialize(&world_id).await?;
let evaluation = world.evaluation.as_ref().filter(|e| e.status == "ready")
    .ok_or("Task setup is not ready; inspect the world's evaluation details")?;
let suite_id = evaluation.task_suite_id.clone();

A world without tasks has no evaluation setup to retry. Once setup is ready, inspect the generated task and scorers or use Evaluations with the returned suite ID.

Blueprint

A blueprint is an object with these top-level fields:

Field	Contents
`name`, `summary`	Display name and the situation in a sentence.
`clock`	The story’s “now”, as UTC, e.g. `2026-09-03T17:00:00Z`.
`organization`	Name, workspace slug, email domain, industry, description.
`identities`	People shared across services: handle, name, role, department, time zone.
`twins`	One section per service you want: `slack`, `linear`, `salesforce`, `sapS4hana`. Each holds that service’s seed records. A present section creates a twin.
`scenario`	Background story, cross-service threads, and `tasks[]`, each with an instruction, steps, expected outcome, and `scorers[]`.

Use readable keys for records and reference them by key; the compiler assigns vendor-style IDs and resolves the links. The complete schema is on the POST /v1/worldsmith/compile page under Worldsmith endpoints. The SDKs type it as WorldBlueprint. Export the selected blueprint for the endpoint examples:

Python

import json
from pathlib import Path

Path("blueprint.json").write_text(json.dumps(blueprint.model_dump(mode="json"), indent=2))

The file contains only the blueprint, without a surrounding blueprint key. Keep live twin tokens out of exported configuration.

Launch a new version

Send the updated blueprint with source_world_id set to the current version’s world.id and a new idempotency key. The old version keeps its twins and history.

Python

v2 = client.worlds.create(
    blueprint=blueprint,
    source_world_id=world_id,
    idempotency_key="launch-2",
)
print(v2.world.id, v2.status)

v2, err := client.Worlds.Create(ctx, chronicle.WorldCreateParams{
    Blueprint:      blueprint,
    SourceWorldID:  worldID,
    IdempotencyKey: "launch-2",
})
if err != nil {
    return err
}
fmt.Println(v2.World.ID, v2.Status)

let v2 = client.worlds().create(WorldCreateParams {
    blueprint: blueprint.clone(),
    source_world_id: Some(world_id.clone()),
    idempotency_key: "launch-2".into(),
    ..Default::default()
}).await?;
println!("{} {}", v2.world.id, v2.status);

worlds.versions.list(world_id) returns every version in the same lineage. Without source_world_id, you get a separate new world.

Activity and lifecycle

worlds.activity.list returns every request made to any of the world’s twins, newest first. worlds.lifecycle.list returns start, stop, and reset events. Both are pages: items, has_next_page(), get_next_page().

Python

page = client.worlds.activity.list(world_id, limit=50)
for activity in page.auto_paging_iter():
    print(activity.service, activity.request.method, activity.request.path, activity.mutations)

page, err := client.Worlds.Activity.List(ctx, worldID, chronicle.PageParams{Limit: 50})
if err != nil {
    return err
}
for {
    for _, a := range page.Items {
        fmt.Println(a.Service, a.Request.Method, a.Request.Path, a.Mutations)
    }
    if !page.HasNextPage() { break }
    page, err = page.GetNextPage(ctx)
    if err != nil { return err }
}

let mut page = client.worlds().activity().list(&world_id, PageParams { limit: Some(50), ..Default::default() }).await?;
loop {
    for a in &page.items {
        println!("{:?} {} {} {:?}", a.service, a.request.method, a.request.path, a.mutations);
    }
    if !page.has_next_page() { break; }
    page = page.get_next_page().await?;
}

Each activity names the twin, summarizes the request, and lists the records it changed. For the full request, response, and before/after values, use twin activity detail.

Errors

Result	Meaning
Compile returns `problems`	Fix the blueprint and compile again.
World `status` is `failed`	Read `launch_error` and twin errors, then launch again with a new key.
`400`	Bad blueprint or key format.
`403`	Not enough twin capacity in your organization.
`404`	Unknown `world_id` or `source_world_id`.
`409`	Idempotency key reused with different inputs.
`503` while retrying task setup	Evaluation services aren’t enabled on this deployment.

Get started

Guides

SDKs

Worldsmith endpoints

Methods

Launch a world

The world object

SDK and HTTP fields

Retry task setup

Blueprint

Launch a new version

Activity and lifecycle

Errors

​Methods

​Launch a world

​The world object

​SDK and HTTP fields

​Retry task setup

​Blueprint

​Launch a new version

​Activity and lifecycle

​Errors

Methods

Launch a world

The world object

SDK and HTTP fields

Retry task setup

Blueprint

Launch a new version

Activity and lifecycle

Errors