Reference

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")
2
class ShoppingCart:
3
@operation(mode=OperationMode.EXCLUSIVE) # the default mode
4
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)
9
10
@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)
14
15
@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

ModeContextUse for
OperationMode.EXCLUSIVE (default)ActorContextOperations that change state. They run one at a time per actor key.
OperationMode.SHAREDSharedActorContextOperations 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:

MethodDescription
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")
2
class 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:

1
async 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.


Next steps