Skip to main content

​
Execution budgets

Do LLM and outbound API work in tasks, not inbound methods — see How Agents Run. Full platform numbers live in the StatefulActor API reference.

​
Task retries

A task that throws retries up to its maxRetries (default 5) with exponential backoff, then is parked — it stops retrying and no longer fires. every() tasks reset their attempt count after each successful run.

​
Storage

Message history and state live in the actor’s persistent storage and are subject to its size caps — see the storage reference and where this is stored. Message history is append-only — there is no delete or trim API. last(n) reads a bounded window, but writes accumulate forever. For relational or queryable data, use the actor’s embedded SQL database instead — up to 1 GB per agent.

​
Actor id length

An agent’s name becomes an actor id, and that id is carried into names the platform builds for the instance behind it — including the file its persistent state is kept in, which is capped at 255 bytes. The budget is measured on the id once URL-escaped, so a : costs three characters rather than one, and the ceiling is 225 escaped characters: 225 ASCII characters, 54 two-byte, 36 three-byte, or 27 four-byte (emoji), plus 6 for every escaped run. encodeAgentName() and mountAgents() apply the rule for you — the two exports below are for a front door you wrote yourself. Worth knowing either way: an over-long id is not rejected on first use. The instance activates and accepts writes, and only becomes unreachable once it is evicted and rehydrated, so a name that is too long looks healthy until the first eviction.

​
MAX_ESCAPED_ACTOR_ID_LENGTH

​
escapedActorIdLength()

​
What’s shipped

  • Agent base class with message history, scheduled tasks, and merge-patch state
  • WebSocket termination via webSocket() — see WebSockets
  • The agent socket layer (SDK ≥ 0.10.0) — AgentClient for browser/Node clients (automatic reconnect, state mirroring, typed RPC) and AgentSocketServer on the agent side, with the @rpc() opt-in
  • BlobStore for blob access within actors
  • The mount front door (SDK ≥ 0.12.0) — mountAgents() routes every agent a function serves on one address shape; see Mounting Agents
The Agent API surface is Beta and may change as pieces land.