Propose low-level snapshot api #497

pgrayy · 2026-02-02T18:07:58Z

Do we have a use case for wanting to modify a past message?

cagataycali · 2026-02-02T18:05:10Z

i'd want to see a timestamp of snapshot so we can go back in time.

+1, Probably it can be in the sate / metadata.

I notice that otel trace / span properties are good to have in many cases. I wonder if some of them can be added into state or metadata.

cagataycali · 2026-02-02T18:21:33Z

Adding SHA is also crucial here ^^

mkmeral · 2026-02-02T18:06:44Z

Do we want specific agent methods, or Snapshottable (wip name) interface?

Having an interface like below, would make implementation a lot easier. And it would allow us to extend to other types (multi-agent, etc)

Snapshottable: def save(): def load():

This is similar to @JackYPCOnline 's idea on SessionAwarebut different naming pretty much

afarntrog · 2026-02-02T18:06:55Z

Great idea! I would consider moving these methods to their own class and inject it in the agent class agent.snapshot.load()

I am picky on naming, what it actually does is to_dict() and from_dict(), we are not saving anything

Unshure · 2026-01-29T15:36:03Z

I agree with this, it is not easy to capture and persist code, and I dont think strands should try to do this.

However, we should explore how one would restore an agent from a snapshot, and load lets say tools back into the agent after persisting it. I would like to see an example devex of what this looks like.

I view the tool state as a feature that we'd be adding to the agent to make "enabled" tools into a state on the agent. So, if we had that I imagine it would be something like:

agent = Agent(tools=[tool1, tool2, tool3, tool4], enabled_tools=["tool1"])

Where only tool1 would be enabled/available on the agent. Then to enable other tools something would eventually trigger:

agent.enabled_tools = ["tool1", "tool3"]

and for restoring an agent with specific tools, it would be the same as

agent2 = Agent(tools=[tool3, tool4]) agent2.load_snapshot(snapshot)

and the snapshot would be restoring the enabled_tools state back into the agent.

+1 the term "snapshot" makes me think of a disk snapshot - literally everything. I would like to see this incorporate tools etc in the future.

mkmeral · 2026-01-29T17:44:04Z

Do we allow these components to expose "snapshot-able data"? e.g. I am a conv manager developer, I want my data to be restored with snapshots

What's the recommendation? Keeping that data in agent state?

What's the recommendation? Keeping that data in agent state?

Yeah; the recommendation is agent state

Do we allow these components to expose "snapshot-able data"?

It should be Agent State (AgentState directly; or if we're missing something, an equivalent thereof). The idea that I'm trying to get across in this section is "Snapshots do not represent anything other than what already exists in agent state/session-management, it just provides a more direct api to control it".

dbschmigelski · 2026-02-02T18:11:16Z

Are we saying that we don't believe these things should be part of a snapshot or are we just saying that we are not trying to expand the scoep by limiting to the current capabilities of Session Management.

For example I could see the following being important

models: what happens if I change this as the agent runs

tools: what happens if I add a tool and want to revert back to a time when I did not

pgrayy · 2026-02-02T18:13:38Z

So does that mean a configuration like model_id wouldn't be stored in the snapshot? Is there a specific reason why? May have missed it.

dbschmigelski · 2026-02-02T18:09:39Z

nit: naming is hard but I think describing this as metadata is a stretch. If it is just store checkpoint labels, timestamps I agree but the any application-specific data part seems like this is broader

poshinchen · 2026-02-02T18:26:56Z

Good to have: We can enable a traces for snapshot actions

pgrayy · 2026-02-02T18:19:12Z

Do we want to allow users to snapshot in hooks on life cycle events?

poshinchen · 2026-02-02T18:18:46Z

QQ: what happens if an user calls save_snapshot() twice?

mehtarac · 2026-02-02T18:19:06Z

I'm a little unclear here. agent has tools tool1 and tool2. agent2, is initialized with tool3 and tool4. When agent2 loads the snapshot, does it have all the tools or just the tool1 and tool2

afarntrog · 2026-02-02T18:09:39Z

We should consider allowing for passing in the snapshot in the Agent init (as well)

dbschmigelski · 2026-02-02T18:13:10Z

if this is the intended flow where we are creating a new instance, did you consider pros/cons of acting on the constructor?

Agent(snapshot=...)

pgrayy · 2026-02-02T18:17:01Z

Would we want to give customers the option to override specific data in a snapshot? So keep most things the same but try tweaking one value to see how the agent behaves.

afarntrog · 2026-02-02T18:13:15Z

I think we can have these as methods or as different snapshot implementations such as S3Snapshot etc and then users call snapshot.persist()

mkmeral · 2026-02-02T18:11:06Z

I'd argue system prompt is also evolving state. You can inject context at runtime to update system prompt, same with tools and conversation manager to be honest.

Thinking further, I don't think I like this distinction. Given meta-agents, skills, context maangement, etc. I'd argue this distinction is pretty blurry

I think we should snapshot all the info that we list below.

I'd do something like agent code is the superset, and snapshot is current data.

E.g. You might have tools in python definition of the code

Agent(tools=[a,b,c,d,e])

but your snapshot might include

tools: [d,e,f]

then the loaded agent should be tools=[d,e] (f would load because we dont know the definition)

dbschmigelski · 2026-02-02T18:15:38Z

Mentioned above, but I think this makes the assumption that all of these things are static when we have seen dynamic use cases for each of these (excluding conversation manager)

dbschmigelski · 2026-02-02T18:48:46Z

note for if we do model, we should be persisting model configuration probably be a ModelSnapshot not an str

Unshure · 2026-01-29T20:31:31Z

This might be the right boundary, but I want to understand the devex a bit more for restoring "Agent Definition" after loading a snapshot. I get you can do this:

agent = Agent(tools=[tool1, tool2]) snapshot = agent.save_snapshot() result = agent("What is the weather?") # ... agent = Agent(tools=[tool1, tool2]) agent.load_snapshot(snapshot)

Im thinking about defining custom serializers and deserializers you can pass into save_snapshot and load_snapshot, but I guess that doesnt really make sense since the customer can do that themselves anyway today like this:

snapshot = custom_serializer(agent) agent = custom_deserializer(agent)

Maybe this is where AgentConfig comes in to save the day?

agent = Agent.from_config(config) agent.load_snapshot(snapshot)

cagataycali · 2026-02-02T18:07:00Z

seems like timestamps are missing for rewind ^^

-Original file line number
+Diff line change
@@ -0,0 +1,174 @@
+    # Design Doc: Low-Level Snapshot API
+    **Status**: Proposed
+    **Date**: 2026-01-28
+    **Issue**: https://github.com/strands-agents/sdk-python/issues/1138
+    ## Motivation
+    Today, developers who want to manually snapshot and restore agent state can *almost* do so by saving and loading these properties directly:
+    - `Agent.messages` — the conversation history
+    - `Agent.state` — custom application state
+    - `Agent._interrupt_state` — internal state for interrupt handling
+    - Conversation manager internal state — state held by the conversation manager (e.g., sliding window position)
+    However, this approach is fragile: it requires knowledge of internal implementation details, and the set of properties may change between versions. This proposal introduces a stable, convenient API to accomplish the same thing without relying on internals.
+    **This API does not change agent behavior** — it simply provides a clean way to serialize and restore the existing state that already exists on the agent.
+    ## Context
+    Developers need a way to preserve and restore the exact state of an agent at a specific point in time. The existing SessionManagement doesn't address this:
+    - SessionManager works in the background, incrementally recording messages rather than full state. This means it's not possible to restore to arbitrary points in time.
+    - After a message is saved, there is no way to modify it and have it recorded in session-management, preventing more advance context-management strategies while being able to pause & restore agents.
+    - There is no way to proactively trigger session-management (e.g., after modifying `agent.messages` or `agent.state` directly)
+    ## Decision
+    Add a low-level, explicit snapshot API as an alternative to automatic session-management. This enables preserving the exact state of an agent at a specific point and restoring it later — useful for evaluation frameworks, custom session management, and checkpoint/restore workflows.
+    ### API Changes
+    ```python
+    class Snapshot(TypedDict):
+        type: str              # the type of data stored (e.g., "agent")
+        state: dict[str, Any]  # opaque; do not modify — format subject to change
+        metadata: dict         # user-provided data to be stored with the snapshot
+    class Agent:
+        def save_snapshot(self, metadata: dict | None = None) -> Snapshot:
+            """Capture the current agent state as a snapshot."""
+            ...
+        def load_snapshot(self, snapshot: Snapshot) -> None:
+            """Restore agent state from a snapshot."""
+            ...
+    ```
+    ### Behavior
+    Snapshots capture **agent state** (data), not **runtime behavior** (code):
+    - **Agent State** — Data persisted as part of session-management: conversation messages, context, and other JSON-serializable data. This is what snapshots save and restore.
+    - **Runtime Behavior** — Configuration that defines how the agent operates: model, tools, ConversationManager, etc. These are *not* included in snapshots and must be set separately when creating or restoring an agent.
+    The intent is that anything stored or restored by session-management would be stored in a snapshot — so this proposal is *not* documenting or changing what is persisted, but rather providing an explicit way to do what session-management does automatically.
+    ### Contract
+    - **`metadata`** — Application-owned. Strands does not read, modify, or manage this field. Use it to store checkpoint labels, timestamps, or any application-specific data without the need for a separate/standalone object/datastore.
+    - **`type` and `state`** — Strands-owned. These fields are managed internally and should be treated as opaque. The format of `state` is subject to change; do not modify or depend on its structure.
+    - **Serialization** — Strands guarantees that `type` and `state` will only contain JSON-serializable values.
+    ### Future Concerns
+    - Snapshotting for MultiAgent constructs - Snapshot is designed in a way that the snapshot could be reused for multi-agent with a similar api
+    - Providing a storage API for snapshot CRUD operations (save to disk, database, etc.)
+    - Providing APIs to customize serialization formats
+    ## Developer Experience
+    ### Evaluations via Rewind and Replay
+    ```python
+    agent = Agent(tools=[tool1, tool2])
+    snapshot = agent.save_snapshot()
+    result1 = agent("What is the weather?")
+    # ...
+    agent2 = Agent(tools=[tool3, tool4])
+    agent2.load_snapshot(snapshot)
+    result2 = agent2("What is the weather?")
+    # ...
+    # Human/manual evaluation if one outcome was better than the other
+    # ...
+    ```
+    ### Advanced Context Management
+    ```python
+    agent = Agent(conversation_manager=CompactingConversationManager())
+    snapshot = agent.save_snapshot(metadata={"checkpoint": "before_long_task"})
+    # ... later ...
+    later_agent = Agent(conversation_manager=CompactingConversationManager())
+    later_agent.load_snapshot(snapshot)
+    ```
+    ### Persisting Snapshots
+    ```python
+    import json
+    agent = Agent(tools=[tool1, tool2])
+    agent("Remember that my favorite color is orange.")
+    # Save to file
+    snapshot = agent.save_snapshot(metadata={"user_id": "123"})
+    with open("snapshot.json", "w") as f:
+        json.dump(snapshot, f)
+    # Later, restore from file
+    with open("snapshot.json", "r") as f:
+        snapshot: Snapshot = json.load(f)
+    agent = Agent(tools=[tool1, tool2])
+    agent.load_snapshot(snapshot)
+    agent("What is my favorite color?")  # "Your favorite color is orange."
+    ```
+    ### Edge cases
+    Restoring runtime behavior (e.g., tools) is explicitly not supported:
+    ```python
+    agent1 = Agent(tools=[tool1, tool2])
+    snapshot = agent1.save_snapshot()
+    agent_no = Agent(snapshot)  # tools are NOT restored
+    ```
+    ## Up for Debate
+    ### What state should be included in a snapshot?
+    The current proposal includes:
+    - **messages** — conversation history
+    - **interrupt state** — internal state for paused/resumed interrupts
+    - **agent state** — custom application state (`agent.state`)
+    - **conversation manager state** — internal state of the conversation manager (but not the conversation manager itself)
+    This draws a distinction between "evolving state" (data that changes as the agent runs) and "agent definition" (configuration that defines what the agent *is*):
+    | Evolving State (snapshotted) | Agent Definition (not snapshotted) |
+    |------------------------------|-----------------------------------|
+    | messages | system_prompt |
+    | interrupt state | tools |
+    | agent state | model |
+    | conversation manager state | conversation_manager |
+    Further justification: these three properties are also what SessionManagement persists today, so this API aligns with existing behavior.
+    **Open question:** Is this the right boundary? Are there other properties that should be considered "evolving state"?
+    ## Consequences
+    **Easier:**
+    - Building evaluation frameworks with rewind/replay capabilities
+    - Implementing custom session management strategies
+    - Creating checkpoints during long-running agent tasks
+    - Cloning agents (load the same snapshot into multiple agent instances)
+    - Resetting agents to a known state (we do this manually for Graphs)
+    **More difficult:**
+    - N/A — this is an additive API
+    ## Willingness to Implement
+    Yes

Propose low-level snapshot api #497

Are you sure you want to change the base?

Uh oh!

Propose low-level snapshot api #497

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JackYPCOnline Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

poshinchen Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mehtarac Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JackYPCOnline Feb 2, 2026 •

edited

Loading

poshinchen Feb 2, 2026 •

edited

Loading

mehtarac Feb 2, 2026 •

edited

Loading