feat(langgraph-checkpoint-aws): add Valkey checkpoint saver for AgentCore (#738)

This PR provides AgentCore-compatible checkpoint savers that use Valkey
as the storage backend, combining AgentCore session management concepts
with Valkey's storage and search capabilities.

Author: seaofawareness

libs/langgraph-checkpoint-aws/README.md

@@ -38,12 +38,12 @@ pip install 'langgraph-checkpoint-aws[valkey]'
 This package provides following main components:
 
 1. **AgentCoreMemorySaver** - AWS Bedrock-based checkpoint storage
-2. **AgentCoreMemoryStore** - AWS Bedrock-based document store
-3. **ValkeyCache** - Valkey LLM response cache
+2. **AgentCoreValkeySaver** - AgentCore-compatible Valkey checkpoint storage
+3. **DynamoDBSaver** - DynamoDB-based checkpoint storage with S3 offloading
 4. **ValkeySaver** - Valkey checkpoint storage
-5. **ValkeyStore** - Valkey document store
-6. **DynamoDBSaver** - DynamoDB-based checkpoint storage with S3 offloading
-
+5. **AgentCoreMemoryStore** - AWS Bedrock-based document store
+6. **ValkeyStore** - Valkey document store
+7. **ValkeyCache** - Valkey LLM response cache
 
 ## Usage
 
@@ -248,7 +248,47 @@ with ValkeySaver.from_conn_string(
     result = graph.invoke(1, config)
 ```
 
-### 6. Valkey Store for Document Storage
+### 6. AgentCore Valkey Storage
+
+For AWS Bedrock AgentCore-compatible applications that want to use Valkey instead of managed Memory:
+
+```python
+from langgraph.prebuilt import create_react_agent
+from langgraph_checkpoint_aws import AgentCoreValkeySaver
+
+# Using connection string
+with AgentCoreValkeySaver.from_conn_string(
+    "valkey://localhost:6379",
+    ttl_seconds=3600,  # 1 hour TTL
+    pool_size=10
+) as checkpointer:
+    # Create your agent
+    graph = create_react_agent(
+        model=model,
+        tools=tools,
+        checkpointer=checkpointer
+    )
+
+    # AgentCore-style configuration (requires actor_id)
+    config = {
+        "configurable": {
+            "thread_id": "session-123",
+            "actor_id": "agent-456",  # Required for AgentCore compatibility
+            "checkpoint_ns": "production"
+        }
+    }
+
+    result = graph.invoke({"messages": [...]}, config)
+```
+
+**Key Differences from ValkeySaver:**
+- ✅ Requires `actor_id` in configuration (AgentCore requirement)
+- ✅ Uses AgentCore-compatible key structure (`agentcore:*` prefix)
+- ✅ Built-in retry logic with exponential backoff
+- ✅ Pydantic validation for data integrity
+- ⚠️ **Data is NOT compatible with ValkeySaver** - choose one at project start
+
+### 7. Valkey Store for Document Storage
 
 Document storage with vector search capabilities using ValkeyIndexConfig:
 

libs/langgraph-checkpoint-aws/langgraph_checkpoint_aws/__init__.py

@@ -4,6 +4,7 @@
 """
 
 from importlib.metadata import version
+from typing import Any
 
 from langgraph_checkpoint_aws.agentcore.saver import (
     AgentCoreMemorySaver,
@@ -14,6 +15,7 @@
 
 # Conditional imports for Valkey functionality
 try:
+    from langgraph_checkpoint_aws.agentcore import AgentCoreValkeySaver
     from langgraph_checkpoint_aws.cache import ValkeyCache
     from langgraph_checkpoint_aws.checkpoint import AsyncValkeySaver, ValkeySaver
     from langgraph_checkpoint_aws.store import (
@@ -42,17 +44,20 @@
     )
 
     valkey_available = True
-except ImportError:
-    # If dependencies are not available, create placeholder classes
+except ImportError as e:
+    # Store the import error for better debugging
+    _import_error = e
+
     from typing import Any
 
     def _missing_dependencies_error(*args: Any, **kwargs: Any) -> Any:
         raise ImportError(
             "Valkey functionality requires optional dependencies. "
             "Install them with: pip install 'langgraph-checkpoint-aws[valkey]'"
-        )
+        ) from _import_error
 
     # Create placeholder classes that raise helpful errors
+    AgentCoreValkeySaver: type[Any] = _missing_dependencies_error  # type: ignore[assignment,no-redef]
     AsyncValkeySaver: type[Any] = _missing_dependencies_error  # type: ignore[assignment,no-redef]
     AsyncValkeyStore: type[Any] = _missing_dependencies_error  # type: ignore[assignment,no-redef]
     ValkeyCache: type[Any] = _missing_dependencies_error  # type: ignore[assignment,no-redef]
@@ -79,6 +84,7 @@ def _missing_dependencies_error(*args: Any, **kwargs: Any) -> Any:
 __all__ = [
     "AgentCoreMemorySaver",
     "AgentCoreMemoryStore",
+    "AgentCoreValkeySaver",
     "AsyncValkeySaver",
     "AsyncValkeyStore",
     "ValkeyConnectionError",

libs/langgraph-checkpoint-aws/langgraph_checkpoint_aws/agentcore/__init__.py

@@ -1,7 +1,34 @@
+from typing import Any
+
 from langgraph_checkpoint_aws.agentcore.saver import AgentCoreMemorySaver
 from langgraph_checkpoint_aws.agentcore.store import AgentCoreMemoryStore
 
+# Store the import error for later use
+_import_error: ImportError | None = None
+
+# Conditional imports for optional dependencies
+try:
+    from langgraph_checkpoint_aws.agentcore.valkey import AgentCoreValkeySaver
+
+    valkey_available = True
+except ImportError as e:
+    # Store the error for later use
+    _import_error = e
+    valkey_available = False
+
+    # If dependencies are not available, provide helpful error message
+    def _missing_valkey_dependencies_error(*args: Any, **kwargs: Any) -> Any:
+        raise ImportError(
+            "AgentCore Valkey functionality requires optional dependencies. "
+            "Install them with: pip install 'langgraph-checkpoint-aws[valkey]'"
+        ) from _import_error
+
+    # Create placeholder class that raises helpful error
+    AgentCoreValkeySaver: type[Any] = _missing_valkey_dependencies_error  # type: ignore[assignment,no-redef]
+
 __all__ = [
     "AgentCoreMemorySaver",
     "AgentCoreMemoryStore",
+    "AgentCoreValkeySaver",
+    "valkey_available",
 ]