{"id":8264,"library":"langgraph-checkpoint-aws","title":"LangGraph AWS Checkpoint","description":"The `langgraph-checkpoint-aws` library provides a LangGraph checkpointer implementation that leverages AWS Bedrock Session Management Service (SMS) for session storage and AWS ElastiCache Valkey (Redis) for state management. It enables stateful and resumable LangGraph agents, allowing them to persist and retrieve their execution state across invocations. The current version is 1.0.7, and its release cadence is tied to the LangChain ecosystem, implying active development and frequent updates.","status":"active","version":"1.0.7","language":"en","source_language":"en","source_url":"https://github.com/langchain-ai/langchain-aws/tree/main/libs/langgraph-checkpoint-aws","tags":["langchain","langgraph","aws","checkpoint","state","redis","valkey","bedrock","dynamodb"],"install":[{"cmd":"pip install langgraph-checkpoint-aws","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides core AWS integrations for LangChain/LangGraph.","package":"langchain-aws"},{"reason":"Official AWS SDK for Python, used for interacting with AWS services like DynamoDB (via Bedrock SMS).","package":"boto3"},{"reason":"Python client for Redis, used for Valkey (Redis-compatible) state management.","package":"redis"},{"reason":"Python client for Valkey, also used for Valkey (Redis-compatible) state management.","package":"valkey-py"}],"imports":[{"symbol":"AWSSessionManagerValkeySaver","correct":"from langgraph_checkpoint_aws import AWSSessionManagerValkeySaver"}],"quickstart":{"code":"import os\nimport redis\nimport boto3\nfrom langgraph.graph import StateGraph, START\nfrom langgraph.checkpoint.base import Checkpoint\nfrom langgraph_checkpoint_aws import AWSSessionManagerValkeySaver\n\n# 1. Setup AWS client (ensure AWS credentials are configured, e.g., via ~/.aws/credentials or env vars)\n#    The Checkpointer primarily uses DynamoDB via Bedrock Session Management Service.\naws_region = os.environ.get(\"AWS_REGION\", \"us-east-1\")\nboto3_session = boto3.Session(region_name=aws_region)\n\n# 2. Setup Valkey/Redis client\n#    Ensure a Redis/Valkey instance is running and accessible (e.g., local or ElastiCache)\nredis_url = os.environ.get(\"REDIS_URL\", \"redis://localhost:6379/0\")\ntry:\n    redis_client = redis.from_url(redis_url)\n    redis_client.ping() # Test connection\nexcept redis.exceptions.ConnectionError:\n    print(f\"WARNING: Could not connect to Redis at {redis_url}. Please ensure a Redis/Valkey instance is running.\")\n    redis_client = None # Mark as failed\n\n# 3. Define a simple LangGraph state\nclass AgentState(dict):\n    \"\"\"A dictionary-like state for the graph.\"\"\"\n    pass\n\n# 4. Instantiate the AWSSessionManagerValkeySaver\n#    'application_id' is used to partition state within Bedrock SMS/DynamoDB.\napplication_id = os.environ.get(\"AWS_APPLICATION_ID\", \"my_langgraph_app_dev\")\n\nif redis_client:\n    checkpointer = AWSSessionManagerValkeySaver(\n        boto3_session=boto3_session,\n        redis_client=redis_client,\n        application_id=application_id\n        # Optional: You can specify a custom DynamoDB table name if not using the default Bedrock SMS table.\n        # table_name=\"MyCustomLangGraphCheckpoints\"\n    )\n\n    # 5. Build a simple LangGraph with the checkpointer\n    graph_builder = StateGraph(AgentState)\n    graph_builder.add_node(\"start_node\", lambda state: {\"message\": \"Hello from LangGraph!\"})\n    graph_builder.set_entry_point(\"start_node\")\n    graph_builder.set_finish_point(\"start_node\")\n\n    # Compile the graph with the checkpointer\n    app = graph_builder.compile(checkpointer=checkpointer)\n\n    # 6. Run the graph with a configurable thread_id for checkpointing\n    thread_id = \"unique_session_123\"\n    config = {\"configurable\": {\"thread_id\": thread_id}}\n\n    print(f\"Running LangGraph with checkpointer for thread_id: {thread_id}\")\n    # The first run will create a checkpoint\n    result = app.invoke({}, config=config)\n    print(f\"First run output: {result}\")\n\n    # Subsequent runs with the same thread_id will load the checkpoint\n    # (in a more complex graph, state would be loaded and updated)\n    result_again = app.invoke({}, config=config)\n    print(f\"Second run output (should be same for this simple graph): {result_again}\")\n\n    print(\"\\nSuccessfully configured AWSSessionManagerValkeySaver and ran a simple graph.\")\n    print(\"Check your AWS Bedrock Session Manager (DynamoDB) and Valkey/Redis instance for stored state.\")\nelse:\n    print(\"Checkpointer instantiation skipped due to Redis connection failure.\")\n    print(\"Please ensure REDIS_URL and AWS credentials are correctly configured.\")","lang":"python","description":"This quickstart demonstrates how to initialize `AWSSessionManagerValkeySaver` and integrate it with a basic LangGraph `StateGraph`. It requires AWS credentials configured in your environment (e.g., via `~/.aws/credentials` or environment variables) and a running Redis/Valkey instance accessible via `REDIS_URL`. The example simulates two runs to show how `thread_id` is used with the checkpointer to persist and retrieve state."},"warnings":[{"fix":"Configure AWS credentials (e.g., `~/.aws/credentials`, environment variables like `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) and ensure the IAM role/user has appropriate permissions for DynamoDB actions on the Bedrock Session Manager table or a custom table if specified.","message":"Ensure AWS credentials and necessary IAM permissions are configured for your environment. The checkpointer interacts with AWS DynamoDB (via Bedrock Session Management Service) and potentially other AWS services. Missing permissions (e.g., `dynamodb:PutItem`, `dynamodb:GetItem`, `dynamodb:UpdateItem`) will lead to `AccessDeniedException` errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Verify the `redis_client` connection parameters (host, port, password, URL) passed to `AWSSessionManagerValkeySaver`. Ensure the Redis/Valkey server is running and network accessible from where your application is executing. Use `redis.from_url` with a full URL like `redis://user:password@host:port/db`.","message":"The checkpointer requires a running and accessible Redis or Valkey instance. Connection errors (`redis.exceptions.ConnectionError`) are common if the host, port, or password are incorrect, or if the instance is not running or is behind a firewall.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consistently use the same `application_id` across all instances of your LangGraph application that should share the same state. Consider using environment variables or a configuration file to manage this value.","message":"The `application_id` parameter for `AWSSessionManagerValkeySaver` is crucial for partitioning state within Bedrock Session Management Service (DynamoDB). Using different `application_id` values will result in separate state storage for the same `thread_id`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Start your Redis/Valkey server. Verify the `REDIS_URL` environment variable or the host/port in your `redis.from_url()` call is correct and that no firewall is blocking the connection.","cause":"The Redis/Valkey server is not running or is not accessible at the specified host and port.","error":"redis.exceptions.ConnectionError: Error 111 connecting to localhost:6379. Connection refused."},{"fix":"Grant the IAM user or role associated with your application `dynamodb:PutItem`, `dynamodb:GetItem`, and `dynamodb:UpdateItem` permissions on the target DynamoDB table. Ensure `AWS_REGION` is also correctly configured.","cause":"The AWS credentials used by your application lack the necessary IAM permissions to interact with the DynamoDB table used by Bedrock Session Management Service (or a custom table you specified).","error":"botocore.exceptions.ClientError: An error occurred (AccessDeniedException) when calling the PutItem operation: User: arn:aws:iam::123456789012:user/myuser is not authorized to perform: dynamodb:PutItem on resource: arn:aws:dynamodb:us-east-1:123456789012:table/BedrockSessionManager"},{"fix":"Ensure your `config` dictionary passed to `graph.invoke()` includes `{'configurable': {'thread_id': 'your_unique_thread_id'}}`.","cause":"When a checkpointer is enabled, LangGraph requires a `thread_id` to be provided in the `config` object during `invoke()` or `stream()` calls to manage the state of a specific conversational thread.","error":"ValueError: Must specify a 'thread_id' in the config under ['configurable'] when using a checkpointer."}]}