Actors
An actor is an object identified by a type name and a key (ShoppingCart / user-123) with its own durable key-value state. Operations on one actor key that change state run one at a time, so an operation can read, change and write its state without another operation interleaving.
Defining an actor
Decorate the class with @actor and each operation with @operation. An operation's name is its method name, and its first parameter after self is the context:
1@actor(name="ShoppingCart", description="One cart per customer")2class ShoppingCart:3 @operation(mode=OperationMode.EXCLUSIVE) # the default mode4 async def add_item(self, ctx: ActorContext, sku: str, price: float) -> int:5 items: list[dict[str, Any]] = await ctx.state.get("items") or []6 items.append({"sku": sku, "price": price})7 await ctx.state.set("items", items)8 return len(items)910 @operation(mode=OperationMode.SHARED, timeout=5.0)11 async def total(self, ctx: SharedActorContext) -> float:12 items: list[dict[str, Any]] = await ctx.state.get("items") or []13 return sum(float(item["price"]) for item in items)1415 @operation()16 async def clear(self, ctx: ActorContext) -> None:17 await ctx.state.clear_all()@operation() takes a mode and an optional timeout in seconds. Like workflows and tasks, an actor registers when its module is imported, and a worker that has actors registered also polls for actor operations.
An operation's input arrives the way a workflow's does: a dict is spread into keyword arguments, and any other value is passed as one positional argument.
Operation modes
| Mode | Context | Use for |
|---|---|---|
OperationMode.EXCLUSIVE (default) | ActorContext | Operations that change state. They run one at a time per actor key. |
OperationMode.SHARED | SharedActorContext | Operations that only read state. The worker registers the mode with the engine, which may run shared operations alongside each other. |
A shared operation can still call the state's write methods; the mode is a declaration, so keep shared operations read-only yourself.
State and context
ctx.state reads and writes the actor's state; every method is async:
| Method | Description |
|---|---|
get(key) | The value, or None |
set(key, value) | Store a JSON-serializable value |
update(key, fn) | Read, apply fn to the current value (or None), write back and return the new value |
delete(key) | Remove a key; returns whether it existed |
exists(key) | Whether a key is set |
list(prefix=None) | The state's keys |
clear_all() | Remove every key |
update is a read followed by a write, which is safe inside an exclusive operation because nothing else runs on that key in between. The context also identifies the actor and the operation:
1@actor(name="Counter")2class Counter:3 @operation()4 async def increment(self, ctx: ActorContext, by: int = 1) -> dict:5 count = await ctx.state.update("count", lambda current: (current or 0) + by)6 return {7 "actor": ctx.actor_name, # "Counter"8 "key": ctx.key, # which counter, e.g. "user-123"9 "execution_id": ctx.execution_id,10 "count": count,11 }ctx.deterministic_uuid(seed) returns a UUID derived from the actor's name and key and the seed, so the same seed gives the same UUID on every call for that actor.
Invoking operations
Call an actor's operations from outside it with ActorInvocationClient, given a connected Client, the actor's name and the key of the instance. invoke sends the operation's input as JSON and returns its result decoded, and waits 30 seconds unless given timeout_ms:
1async def cart_total(customer_id: str) -> float:2 async with Client(ClientConfig(server_url="http://localhost:50051")) as orcher:3 cart = ActorInvocationClient(orcher, "ShoppingCart", customer_id)4 total = await cart.invoke("total", timeout_ms=5_000)5 return float(total)Use the client while it is open: invoke goes through it. A workflow has no API for invoking an actor operation; call one from a task, which can open a client.