Sagents.Persistence.StateSerializer (Sagents v0.8.0-rc.1)

Handles serialization and deserialization of AgentServer state.

Automatically handles:

Version migrations
Non-serializable data (PIDs, refs)
Consistent use of string keys (for JSONB compatibility)

String Keys

NOTE: This serializer uses string keys throughout to match PostgreSQL JSONB behavior. When JSONB maps are restored from the database, they will have string keys, not atoms. For consistency, the serializer exports to string keys and expects string keys on import.

Agent Configuration vs Conversation State

StateSerializer follows the principle: Code lives in code. Data lives in data.

What is serialized:

✅ Conversation state: messages, todos, metadata

What is NOT serialized:

❌ Agent configuration: middleware, tools, model
❌ Runtime identifiers: agent_id

Agent capabilities (middleware, tools, model) are code-defined by your application. When restoring a conversation, create the agent from your application code and restore only the conversation state.

See AgentServer module documentation for complete restoration examples.

Versioning

The serialized state includes a version field that allows for future migrations of the state format. The current version is 2.

v1 → v2

The Sagents.Middleware.SubAgent task tool's required argument was renamed from subagent_type to task_name. Stored tool-call arguments on assistant messages are rewritten on read so historical conversations remain consistent with the current tool schema. Affects calls named "task" or "get_task_instructions".

Summary

Functions

current_version()

Get the current serialization format version.

deserialize_server_state(agent_id, data, opts \\ [])

Deserializes a serialized state map back to a State struct.

deserialize_state(agent_id, data)

Deserializes a map with string keys into a State struct.

serialize_server_state(agent, state)

Serializes AgentServer state to a map with string keys.

serialize_state(state)

Serializes a State struct to a map with string keys.

Functions

current_version()

Get the current serialization format version.

deserialize_server_state(agent_id, data, opts \\ [])

Deserializes a serialized state map back to a State struct.

The agent configuration is NOT deserialized - agents must be created from your application code. This function only restores conversation state (messages, metadata).

Parameters

agent_id - The agent_id to use (NOT serialized, provided by you)
data - The serialized state map (from JSONB or export)
opts - Options (currently unused, kept for compatibility)

Returns

{:ok, state} - Successfully deserialized state
{:error, reason} - Deserialization failed

deserialize_state(agent_id, data)

Deserializes a map with string keys into a State struct.

The agent_id must be provided as it is not part of the serialized data (it's a runtime identifier for process registration and PubSub).

Returns {:ok, state} on success or {:error, reason} on failure.

serialize_server_state(agent, state)

Serializes AgentServer state to a map with string keys.

Returns a map with string keys suitable for storage in JSONB columns.

Note: The agent_id is NOT included in the serialized state. The agent_id is a runtime identifier used for process registration and PubSub topics, not part of the conversation state. When restoring state, you must provide the agent_id to deserialize_server_state/2 or AgentServer.start_link_from_state/2.

serialize_state(state)

Serializes a State struct to a map with string keys.