Skip to main content
env.<BINDING> is your handle to an actor class. You name an instance, get a stub, and call methods on it.

​
Two Ways to Name an Instance

  • idFromName(name) is deterministic: the same name always lands on the same instance, from anywhere. This is the common case — pick a stable identity for the entity and let the platform route to its state.
  • newUniqueId() mints a fresh, unguessable instance; you store the id (stub.id) yourself. It currently fails at call time on the platform (a known runtime issue — see Actor Namespace); until it’s fixed, mint an identity yourself and pass it to idFromName.

​
Choosing a Name

The name is your shard key — choose the entity’s natural identity: a user or account id, a room id, or a composite key (tenant:room). Same name → same single-threaded instance → coherent state for that entity. Names may contain ASCII letters (A–Z, a–z), digits, -, _, ., :, and spaces. Ids addressable by the platform are [A-Za-z0-9._-] spans plus optional :hex: escape brackets (the : renders as %3A on the wire). The Agent SDK’s mountAgents/encodeAgentName escapes out-of-alphabet characters (including : and spaces) into that :hex: form for you; calling idFromName directly, pass a name whose characters are already within [A-Za-z0-9._-] — and avoid exactly . or .. as the whole id (URL path resolution collapses those segments, so they are unaddressable). The 225-character cap is not enforced on direct idFromName calls either — an over-limit id activates and accepts writes and the instance only becomes unreachable after its first eviction, so validate long names yourself (encodeAgentName refuses them up front) before persisting state. For phone numbers, strip the leading + before passing to idFromName. Spreading load means choosing names that spread across entities; a single hot name is one single-threaded bottleneck (see When to use).

​
Calling the Stub

Both calls return a stub. Calling a method on the stub is an RPC to that one instance: the call is queued there, your method runs, the value comes back.

​
Next Steps