AgentState expansion proposal

[afarntrog]

AgentState Expansion

Executive Summary

• Customer Problem: Strands SDK users cannot store rich Python objects (dataclasses, Pydantic models, datetime, etc.) or runtime resources (DB connections, API clients) in AgentState. GitHub issue #1245 demonstrates active customer demand.
• Recommended Solution: Implement pluggable serializers at AgentState/Agent level (Option 1) with persist parameter for runtime-only state (Option 1). Default JSON serializer maintains backward compatibility; optional PickleSerializer enables full Python object support.
• Business Impact: Achieves feature parity with competing agent frameworks, enhances SDK competitiveness, and provides developers the flexibility they’re asking for.
• Decision Requested: Approve Option 1 serializer configuration (AgentState + Agent level) and Option 1 runtime state (persist parameter) for immediate implementation.

Current State of the world:

Strands offers an AgentState primitive that provides key-value storage for stateful information that exists outside of the conversation context. It can be accessed and modified by tools and application logic and is saved to session when using a session manager.

Here’s an example of how developers use AgentState:

from strands import Agent, tool, ToolContext

@tool(context=True)
def tally_invocations(tool_context: ToolContext):
    # Get current action count
    count = tool_context.agent.state.get("count") or 0

    # Update state
    tool_context.agent.state.set("count", count + 1)
    return f"Total invocations: {tool_context.agent.state.get('count')}"


# Create agent with tools
agent = Agent(tools=[tally_invocations])

# Use tools that modify and read state
agent("Track that I invoked the agent")

Problem:

Strands only allows a subset of objects to be stored in AgentState

Currently, Strands agents require agent.state to be JSON-serializable, limiting it to basic Python types (str, int, dict, list, etc.). This prevents users from storing:

• Python dataclasses
• Pydantic models
• Custom objects with complex behavior
• Rich types like datetime, Decimal, UUID
• Objects with non-serializable data (DB connections, file handles)

Examples:

• Here’s an example of what works:

from strands import Agent

agent = Agent(model="...")

# Basic JSON-serializable types work
agent.state.set("count", 42)  

• Here’s an example of what does not work:

from strands import Agent
from datetime import datetime

agent = Agent(model="...")

# datetime - raises ValueError
agent.state.set("created_at", datetime.now())

**In addition **to the above issue of requiring JSON-serializable objects, there is another problem in that users want to be able to store Runtime-Only Resources that cannot and are not meant to be serialized. Such as:

• Database connections (sqlite3.Connection, psycopg2.connection)
• API clients (boto3.client, httpx.Client)

These represent runtime resources, not data. They cannot be meaningfully serialized because they contain system handles that are only valid in the current process.

Here’s an example of how a developer would like to access a database connection in their tool which does not currently work as they cannot store the db connection in their AgentState

@tool(context=True)
def query_database(query: str, tool_context: ToolContext) -> str:
    db = ???  # How to access runtime DB connection from state?
    return db.execute(query).fetchall()


agent = Agent(tools=[query_database])
agent.state.set("db", sqlite3.connect(":memory:"))  # ❌ Cannot serialize

Users want to store a broader set of objects in the AgentState as we can see requested here: #1245 Therefore, in this document we outline an approach on how to support a larger diverse set of objects to be stored in AgentState

Proposed Solution:

To solve the above two problems, our goal is to offer pluggable serializers. Such as a simple (default) JSON serializer that can only serialize JSON serializable objects or a Pickle serializer that can serialize (almost) all python objects.

However, in addition to the Pluggable serializers proposed we will also need to support runtime-only objects. So AgentState would always need to support both of the following types of state:

1. Serializable state (via Pluggable serializers)
2. A runtime-only state pattern (for non-serializable objects such as DB connections)

Serializer Configuration Options:

To solve the problem of supporting a broad set of python objects to store in state we present a couple of options of how and where devs would use the proposed Pluggable Serializer solution.

Option 1: Serializer on AgentState and Agent level (recommended)

We will store the Serializer on the AgentState level and also allow it to be passed in on Agent Instantiation.

# Agent class delegates to AgentState
class Agent:
    def __init__(self, ..., ***state_serializer* *****|***** ** *****None***** ** *****=***** ** *****None***, ...):
        self.state = AgentState(serializer=state_serializer)

# Both work:
agent = Agent(model, state_serializer=PickleSerializer())

# or
agent.state.serializer = PickleSerializer() # Set serializer
agent.state.serializer  # Get current serializer
agent.state.serialize()  # Uses whatever serializer is set
agent.state.deserialize(data)

Pros: Maximum flexibility, configurable at both levels.
Cons: Two ways to do same thing (though one is just delegation), another parameter in the Agent class (this can be offset as it can be potentially added as part of the agent_config the team is thinking about in the future.)

Note: The Agent constructor will raise an error when there is a conflict conflict:

We currently support the user passing in an existing AgentState object. We cannot allow the use to pass in both - the AgentState and state_serializer.

def __init__(self, ..., state_serializer | None = None, ...):
    ...
    # Conflict check
    if isinstance(state, AgentState) and state_serializer is not None:
        raise ValueError(
            "Cannot provide both 'state' (AgentState) and 'state_serializer'. "
            "Configure serializer on the AgentState directly."
        )
    ...

---

You can skip reading the below additional options if you agree with the above recommended option

---

Option 2: Serializer on SessionManager level

from strands.session import FileSessionManager, PickleSerializer

session = FileSessionManager(
    session_id="abc",
    serializer=PickleSerializer()  # Default: JSONSerializer
)
agent = Agent(model, session_manager=session)

Rationale: SessionManager owns persistence → owns serialization format
Pros: Clean separation, SessionManager already handles storage
Cons:

• All agents in a session share serialization strategy (this can arguably be a pro as well)
• The serialization is tightly coupled to Session Management and would not work outside of session management such as with checkpointing

Option 3: Serializer on Agent level

from strands import Agent
from strands.serializers import PickleSerializer, JSONSerializer

# At construction
agent = Agent(
    model=model,
    state_serializer=PickleSerializer()
)

# Or mutable
agent.state_serializer = JSONSerializer()

# Usage patterns
session_manager.sync_agent(agent)    # Uses agent.state_serializer.serialize()

Pros:

• Agent is the primary object users interact with
• Per-agent control
• Single configuration point for all state operations
• Checkpointing is an Agent method, so serializer lives where it's used
• Clear ownership: "this agent serializes its state this way"

Cons:

• Agent takes on another responsibility (serialization policy)
• State could theoretically outlive agent (though rare)
• Serializer is really about persistence, not agent behavior

SessionManager calls agent.state_serializer.serialize() during persistence.

Option 4: Serializer on AgentState level

from strands import Agent
from strands.agent.state import AgentState, PickleSerializer

# Via state object
agent = Agent(model=model)
agent.state.serializer = PickleSerializer()

# Or factory pattern
state = AgentState(serializer=PickleSerializer())
agent = Agent(model=model, state=state)

# Usage
snapshot = agent.state.serialize()
data = agent.state.deserialize(snapshot)

Pros:

• State is self-describing - carries its serialization behavior
• Decoupled from Agent - state could be passed around, saved, restored independently
• AgentState is already a class (JSONSerializableDict) - this is extending it
• Follows "tell, don't ask" - state knows how to serialize itself

Cons:

• Slightly less discoverable (agent.state.serializer vs passing in to the Agent on initialization)

Option 5: Both, Serializer on AgentState and Agent level

This allows for setting and retrieving on the Agent level as well even though it ultimately delegates to the State

# Agent delegates to state
class Agent:
    def __init__(self, model, state_serializer=None, state=None, ...):
        self.state = state or AgentState(serializer=state_serializer)
    
    @property
    def state_serializer(self):
        return self.state.serializer
    
    @state_serializer.setter
    def state_serializer(self, value):
        self.state.serializer = value

# Both work:
agent = Agent(model, state_serializer=PickleSerializer())
# or
agent.state.serializer = PickleSerializer()
# or
agent.state_serializer = PickleSerializer()  # Delegates

Pros: Maximum flexibility, discoverable at both levels
Cons: Two ways to do same thing

---

Options skipping is done here. Continue reading below

---

Runtime State Configuration Options:

Option 1: Transient Flag with persist Parameter (recommended)

Add a persist parameter to the existing set() method to mark values as transient (runtime-only).

class AgentState:
    def __init__(self, ...):
        self._data: dict[str, Any] = {}
        self._transient_keys: set[str] = set()  # Track transient keys
        
    def set(self, key: str, value: Any, *, persist: bool = True) -> None:
        ...

    def serialize(self) -> bytes:
        """Serialize only persistent keys."""
        persistent_data = {k: v for k, v in self._data.items() 
                          if k not in self._transient_keys}
        return self.serializer.serialize(persistent_data)

Usage Examples

from strands import Agent, PickleSerializer
import sqlite3

agent = Agent(state_serializer=PickleSerializer())

agent.state.set("user_id", "12345") *# ✅ Persisted - no change*

*# Runtime-only state (explicit opt-out)*
agent.state.set("db", sqlite3.connect(":memory:"), persist=False)  *# ✅ Not persisted

*

Pros

• Minimal API surface change - Single new parameter on existing method
• Backward compatible - Default persist=True maintains current behavior
• Unified retrieval - Single get() method for all values
• Explicit at call site - Clear indication of what will persist
• Easy migration - Existing code continues to work unchanged

Cons

• Mixed storage - Persistent and transient data in same namespace could be confusing
• Tracking overhead - Need to maintain _transient_keys set

Option 2: Separate Runtime Methods

Add dedicated methods for runtime-only state management.

Implementation

class AgentState:
    def __init__(self, ...):
        self._data: dict[str, Any] = {}        *# Persistent (serialized)*
        self._runtime: dict[str, Any] = {}     *# Runtime-only (never serialized)*
    
    *# New methods for runtime state*
    def set_runtime(self, key: str, value: Any) -> None:
        """Set runtime-only value (not persisted)."""
        ...

    def get_runtime(self, key: str | None = None) -> Any:
        """Get runtime-only value."""
        ...

Usage Examples

from strands import Agent, PickleSerializerimport sqlite3import boto3

agent = Agent(model="...", state_serializer=PickleSerializer())

*# Persistent state (serialized)*
agent.state.set("user_id", "12345") # *✅ Persisted*

*# Runtime-only state (never serialized)*
agent.state.set_runtime("db", sqlite3.connect(":memory:"))  *# ✅ Not Persisted*

Pros

• Explicit separation - Clear distinction between persistent and runtime
• Visual clarity - Method names make intent obvious
• Parallel namespaces - Can have same key in both persistent and runtime
• Cleaner mental model - Two distinct concepts, two distinct APIs

Cons

• Larger API surface - Three new methods to learn
• Dual retrieval - Must remember which get method to use
• More verbose - Longer method names for runtime operations
• Potential confusion - Users might use wrong method accidentally

---

---

Appendix:

PR: #1408

DX:

Basic Usage with Default JSON Serializer

from strands import Agent
agent = Agent()

# Store JSON-compatible values
agent.state.set("user_id", "12345")
agent.state.set("preferences", {"theme": "dark", "language": "en"})
agent.state.set("visit_count", 42)

data = agent.state.serialize() # This is called under-the-hood in session management etc
deserialize_data = agent.state.deserialize(data)

Using PickleSerializer for Rich Python Types

from datetime import datetime
from uuid import uuid4
from strands import Agent, PickleSerializer
from dataclasses import dataclass

@dataclass
class UserDataclass:
    name: str
    role: str

agent = Agent(state_serializer=PickleSerializer())

# Now you can store any Python object
agent.state.set("created_at", datetime.now())
agent.state.set("session_id", uuid4())
agent.state.set("user", UserDataclass(name="Alice", role="admin"))

data = agent.state.serialize() # This is called under-the-hood in session management etc

Transient State (Runtime-Only Values)

from strands import Agent

agent = Agent()

# Persistent state - included in serialization
agent.state.set("user_id", "12345")

# Transient state - excluded from serialization
# Useful for: DB connections..
agent.state.set("db_connection", connection_pool, persist=False)

# Check if a key is transient
agent.state.is_transient("db_connection")  # True
agent.state.is_transient("user_id")         # False

# Serialize - only includes persistent state
data = agent.state.serialize()  # "db_connection" NOT included

Custom Serializers

from typing import Any
from strands import StateSerializer, AgentState
import msgpack  # Example: using msgpack

class MsgPackSerializer:
    """Custom serializer using msgpack."""
    
    def serialize(self, data: dict[str, Any]) -> bytes:
        return msgpack.packb(data)
    
    def deserialize(self, data: bytes) -> dict[str, Any]:
        return msgpack.unpackb(data)
    
    def validate(self, value: Any) -> None:
        # msgpack supports similar types to JSON
        try:
            msgpack.packb(value)
        except Exception as e:
            raise ValueError(f"Not msgpack serializable: {e}")

# Use custom serializer
state = AgentState(serializer=MsgPackSerializer())

[zastrowm]

Option 1: Serializer on AgentState and Agent level (recommended)

We will store the Serializer on the AgentState level and also allow it to be passed in on Agent Instantiation.

...

Pros: Maximum flexibility, configurable at both levels. Cons: Two ways to do same thing (though one is just delegation), another parameter in the Agent class (this can be offset as it can be potentially added as part of the agent_config the team is thinking about in the future.)

What benefit does it have on Agent given that (AFAICT) it's specific to AgentState?

I'm curious where else we expect this to be used. Everywhere else we do serialization, it's the SDK driving it and thus we don't need control over the serialization.

[zastrowm]

Relatedly:

Option 5: Both, Serializer on AgentState and Agent level

...

Pros: Maximum flexibility, discoverable at both levels

I'm not sure why "discoverable" [at the agent level] is what we're optimizing for. I see AgentState as a "data-store" - and is the only "non-SDK" provide data store that needs serialization; elevating it to the agent level without anything else needing it seems... odd

[afarntrog]

What benefit does it have on Agent given that (AFAICT) it's specific to AgentState?

Good point. So i'm thinking that in the current agent most users won't access state directly (agent.state...) when setting up their agent. They will specify everything during Agent construction and just run the agent() expecting to work with the provided config. This approach just adds another param to the Agent construction allowing this pattern to continue. It's not tightly coupled with Agent as the Agent class just delegates the param to the AgentState object that is initialized during the Agent initialization. We won't be storing the serializer on the agent class.

The alternative is forcing users to set it directly on the state object which is more steps/tedious

agent = Agent(config...,)

agent.state.serializer=MySerializer()
agent(prompt)

Add a Comment

[mkmeral]

What benefit does it have on Agent given that (AFAICT) it's specific to AgentState?

I want to actually challenge this a bit. should it be specific to agent state? we can use this to serialize agent as is, hooks, etc. included. this can be great for checkpointing. one-shop-serialization

[zastrowm]

I see that as a separate use case and/or feature. I would also ask, does that need Strands framework support today - can you not use Pickle today for this or do things break?

Up until now (and I think it's a good guideline) we've separate out state from behavior. E.g. whenever you restore state, you have to configure the behavior (hooks, etc.) back and restore the state. I like that because it's safe by default

I started a thread regarding the separation of state & behavior - I think this is one thing we'll have to decide. I think there is still a use case specific to AgentState however that would be enabled by letting more things be serializable - Pydantic objects, for instance.

[zastrowm]

Option 1: Serializer on AgentState and Agent level (recommended)
Note: The Agent constructor will raise an error when there is a conflict conflict:

This seems contrary to our tenet:

Composability: Primitives are building blocks with each other. Each feature of Strands is developed with all other features in mind, they are consistent and complement one another.

For that reason, I would lean towards one or the other but not both

[afarntrog]

I like your idea of getting rid of the proposed state_serializer variable from the Agent init altogether and requiring devs to pass in the AgentState object directly with the serializer initialized like:

state = AgentState(serializer=PickleSerializer())
agent = Agent(..., state=state)

[zastrowm]

I think there's a larger item here as to what AgentState represents. AgentState to me intrinsically holds data specific to each agent and because it's only data, it must be serializable to support both snapshots & session management.

However, this item:

Objects with non-serializable data (DB connections, file handles)

repurposes AgentState to be something else - specifically that it's a container of both state and possibly runtime behavior and thus wouldn't necessarily be serializable. The section later on "Transient State (Runtime-Only Values)" goes a bit more into this, but ultimately this is a key point that we need a decision on - is AgentState just a container of state or also holding runtime behavior & data.

---

Side note: I think Strands is lacking here and we need an AgentServices, but I don't want to conflate that need with what AgentState is or should be.

[mkmeral]

Problem

Do people want/need these other "non-serializable" objects to persist? Is that part of the problem?

Given the problem definition, it can just be solved using json.dumps(object, default=None). If we have a use case for persisting these other non-JSON-serializable objects, then i'd be more inclined for the pickle and custom serializer option

[mkmeral]

agent.state.set("db", sqlite3.connect(":memory:"))

is this safe? client objects will likely have tokens/creds inside, we might want to put a warning in docs for it

[dbschmigelski]

Also just a step back, for things like this it seems like we are recreating dependency injection

like if we want DI maybe AgentState isn't the best place for that

[dbschmigelski]

Option 4: Serializer on AgentState level

This to me like the most straightforward approach since we already have the pattern. I feel like we can do this in two steps

1. Abstract AgentState the the serializable one as the default impl, just the 3 methods on there: get, delete, set. Might need to add another for serialize/deserialize This would be flexible for people to create their own AgentState+Session pair

2. Improve the DefaultAgentState impl