Durable operations and errors

Capture, generation, training, evaluation, deployment, rollback, research, and improvement can outlive a Python process. The SDK represents each as Operation[Result, Progress].

Submit once

operation = await client.worlds.evaluate(application, for_task=task, seed=7)

# Persist this before waiting.
print(operation.ref)  # worlds/evaluation/01J...

Admission means the owner accepted the work. It does not mean the work succeeded.

Choose how to observe

evaluation = await operation

async for receipt in operation.watch():
    print(receipt.cursor, receipt.state)

status = await operation.status()

watch() follows the owner's ordered ledger until a terminal receipt. status() makes one read. result() reads once and raises if the work is still running.

Reattach later

async with sx.connect(project_id) as client:
    operation = client.operation("worlds/evaluation/01J...")
    status = await operation.status()
    evaluation = await operation

Reattachment performs no I/O until you request status, updates, or a result. Disconnecting a client does not cancel server work.

Handle terminal outcomes explicitly

from sx import OperationCancelledError, OperationFailedError

try:
    evaluation = await operation
except OperationFailedError as error:
    print(error.status.failure.code)
    print(error.status.failure.message)
except OperationCancelledError as error:
    print(error.status.reason)

Error	Meaning	Correct response
`OperationNotCompleteError`	`result()` was called before terminal state	watch, await, or inspect later
`OperationFailedError`	the owner reached a failed terminal state	use the typed failure and recovery detail
`OperationCancelledError`	an authorized caller cancelled the operation	retain the reason and terminal receipt
`OperationHistoryGapError`	the requested cursor is older than retained updates	use `error.latest` as the authoritative snapshot
`OperationProtocolError`	the owner returned malformed or contradictory identity	stop; do not reinterpret the response

Cancel deliberately

receipt = await operation.cancel(reason="operator ended the experiment")

Local task cancellation, process exit, or closing the client does not cancel platform work. Server cancellation happens only through operation.cancel(...) and requires a non-empty reason.

The SDK derives an idempotency key from the operation name and canonical request body unless you provide one at the lower admission boundary. Retrying the same intent does not create a second operation accidentally.

Persist at least:

project id
operation reference
idempotency key from the admission receipt
resource reference
last observed cursor
terminal result or typed failure

The same controls on every surface

Python SDK	MCP tool	CLI
`operation.status()`	`operation.status`	`sx status REF`
`operation.watch()` / `updates_page()`	`operation.updates`	`sx watch REF`
`operation.result()`	`operation.result`	`sx result REF`
`operation.cancel(reason=...)`	`operation.cancel`	`sx cancel REF --reason ...`

Reliable automation rule

Persist the operation reference before monitoring. Report success only from the terminal result. Treat a typed refusal as a real outcome with a recovery action—not as a reason to substitute a different project, task, controller, or dataset.

sx docs