Offloading LangGraph Agent Checkpoints to AIOZ Storage

AIOZ Storage can back part of a LangGraph agent's checkpoint system, the S3 offload tier for large checkpoints specifically, not the whole thing. LangGraph's official AWS checkpoint package, langgraph-checkpoint-aws, is built on DynamoDB as its primary store, with S3 as an optional offload target for anything too big to fit in a DynamoDB item. That distinction matters more than it sounds, because it runs into a real credential-sharing limitation the moment you try to mix real AWS DynamoDB with AIOZ Storage's own credentials. This article covers how the package actually works, exactly where that limitation shows up, and the one setup that gets around it.

TL;DR:

• langgraph-checkpoint-aws's DynamoDBSaver stores checkpoints in DynamoDB, offloading anything 350KB or larger to S3, an optional s3_offload_config with its own endpoint_url field.
• The S3 client shares the exact same session and credentials as the DynamoDB client. You cannot point DynamoDB at real AWS and the S3 offload at AIOZ Storage with one shared credential set, since each needs its own distinct kind.
• The workaround that actually works: run DynamoDB Local (an official AWS tool, meant for development and testing, not production) alongside AIOZ Storage, since DynamoDB Local accepts any credentials without validating them.

How LangGraph Checkpointing Actually Works in This Package

DynamoDBSaver is a DynamoDB-backed checkpoint saver for LangGraph, the official langgraph-checkpoint-aws package's primary offering. Checkpoints under 350KB get written directly into DynamoDB as items. Checkpoints at or above that size get uploaded to a configured S3 bucket instead, with DynamoDB storing only a reference pointer to the S3 object, a pattern AWS's own DynamoDB documentation recommends directly: items are capped at 400KB, and the official guidance for anything larger is to store the payload in S3 and keep a pointer in DynamoDB. The 350KB offload threshold in this package is that exact pattern, with headroom under the hard 400KB ceiling.

from langgraph_checkpoint_aws import DynamoDBSaver

checkpointer = DynamoDBSaver(
    table_name="my-checkpoints",
    region_name="us-west-2",
    s3_offload_config={"bucket_name": "my-checkpoint-bucket"},
)

Where AIOZ Storage Fits, and Where It Doesn't

The S3 side of this package takes a custom endpoint_url inside s3_offload_config, and AIOZ Storage's s3.aiozstorage.network endpoint is a legitimate value there. That's the part that made this look like a straightforward swap. It isn't, once you look at how the constructor actually builds its clients: both the DynamoDB client and the S3 client are created from the same session, region_name, and credentials passed into DynamoDBSaver. There's no separate credential field inside s3_offload_config, only bucket_name and endpoint_url.

That's the real gap. DynamoDB, whether AWS's hosted service or a compatible alternative, needs its own credentials. AIOZ Storage needs its own separate access key and secret, issued through its own dashboard, not an AWS IAM identity. One shared boto3.Session cannot correctly authenticate against both a real AWS account and AIOZ Storage at the same time, because they don't share a credential system. Point the session's credentials at AIOZ Storage, and DynamoDB calls against real AWS fail. Point them at real AWS, and AIOZ Storage rejects the request.

The Setup That Actually Works: DynamoDB Local Plus AIOZ Storage

There is a real way through this, and it comes from a detail in AWS's own DynamoDB Local documentation: DynamoDB Local, the official downloadable version of DynamoDB meant for development and testing, does not validate the credentials you give it. AWS's own docs say plainly that it requires some access key and secret to be present, but they don't have to be valid AWS values. That means you can point the shared session's credentials at your real AIOZ Storage access key and secret, and DynamoDB Local will accept them without complaint, while AIOZ Storage's S3-compatible endpoint validates those same credentials for real, since they're genuinely its own.

import boto3
from langgraph_checkpoint_aws import DynamoDBSaver

session = boto3.Session(
    aws_access_key_id="<your-aioz-storage-access-key-id>",
    aws_secret_access_key="<your-aioz-storage-secret-access-key>",
)

checkpointer = DynamoDBSaver(
    table_name="my-checkpoints",
    session=session,
    region_name="us-east-1",
    endpoint_url="http://localhost:8000",  # DynamoDB Local, ignores credential validity
    s3_offload_config={
        "bucket_name": "my-checkpoint-bucket",
        "endpoint_url": "https://s3.aiozstorage.network",  # validated for real
    },
)

region_name is still required by boto3's client constructor even though neither DynamoDB Local nor AIOZ Storage is region-partitioned, the same placeholder-region pattern covered across every other AIOZ Storage SDK guide on this hub. DynamoDB Local itself runs as a downloadable JAR or a Docker container, documented directly by AWS, and needs to be running and reachable at whatever endpoint_url you configure.

The honest caveat: AWS's own documentation frames DynamoDB Local as a development and testing tool, something you remove in favor of the real DynamoDB web service before going to production, not something AWS positions as a permanent production backend. This pattern is genuinely useful for local development, self-hosted small-scale deployments where you've accepted that tradeoff, or any setup where you already don't want a dependency on AWS's hosted DynamoDB specifically. It is not a drop-in "run this in production exactly as shown" recommendation, and this article won't pretend it is.

Wiring the Checkpointer Into a Graph

Once the checkpointer is constructed, it plugs into LangGraph exactly the way any other checkpointer does, no AIOZ-specific step:

from langgraph.graph import StateGraph

builder = StateGraph(int)
builder.add_node("add_one", lambda x: x + 1)
builder.set_entry_point("add_one")
builder.set_finish_point("add_one")

graph = builder.compile(checkpointer=checkpointer)
config = {"configurable": {"thread_id": "session-1"}}
result = graph.invoke(1, config)

Any checkpoint state under 350KB lands in DynamoDB Local as a plain item. Anything at or above that threshold gets uploaded to the AIOZ Storage bucket automatically, with DynamoDB Local holding the pointer, exactly the same offload logic the package runs against real AWS.

Frequently Asked Questions

Can AIOZ Storage fully replace DynamoDB for LangGraph checkpointing?
No. langgraph-checkpoint-aws's DynamoDBSaver uses DynamoDB as its primary store for all checkpoints under 350KB. AIOZ Storage can only serve the S3 offload tier for checkpoints at or above that size, not the primary index.

Why can't I just point DynamoDB at AWS and the S3 offload at AIOZ Storage?
Both clients are built from the same boto3 session and credentials inside DynamoDBSaver, with no separate credential field for the S3 side. Real AWS IAM credentials and AIOZ Storage's own access key and secret aren't interchangeable, so one shared session can't authenticate correctly against both.

What size checkpoint actually triggers the S3 offload?
350KB or larger, per the package's documentation, comfortably under DynamoDB's hard 400KB item size limit.

Is running DynamoDB Local for production a good idea?
AWS's own documentation frames DynamoDB Local as a development and testing tool, meant to be swapped for the real DynamoDB web service before production. Treat the pattern in this article as a real, working setup for development or a self-hosted deployment you've deliberately chosen, not a general production recommendation.

Does the region_name parameter matter for AIOZ Storage or DynamoDB Local?
Not functionally, since neither service is region-partitioned, but boto3's client constructor requires some value to be present regardless.

Where do I get AIOZ Storage credentials for the S3 offload config?
The same S3 Access Key ID and Secret Access Key used across every other AIOZ Storage SDK integration, generated as an access grant through the dashboard, covered in AIOZ Storage Access Control.

Related Reading

• AIOZ Storage for AI and Data Pipelines: What's Actually Documented Today - the hub this article is part of, including the original, less-detailed version of this claim.
• Using AIOZ Storage as a Dataset and Model-Output Backend - the honest can/can't framing this article's credential-gap finding continues.
• AIOZ Storage Access Control: Macaroons and Access Grants - generating the access key and secret this setup authenticates with.
• File Management API with FastAPI, Boto3, and AIOZ Storage - the same boto3 client patterns this article builds on.

References

• langgraph-checkpoint-aws on PyPI
• langchain-aws GitHub Repository: langgraph-checkpoint-aws Source
• AWS DynamoDB Documentation: Best Practices for Storing Large Items and Attributes
• AWS DynamoDB Documentation: Setting Up DynamoDB Local