Snapshots

Snapshots provide a point-in-time capture of agent state that can be saved and restored later. You control which fields are included, and serialization is left to you — snapshots are plain JSON-serializable objects that you can persist however you like.

Basic Usage

Taking a Snapshot

Use the "session" preset to capture the most common fields:

Python

from strands import Agent

agent = Agent(system_prompt="You are a helpful assistant")
agent("Hello!")
agent.state.set("user_id", "user-123")

# Capture a snapshot with the session preset
snapshot = agent.take_snapshot(preset="session")

print(snapshot.schema_version)  # "1.0"
print(snapshot.created_at)      # ISO 8601 timestamp
print(snapshot.data.keys())     # messages, state, conversation_manager_state, interrupt_state

The "session" preset captures messages, state, conversation_manager_state, and interrupt_state. The system_prompt field is not included by default — see Field Selection to customize which fields are captured.

TypeScript

const agent = new Agent({ systemPrompt: 'You are a helpful assistant' })
await agent.invoke('Hello!')
agent.appState.set('user_id', 'user-123')

// Capture a snapshot with the session preset
const snapshot = takeSnapshot(agent, { preset: 'session' })

console.log(snapshot.schemaVersion) // "1.0"
console.log(snapshot.createdAt) // ISO 8601 timestamp
console.log(Object.keys(snapshot.data)) // messages, state, systemPrompt

The "session" preset captures messages, state, and systemPrompt.

Restoring a Snapshot

Load a snapshot to restore the agent to a previous state:

Python

from strands import Agent

agent = Agent(system_prompt="You are a helpful assistant")
agent("Hello!")

# Take a snapshot
snapshot = agent.take_snapshot(preset="session")

# Continue the conversation
agent("Tell me a joke")
agent("Tell me another one")

# Restore to the earlier state
agent.load_snapshot(snapshot)

# The agent is back to the state after "Hello!"
print(len(agent.messages))  # Only the messages from before the jokes

TypeScript

const agent = new Agent({ systemPrompt: 'You are a helpful assistant' })
await agent.invoke('Hello!')

// Take a snapshot
const snapshot = takeSnapshot(agent, { preset: 'session' })

// Continue the conversation
await agent.invoke('Tell me a joke')
await agent.invoke('Tell me another one')

// Restore to the earlier state
loadSnapshot(agent, snapshot)

// The agent is back to the state after "Hello!"
console.log(agent.messages.length) // Only the messages from before the jokes

Only fields present in the snapshot are restored. If a field was excluded when the snapshot was taken, the agent’s current value for that field is left unchanged.

Field Selection

Snapshots support flexible field selection through presets, includes, and excludes. The resolution order is: preset → include → exclude.

Python

Field	Description
messages	Conversation history
state	Agent key-value state
conversation_manager_state	Conversation manager internal state
interrupt_state	Human-in-the-loop interrupt state
system_prompt	System prompt content

TypeScript

Field	Description
messages	Conversation history
state	Agent key-value state
systemPrompt	System prompt

Note

The "session" preset is currently the only available preset. It includes the same fields that the Session Manager persists by default.

Use include to select specific fields without a preset, or to add fields on top of a preset. Use exclude to remove fields from a preset:

Python

# Capture only messages and state (no preset)
snapshot = agent.take_snapshot(include=["messages", "state"])

# Session preset plus system_prompt
snapshot = agent.take_snapshot(preset="session", include=["system_prompt"])

# Session preset minus interrupt_state
snapshot = agent.take_snapshot(preset="session", exclude=["interrupt_state"])

TypeScript

// Capture only messages and state (no preset)
const messagesOnly = takeSnapshot(agent, { include: ['messages', 'state'] })

// Session preset minus systemPrompt
const noPrompt = takeSnapshot(agent, { preset: 'session', exclude: ['systemPrompt'] })

Application Data

Snapshots support an app_data (Python) / appData (TypeScript) field for storing application-owned data alongside the agent state. Strands does not read or modify this data — it’s passed through verbatim.

This is useful for attaching metadata like a display name for the snapshot, the current step in a workflow, user preferences, or any other context your application needs to associate with a particular point in time.

Python

snapshot = agent.take_snapshot(
    preset="session",
    app_data={
        "snapshot_label": "After onboarding",
        "workflow_step": 3,
        "user_display_name": "Alice",
    },
)

# Access app data later
print(snapshot.app_data["snapshot_label"])     # "After onboarding"
print(snapshot.app_data["user_display_name"])  # "Alice"

TypeScript

const snapshot = takeSnapshot(agent, {
  preset: 'session',
  appData: {
    snapshotLabel: 'After onboarding',
    workflowStep: 3,
    userDisplayName: 'Alice',
  },
})

// Access app data later
console.log(snapshot.appData.snapshotLabel) // "After onboarding"
console.log(snapshot.appData.userDisplayName) // "Alice"

Serialization

Snapshots are JSON-serializable, making them easy to persist to any storage backend.

Python

import json
from strands import Agent, Snapshot

agent = Agent()
agent("Hello!")

# Take a snapshot
snapshot = agent.take_snapshot(preset="session")

# Serialize to JSON
json_str = json.dumps(snapshot.to_dict())

# Store to file, database, S3, etc.
with open("snapshot.json", "w") as f:
    f.write(json_str)

# Later, restore from JSON
with open("snapshot.json", "r") as f:
    data = json.loads(f.read())

restored_snapshot = Snapshot.from_dict(data)

# Load into a new agent
new_agent = Agent()
new_agent.load_snapshot(restored_snapshot)

TypeScript

const agent = new Agent()
await agent.invoke('Hello!')

// Take a snapshot
const snapshot = takeSnapshot(agent, { preset: 'session' })

// Serialize to JSON string
const jsonString = JSON.stringify(snapshot)

// Store to file, database, S3, etc.
// ...

// Later, restore from JSON
const parsed: Snapshot = JSON.parse(jsonString)

// Load into a new agent
const newAgent = new Agent()
loadSnapshot(newAgent, parsed)

Use Cases

Checkpointing

Save agent state at key points in a workflow so you can resume from the last checkpoint if something goes wrong:

Python

from strands import Agent

agent = Agent(system_prompt="You are a research assistant")

# Step 1: Gather information
agent("Research the latest trends in AI agents")
checkpoint_1 = agent.take_snapshot(preset="session")

# Step 2: Analyze (might fail or produce poor results)
agent("Analyze the key themes and summarize")
checkpoint_2 = agent.take_snapshot(preset="session")

# If step 2 didn't go well, roll back to checkpoint 1
agent.load_snapshot(checkpoint_1)
agent("Focus specifically on multi-agent systems and summarize")

TypeScript

const agent = new Agent({ systemPrompt: 'You are a research assistant' })

// Step 1: Gather information
await agent.invoke('Research the latest trends in AI agents')
const checkpoint1 = takeSnapshot(agent, { preset: 'session' })

// Step 2: Analyze (might fail or produce poor results)
await agent.invoke('Analyze the key themes and summarize')
const checkpoint2 = takeSnapshot(agent, { preset: 'session' })

// If step 2 didn't go well, roll back to checkpoint 1
loadSnapshot(agent, checkpoint1)
await agent.invoke('Focus specifically on multi-agent systems and summarize')

Branching Conversations

Create multiple conversation branches from the same starting point:

Python

from strands import Agent

agent = Agent(system_prompt="You are a creative writer")
agent("Write the opening paragraph of a mystery novel")

# Save the branch point
branch_point = agent.take_snapshot(preset="session")

# Branch A: noir style
agent("Continue in a noir detective style")
noir_snapshot = agent.take_snapshot(preset="session")

# Branch B: go back and try cozy mystery
agent.load_snapshot(branch_point)
agent("Continue in a cozy mystery style")
cozy_snapshot = agent.take_snapshot(preset="session")

TypeScript

const agent = new Agent({ systemPrompt: 'You are a creative writer' })
await agent.invoke('Write the opening paragraph of a mystery novel')

// Save the branch point
const branchPoint = takeSnapshot(agent, { preset: 'session' })

// Branch A: noir style
await agent.invoke('Continue in a noir detective style')
const noirSnapshot = takeSnapshot(agent, { preset: 'session' })

// Branch B: go back and try cozy mystery
loadSnapshot(agent, branchPoint)
await agent.invoke('Continue in a cozy mystery style')
const cozySnapshot = takeSnapshot(agent, { preset: 'session' })

Relationship to Session Management

Session management handles persistence automatically — state is saved and restored at the right lifecycle points without you writing any persistence code. Snapshots give you manual control: you decide when to capture state, what to include, and where to store it. Use session management when you want hands-off persistence, and snapshots when you need precise control over save points.

See Also

• State Management — Conversation history, agent state, and request state
• Session Management — Automatic persistence with file or S3 storage
• Conversation Management — Managing conversation history and context window