2.6

Checkpoint size, DeltaChannel, and the cost of a superstep

The framework took under half a percent of a real agent's time, while its checkpoints grew to 10 MB in 100 tool calls, so spend your effort on bytes.

Your agent reads a long document page by page, 100 tool calls on one thread. The messages of the whole conversation are about 110 KB. The SQLite file holds 10.1 MB for that one thread. Nobody wrote 10 MB of anything. The saver wrote the conversation again on every superstep.

When you finish this section, you can predict the size of a thread from its step count and its saver. You can also choose between a plain message channel and DeltaChannel, and say what the loop itself costs next to the model.

Every checkpoint holds the whole list

SqliteSaver.put serializes the whole checkpoint, with every channel value, into one row. It receives new_versions, the list of channels that changed, and does not use it.

InMemorySaver.put does use it. It stores one blob per changed channel, keyed by the channel and its version. That saves the channels that did not change. In an agent, messages changes on every superstep, so each new blob is the whole list again.

A thread of n supersteps with one message each stores 1, 2, 3, up to n messages. That sum grows with n squared.

We measured one create_agent run per saver on the x86 server guest with Qwen3 4B and a context of 16,384 tokens. The tool read_page returns a page that names the cursor of the next page, so the model must make one call per turn. Each run made 100 tool round trips, 101 model calls, and 203 supersteps, and ended with DONE. The model took almost all of the time in each run. We do not use the times, because each saver ran once on a loaded guest: Raw runs

outputcheckpoint size over 100 real tool round tripsFull log
   checkpoint rows=203 total bytes=10132489; row bytes at #1, #50, #100, #150, #200: [689, 25072, 49512, 74045, 98637]; largest 99390; mean 49914
   writes rows=403 bytes=111623 (messages channel 98824); checkpoints + writes = 10244112 bytes; checkpoints / writes = 90.8
…
   InMemorySaver: 203 checkpoints (118969 bytes without channel values); blobs 606 entries, 10002635 bytes, of which messages 9989570 bytes in 202 versions; messages blob at version #1, #50, #100: [861, 24630, 49074], last 98779; writes 111624 bytes
The SqliteSaver and InMemorySaver blocks, cut to the size lines.

The row grew from 689 bytes to 98,637 bytes. The 203 rows held 10,132,489 bytes, and the writes table, which holds each message once, held 111,623. So the checkpoints held 90.8 times the bytes of the writes. The blobs of InMemorySaver held 10,002,635 bytes, and the messages channel was 9,989,570 of them.

DeltaChannel stores the writes

DeltaChannel: a beta channel type that saves only the writes of each superstep, and a full snapshot after a set number of updates. Section 5.5 measures it over 5,000 steps.

A DeltaChannel checkpoint holds no value between snapshots. A snapshot comes every snapshot_frequency updates, 100 by default, or after 5,000 supersteps. A read rebuilds the list from the last snapshot and the writes after it.

create_agent keeps messages in a BinaryOperatorAggregate. Its state_schema argument takes a subclass of AgentState, and the third run used one that swaps the channel:

pythoncreate_agent with a DeltaChannel message listFull log
class DState(AgentState):
    messages: Annotated[list, DeltaChannel(_messages_delta_reducer)]
…
    kw = {"state_schema": DState} if label == "sqlite-delta" else {}
outputthe same 100 round trips with DeltaChannelFull log
   checkpoint rows=203 total bytes=286606; row bytes at #1, #50, #100, #150, #200: [470, 747, 49515, 750, 98638]; largest 98638; mean 1412
   writes rows=403 bytes=111777 (messages channel 98978); checkpoints + writes = 398383 bytes; checkpoints / writes = 2.6
   get_state at the end, 30 reads after 3 warmups: median 2.76 ms (p10 2.75, p90 2.8); 202 messages
The sqlite-delta block, cut to the size and read lines.

The run did the same work: 100 round trips, 101 model calls, and the same last answer. The thread held 398,383 bytes against 10,244,112, about one twenty-sixth. The rows stayed near 750 bytes, except the two snapshots at rows 100 and 200. We read the thread 30 times at the end of each run, and we do not use those times. Figure 2.9 plots every row of both runs.

Fig. 2.9bytes of each checkpoint row, plain messages against DeltaChannelchart
Bytes of each checkpoint row, plain messages against DeltaChannel Bytes of every row of the SqliteSaver checkpoints table, in order, for one create_agent run of 100 real tool round trips with Qwen3 4B on the x86 server guest, once with the plain add_messages channel and once with a state_schema whose messages use DeltaChannel. Each dot is one row, 203 rows per run. The plain rows grow in a straight line from 689 to 99390 bytes, 10132489 bytes in all. The DeltaChannel rows stay near 643 bytes, except 2 snapshot rows at positions 100 and 200 of 49515 and 98638 bytes, 286606 bytes in all. With the writes table, the plain thread holds 25.7 times the bytes of the DeltaChannel thread. 0 KB 20 KB 40 KB 60 KB 80 KB 100 KB 0 50 100 150 200 checkpoint row, in order bytes of the row plain messages 10.13 MB in all DeltaChannel 0.29 MB in all DeltaChannel snapshot rows one per 100 updates whole thread with writes: 10.24 MB plain, 0.40 MB DeltaChannel, 25.7 times less
Plain rows hold the whole list and grow to 99 KB, and DeltaChannel rows stay near 750 bytes except one snapshot per 100 updates. Each dot is one row of the checkpoints table of one create_agent run of 100 real tool round trips, in order, 203 rows per run. Teal is the plain channel, indigo is DeltaChannel, and the two rings are its snapshot rows.

The reducer _messages_delta_reducer has a private name, and the channel is beta. Section 5.5 lists the rules for changing the channel of a thread that already exists.

What one superstep costs

We measured the time of each part of a run on the x86 server guest with Qwen3 4B. Each run was one create_agent run of 10 tool round trips, 22 supersteps, 30 runs per cell after 2 warmups. The framework time is the wall time minus the time inside the Ollama call and inside the tool function: Raw runs

Saver and modeshare of wall
none, async0.144 %
InMemorySaver, async0.197 %
InMemorySaver, sync0.213 %
InMemorySaver, exit0.153 %
SqliteSaver, async0.245 %
SqliteSaver, sync0.449 %
SqliteSaver, exit0.190 %

The guest was loaded, so read the share and the order of the rows, not the milliseconds.

The model filled more than 99.5 percent of each run. The loop functions themselves, planning, applying, and checkpointing, were a small part of the framework time. Figure 2.10 stacks the parts.

Fig. 2.10framework time per superstep, by saver and durability modechart
Framework time per superstep, by saver and durability mode Seven horizontal bars, one per saver and durability mode, for one create_agent run of 10 tool round trips with Qwen3 4B on the x86 server guest, 22 supersteps, 30 runs per row, medians. The guest was loaded, so read the share and the order of the bars, not the milliseconds. The framework time is the wall time minus the time inside the Ollama call and the tool function. Each bar gives milliseconds per superstep: no saver async 1.70, InMemorySaver async 2.33, InMemorySaver sync 2.51, InMemorySaver exit 1.79, SqliteSaver async 2.89, SqliteSaver sync 5.31, SqliteSaver exit 2.24. The indigo part is the loop functions: planning, applying, building the checkpoint, and recording task writes. The grey part is the rest: node wrappers and the saver work that the loop waits for. The right column is the framework share of the wall time, 0.144 to 0.449 percent, in runs of about 25.9 s that the model filled. SAVER, MODE framework ms per superstep SHARE of wall 0 ms 2 ms 4 ms 6 ms no saver async 1.70 ms 0.144 % InMemorySaver async 2.33 ms 0.197 % InMemorySaver sync 2.51 ms 0.213 % InMemorySaver exit 1.79 ms 0.153 % SqliteSaver async 2.89 ms 0.245 % SqliteSaver sync 5.31 ms 0.449 % SqliteSaver exit 2.24 ms 0.190 % loop: plan, apply, checkpoint, task writes rest: node wrappers, saver waits on the loop the model filled the other 99.55 percent or more of each 25.9 s run
LangGraph and LangChain took 0.14 to 0.45 percent of the wall time, and a sync SqliteSaver cost the most. Each bar is one saver and mode, in milliseconds per superstep, medians of 30 runs of 22 supersteps. Indigo is the loop functions, and grey is the rest of the framework time: node wrappers and saver waits on the loop. The right column is the share of the wall time. The guest was loaded, so read the share and the order of the bars, not the milliseconds.

So the loop is not where an agent spends its time. The cost that grows is the checkpoint bytes, and on a database with many threads those bytes are storage, I/O, and backup.

What to do

Estimate the bytes of a thread as the bytes of one message, times supersteps squared, divided by two. That gave 9.98 MB for the run above, against 10.13 MB measured. When that number passes what your database should hold per thread, trim or summarize the messages, as section 5.5 shows. Or pass create_agent a state_schema with a DeltaChannel message list, and accept a beta channel.

Do not tune the loop first. Pick durability for correctness, as section 2.3 argues. The most costly setup in our runs, sync on SQLite, took 0.449 % of the wall time.

LangChain (Python): langchain, langchain-core, langgraph, deepagents, langsmith 1.5.0 · c2f4036 · 2026-11-11 · Edition 2026.11