From 1a9d767315f366e111c354fd179659293f5e3e76 Mon Sep 17 00:00:00 2001 From: Giselle van Dongen Date: Thu, 19 Nov 2026 19:06:14 +0200 Subject: [PATCH 1/3] Document enabling lazy state --- .../skills/restate-agents/SKILL.md | 4 +++ .../references/conversations-and-controls.md | 30 +++++++++++++++++++ .../references/handlers-and-state.md | 3 ++ 3 files changed, 37 insertions(+) diff --git a/plugins/restate-agents/skills/restate-agents/SKILL.md b/plugins/restate-agents/skills/restate-agents/SKILL.md index a3d5902..ae77adf 100644 --- a/plugins/restate-agents/skills/restate-agents/SKILL.md +++ b/plugins/restate-agents/skills/restate-agents/SKILL.md @@ -139,5 +139,9 @@ Restate journals. Move on only when the learner is ready. never from model-supplied tool arguments. - [ ] Approval requests and active-turn IDs stored in state are cleared in a `finally`. +- [ ] An object that stores a `LazyStateConversation` sets + `options.state: {preload: false}`. Otherwise Restate sends the full + history with every invocation of the object. See + `references/conversations-and-controls.md`. - [ ] Tests use a fixture model (`journaledModel`) against `RestateContainer().alwaysReplay().disableRetries()`. No paid model calls. diff --git a/plugins/restate-agents/skills/restate-agents/references/conversations-and-controls.md b/plugins/restate-agents/skills/restate-agents/references/conversations-and-controls.md index 4172fe3..f509ae9 100644 --- a/plugins/restate-agents/skills/restate-agents/references/conversations-and-controls.md +++ b/plugins/restate-agents/skills/restate-agents/references/conversations-and-controls.md @@ -45,6 +45,36 @@ const result = yield* support.run(message, {conversation}); Read it from a shared handler with `yield* new LazyStateConversation().page()`. +**Turn off state preloading on the object.** `LazyStateConversation` reads +one state key per chunk, but by default Restate sends a snapshot of all of +the object's state when each invocation starts, including invocations of +shared handlers such as `steer` and `status`. Compaction changes what the +model reads, not what is stored: every chunk stays in state so `page()` can +return the full history. With the default, every invocation of the object +receives the entire history, although a run loads only the chunks after the +last summary. Set `state: {preload: false}` on the object so each chunk is +fetched when it is read: + +```ts +export const aiSession = restate.object({ + name: "AiSession", + handlers: {doTurn, history, steer, interrupt}, + options: { + state: {preload: false}, // fetch conversation chunks when they are read + handlers: {history: {shared: true}, steer: {shared: true}, interrupt: {shared: true}}, + }, +}); +``` + +- Each state read is then a round trip to Restate. Loading the conversation + reads its metadata key and one key per 32 messages since the last summary. + On AWS Lambda and other platforms without bidirectional streaming, each + read suspends and replays the invocation. +- To keep small keys such as `active` preloaded, list them instead: + `state: {preload: ["active"]}` (Restate 1.8 or later). +- To set it for one handler only, put `state` in `options.handlers`. The + deprecated `enableLazyState: true` equals `state: {preload: false}`. + When a run starts and the conversation compaction fails, the run logs a warning and continues with the history it loaded; the next run tries again. An `AgentTerminalError` from the compaction model fails the run instead. diff --git a/plugins/restate-agents/skills/restate-gen-sdk/references/handlers-and-state.md b/plugins/restate-agents/skills/restate-gen-sdk/references/handlers-and-state.md index b32f88e..7995f1a 100644 --- a/plugins/restate-agents/skills/restate-gen-sdk/references/handlers-and-state.md +++ b/plugins/restate-agents/skills/restate-gen-sdk/references/handlers-and-state.md @@ -120,6 +120,9 @@ export const onboarding = restate.workflow({ `state: {preload}` chooses which state keys are loaded eagerly when the handler starts: `true` for all, `false` for none, or a list of key names. `enableLazyState: true` is deprecated and equals `state: {preload: false}`. +Set `state` at the object level in `options` to apply it to every handler. +Use `preload: false` when an object stores more state than one invocation +reads, such as an agent conversation kept in chunks. Use `retryPolicy` with `onMaxAttempts: "kill"` or `"pause"` to decide what happens to an invocation after its retries are exhausted. From a641f093571c023f281ed92734411c286bae4ca2 Mon Sep 17 00:00:00 2001 From: Giselle van Dongen Date: Thu, 19 Nov 2026 19:10:00 +0200 Subject: [PATCH 2/3] Document enabling lazy state --- .../skills/restate-agents/SKILL.md | 8 ++++--- .../references/conversations-and-controls.md | 23 +++++++++++-------- .../references/handlers-and-state.md | 6 +++-- 3 files changed, 22 insertions(+), 15 deletions(-) diff --git a/plugins/restate-agents/skills/restate-agents/SKILL.md b/plugins/restate-agents/skills/restate-agents/SKILL.md index ae77adf..b1199fc 100644 --- a/plugins/restate-agents/skills/restate-agents/SKILL.md +++ b/plugins/restate-agents/skills/restate-agents/SKILL.md @@ -139,9 +139,11 @@ Restate journals. Move on only when the learner is ready. never from model-supplied tool arguments. - [ ] Approval requests and active-turn IDs stored in state are cleared in a `finally`. -- [ ] An object that stores a `LazyStateConversation` sets - `options.state: {preload: false}`. Otherwise Restate sends the full - history with every invocation of the object. See +- [ ] An agent with long or large conversations in a `LazyStateConversation` + sets `options.state: {preload: false}` on its object. Otherwise + Restate sends the full history with every invocation of the object. + On serverless platforms, each lazy read adds a suspension, so keep the + default for short conversations. See `references/conversations-and-controls.md`. - [ ] Tests use a fixture model (`journaledModel`) against `RestateContainer().alwaysReplay().disableRetries()`. No paid model calls. diff --git a/plugins/restate-agents/skills/restate-agents/references/conversations-and-controls.md b/plugins/restate-agents/skills/restate-agents/references/conversations-and-controls.md index f509ae9..85ffcaa 100644 --- a/plugins/restate-agents/skills/restate-agents/references/conversations-and-controls.md +++ b/plugins/restate-agents/skills/restate-agents/references/conversations-and-controls.md @@ -45,14 +45,16 @@ const result = yield* support.run(message, {conversation}); Read it from a shared handler with `yield* new LazyStateConversation().page()`. -**Turn off state preloading on the object.** `LazyStateConversation` reads -one state key per chunk, but by default Restate sends a snapshot of all of -the object's state when each invocation starts, including invocations of -shared handlers such as `steer` and `status`. Compaction changes what the -model reads, not what is stored: every chunk stays in state so `page()` can -return the full history. With the default, every invocation of the object -receives the entire history, although a run loads only the chunks after the -last summary. Set `state: {preload: false}` on the object so each chunk is +**Turn off state preloading for long or large conversations.** By default, +Restate sends a snapshot of all of the object's state when each invocation +starts, including invocations of shared handlers such as `steer` and +`status`. Compaction changes what the model reads, not what is stored: every +chunk stays in state so `page()` can return the full history. Once a +conversation has many turns or large messages, such as long tool results, +every invocation of the object receives the entire history, although a run +loads only the chunks after the last summary. Short conversations do not +need this; keep the default for them. For agents with long or large +conversations, set `state: {preload: false}` on the object so each chunk is fetched when it is read: ```ts @@ -68,8 +70,9 @@ export const aiSession = restate.object({ - Each state read is then a round trip to Restate. Loading the conversation reads its metadata key and one key per 32 messages since the last summary. - On AWS Lambda and other platforms without bidirectional streaming, each - read suspends and replays the invocation. +- On AWS Lambda and other serverless platforms without bidirectional + streaming, each lazy read adds a suspension: the invocation suspends and + replays once Restate sends the requested state. - To keep small keys such as `active` preloaded, list them instead: `state: {preload: ["active"]}` (Restate 1.8 or later). - To set it for one handler only, put `state` in `options.handlers`. The diff --git a/plugins/restate-agents/skills/restate-gen-sdk/references/handlers-and-state.md b/plugins/restate-agents/skills/restate-gen-sdk/references/handlers-and-state.md index 7995f1a..a052b35 100644 --- a/plugins/restate-agents/skills/restate-gen-sdk/references/handlers-and-state.md +++ b/plugins/restate-agents/skills/restate-gen-sdk/references/handlers-and-state.md @@ -121,8 +121,10 @@ export const onboarding = restate.workflow({ handler starts: `true` for all, `false` for none, or a list of key names. `enableLazyState: true` is deprecated and equals `state: {preload: false}`. Set `state` at the object level in `options` to apply it to every handler. -Use `preload: false` when an object stores more state than one invocation -reads, such as an agent conversation kept in chunks. +Use `preload: false` when an object stores much more state than one +invocation reads, such as a long agent conversation kept in chunks. On +serverless platforms without bidirectional streaming, each lazy read adds a +suspension, so keep the default for small state. Use `retryPolicy` with `onMaxAttempts: "kill"` or `"pause"` to decide what happens to an invocation after its retries are exhausted. From c2e3e99e7dc3c676a9a246c3c94f1a55f94a3dae Mon Sep 17 00:00:00 2001 From: Giselle van Dongen Date: Thu, 19 Nov 2026 19:27:56 +0200 Subject: [PATCH 3/3] use lazy state in the example --- .../src/lessons/09_support_session.ts | 3 +++ .../skills/restate-agents/SKILL.md | 3 ++- .../references/conversations-and-controls.md | 25 +++++++++++++------ .../references/handlers-and-state.md | 5 ++-- 4 files changed, 25 insertions(+), 11 deletions(-) diff --git a/packages/examples/src/lessons/09_support_session.ts b/packages/examples/src/lessons/09_support_session.ts index 9f3efc1..6661a3d 100644 --- a/packages/examples/src/lessons/09_support_session.ts +++ b/packages/examples/src/lessons/09_support_session.ts @@ -125,6 +125,9 @@ export const aiSession = restate.object({ ), }, options: { + // Preload only the small keys that handlers read on every call. Conversation + // chunks are read when needed instead of sent with every invocation. + state: {preload: ["conversation/meta", "active", "approval"]}, // Shared handlers run while doTurn holds the object's lock. handlers: { status: {shared: true}, diff --git a/plugins/restate-agents/skills/restate-agents/SKILL.md b/plugins/restate-agents/skills/restate-agents/SKILL.md index b1199fc..d7b79c5 100644 --- a/plugins/restate-agents/skills/restate-agents/SKILL.md +++ b/plugins/restate-agents/skills/restate-agents/SKILL.md @@ -140,7 +140,8 @@ Restate journals. Move on only when the learner is ready. - [ ] Approval requests and active-turn IDs stored in state are cleared in a `finally`. - [ ] An agent with long or large conversations in a `LazyStateConversation` - sets `options.state: {preload: false}` on its object. Otherwise + preloads only small keys on its object, such as + `options.state: {preload: ["conversation/meta", "active"]}`. Otherwise Restate sends the full history with every invocation of the object. On serverless platforms, each lazy read adds a suspension, so keep the default for short conversations. See diff --git a/plugins/restate-agents/skills/restate-agents/references/conversations-and-controls.md b/plugins/restate-agents/skills/restate-agents/references/conversations-and-controls.md index 85ffcaa..de02990 100644 --- a/plugins/restate-agents/skills/restate-agents/references/conversations-and-controls.md +++ b/plugins/restate-agents/skills/restate-agents/references/conversations-and-controls.md @@ -45,7 +45,7 @@ const result = yield* support.run(message, {conversation}); Read it from a shared handler with `yield* new LazyStateConversation().page()`. -**Turn off state preloading for long or large conversations.** By default, +**Preload only small keys for long or large conversations.** By default, Restate sends a snapshot of all of the object's state when each invocation starts, including invocations of shared handlers such as `steer` and `status`. Compaction changes what the model reads, not what is stored: every @@ -54,27 +54,36 @@ conversation has many turns or large messages, such as long tool results, every invocation of the object receives the entire history, although a run loads only the chunks after the last summary. Short conversations do not need this; keep the default for them. For agents with long or large -conversations, set `state: {preload: false}` on the object so each chunk is -fetched when it is read: +conversations, list the keys to preload: the conversation's metadata key and +your own small keys. Restate fetches every other key, including each chunk, +when it is read: ```ts export const aiSession = restate.object({ name: "AiSession", handlers: {doTurn, history, steer, interrupt}, options: { - state: {preload: false}, // fetch conversation chunks when they are read + state: {preload: ["conversation/meta", "active"]}, // chunks are read on demand handlers: {history: {shared: true}, steer: {shared: true}, interrupt: {shared: true}}, }, }); ``` -- Each state read is then a round trip to Restate. Loading the conversation - reads its metadata key and one key per 32 messages since the last summary. +- `conversation/meta` holds the message count and the latest summary. The + chunk keys (`conversation/0`, `conversation/1`, ...) follow from the + count, and every load, append and `page()` reads the metadata key first, + so always preload it. With a custom `stateKey`, the key is + `/meta`; with a custom `metaKey`, list that key. +- Each key that is not preloaded costs a round trip to Restate when it is + read. Loading the conversation reads one chunk key per 32 messages since + the last summary. - On AWS Lambda and other serverless platforms without bidirectional streaming, each lazy read adds a suspension: the invocation suspends and replays once Restate sends the requested state. -- To keep small keys such as `active` preloaded, list them instead: - `state: {preload: ["active"]}` (Restate 1.8 or later). +- A list of keys requires Restate 1.8 or later: an older server rejects the + deployment at registration because it does not support + `eagerStateKeysWhitelist`. On older servers, use + `state: {preload: false}`; the metadata key is then read lazily as well. - To set it for one handler only, put `state` in `options.handlers`. The deprecated `enableLazyState: true` equals `state: {preload: false}`. diff --git a/plugins/restate-agents/skills/restate-gen-sdk/references/handlers-and-state.md b/plugins/restate-agents/skills/restate-gen-sdk/references/handlers-and-state.md index a052b35..b3d105c 100644 --- a/plugins/restate-agents/skills/restate-gen-sdk/references/handlers-and-state.md +++ b/plugins/restate-agents/skills/restate-gen-sdk/references/handlers-and-state.md @@ -121,8 +121,9 @@ export const onboarding = restate.workflow({ handler starts: `true` for all, `false` for none, or a list of key names. `enableLazyState: true` is deprecated and equals `state: {preload: false}`. Set `state` at the object level in `options` to apply it to every handler. -Use `preload: false` when an object stores much more state than one -invocation reads, such as a long agent conversation kept in chunks. On +Use `preload: false`, or a list of the small keys every invocation reads, +when an object stores much more state than one invocation reads, such as a +long agent conversation kept in chunks. On serverless platforms without bidirectional streaming, each lazy read adds a suspension, so keep the default for small state.