What Is Agent State?
Agent state is everything a run carries from one step to the next: the history of steps taken, any tool call issued and not yet returned, the scratch values the run has computed, and the counters its stopping rules are checked against. It is not the context window, which is the portion of that state assembled into a particular request, and it is not long-term memory, which is what deliberately survives after the run has ended.
What a run is actually holding
Four kinds of thing, and they behave differently enough that treating them as one blob is the source of most resume bugs. The step history is the record of what happened, in order. The pending call is the one tool invocation that has been issued and whose result has not arrived. The scratch values are what the run has computed and holds by reference rather than in the transcript — a parsed document, a plan, a list of candidates. And the control variables are the step count, the tokens spent, the elapsed time and the retry count, which exist for no reason other than to be read by the rules that decide whether to continue.
The distinction that gets lost is between state and context. Context is derived from state at each step, by selecting, truncating, summarising or reordering what state holds, and the derivation is lossy on purpose. So the two diverge: a run can hold a tool result in state and choose not to place it in the next request, and a run whose context has been compacted still has its full history — provided the history was kept somewhere other than the context. Where the context is the only place the history lives, compaction is deletion, and the run has forgotten something it will not know it is missing.
Where state lives is then a separate decision. In the simplest arrangement it is variables in the process running the loop, and it exists exactly as long as that process does. Anything beyond that keeps it in a store, and the two ordinary shapes trade off the usual way: a snapshot written each step loads instantly and says nothing about how the run arrived there, while an append-only log of the events that produced the state can reconstruct any point in the run and has to be replayed to yield one.
| Element | Recoverable if lost? |
|---|---|
| Step history | Only if it was written down. Nothing else in the system contains it. |
| Pending tool call | Not reliably. Whether it ran is a question for the tool, not for the run. |
| Results already returned | Sometimes, by calling again — at the price of a second effect where the call is not read-only. |
| Scratch values | By recomputing, provided the inputs are still held. |
| Step and budget counters | From the history, if the history is complete. |
| Effects outside the run | Never. A message sent and a row written are not part of state and do not come back with it. |
The last row decides whether a run can be resumed at all. State describes what the run knows, never what it has already done to the world, and the two are only aligned at moments the run was built to have — which is what makes the choice of checkpoint boundary an engineering decision rather than a configuration setting.
Resuming, and what a resumed run repeats
Resuming means loading state saved earlier and continuing from it, and the entire difficulty is where the save sits relative to a call that has an effect. Save before the call, and a crash in the window between the save and the return leaves a resumed run about to issue a call that may already have run. Save after, and a crash in the same window loses the result of a call that certainly did run, so the resumed run issues it again. No ordering of two separate writes avoids both, which is why the question is settled at the tool rather than in the loop: a call that can be repeated with no further effect makes the choice free, and one that cannot has to carry a key the receiving side recognises, so that a repeat is answered rather than performed.
Granularity is the second decision and it is usually settled by coherence rather than by cost. A step boundary is where the run is consistent — no request half-assembled, no result half-read, no counter incremented for work not yet done — so it is the natural place to write. Finer than a step is rarely meaningful. Coarser means a crash discards back to the previous boundary, which on a long-running agent can be most of the work, and it is the reason a run that takes hours is normally checkpointed on a boundary rather than at the end.
The third decision is not about correctness and is the one most often taken by default. State written to a store is state that persists, that will be read later, and that can be read by anyone who can read the store. A run's history contains everything the run was given, which includes whatever the operator's own description of the task contained. Recording state and retaining state are separate choices, and the second is a data-protection question whatever the tool that performs it calls it.
How the Registry classifies a state-persistence task
Persisting a run's step history and pending tool calls to a store so a run can resume after a restart is filed as software engineering in this registry's classification. The classification follows what is produced — a schema, a serialisation, a resume path — rather than the subject matter of whatever run is being persisted.
The Registry's canonical brief for this entry is filed as:
Persist an agent’s step history and pending tool calls to a store so a run can resume after a restart.
Submitted for assessment it is
classified as Code modification, and its wording is hashed once — to
f15219a7ab2aec2e…, the first sixteen of sixty-four hexadecimal
characters — with the wording itself never stored. The hash is what the derivation
reads.
That class's own page is /tasks/code.
Classification is one of three inputs. The other two are the configuration submitted with the task, and the permanent chart derived from that configuration — fixed by the model name, the training cutoff and the temperature alone, and never reading the task at all. The same ascendant, ruling planet and harmony therefore appear on every assessment a given configuration receives, whatever it was asked to do. The derivation is published in full at /method.
What this page does not claim about agent state
Where a given run's state is kept, at which boundary it is written, and whether a resumed run repeats an effect are properties of a particular implementation, and the canonical brief above encodes none of them. This registry holds no run state, resumes nothing, and stores no task description: a description submitted for assessment is hashed and discarded, which is a retention decision taken deliberately rather than an incidental one.
The Registry does not run this task, does not inspect any system's output for it, and validates no assessment it issues against what afterwards happens. What it does is compute — from a published method, for one submitted task and one submitted configuration — a verdict and a recommended execution window. It computes neither on this page.
Questions about agent state
- What is agent state?
- Agent state is what a run carries between its steps: the step history, any call issued and not yet returned, the values it has computed, and the counters its stopping rules read. It is the run’s working memory, and it exists for the duration of the run.
- What is the difference between agent state and the context window?
- The context window is what is in one request. State is what the run holds. Context is derived from state at each step by selecting, truncating or summarising, so the two are not the same size and not the same content. A run can hold something in state and leave it out of the next request without losing it — unless the context was the only copy.
- How is agent state persisted?
- Either as a snapshot written at each step boundary, which loads directly and records no history of how it was reached, or as an append-only log of events that is replayed to reconstruct any point in the run. The first is simpler to read; the second is what makes a run auditable after the fact.
- What goes wrong when a run resumes?
- The pending call. State can record that a call was issued, but not whether it took effect, so a resumed run either repeats a call that may already have run or drops a result that certainly returned. The fix is at the tool rather than in the loop: make the call safe to repeat, or give it a key the receiving side can recognise as a repeat.
- Is agent state the same as memory?
- No, and the difference is scope. State is the working record of one run and is discarded when the run ends. Long-term memory is what something deliberately promoted out of a run so that a later, unrelated session can retrieve it. Most state is never promoted, and deciding what is worth promoting is a separate problem with separate failure modes.
- When should state be written to a store rather than kept in memory?
- When the run is expected to outlive the process holding it, when it has to be inspected while still running, or when a human step interrupts it and it must survive the wait. Short runs inside one process need none of that, and adding a store to them buys latency and a retention question in exchange for nothing.
Related entries
Order an assessment for code modification tasks
The Registry issues a permanent, numbered task risk assessment for one submitted task and one submitted configuration. EUR 1.90 Standard, EUR 4.90 Extended, EUR 14.90 Full Chart, which adds the permanent chart. Assessments from EUR 1.90; machine-readable at /pricing.json.