Agent state management is the handling of the information an agent needs across steps, turns, sessions, or workflows. State can include task progress, retrieved context, tool outputs, intermediate decisions, and external system IDs. Managing it means deciding what gets recorded, where it lives, when it is written, and what the model is shown from it on the next step.
This needs a name because the model does not have state. Each call is independent, so whatever coherence an agent shows across twelve tool calls is something your code maintained and re-presented. When an agent forgets a constraint from four steps ago, that is almost never a model failure. It is state that was never written, or state that was written and never surfaced back into the prompt.
Key takeaways
- State is the execution record for the current run. Context is the subset you put in front of the model on a given call. Memory is what survives after the run ends.
- Anything the agent will need later has to be written somewhere your code controls, because the message history is a lossy and expensive place to keep facts.
- State outgrows the context window on any long run, so the design question is what to summarize, what to drop, and what to keep addressable by reference.
- Parallel subagents writing to shared state produce lost updates exactly as any distributed system does, and this is the failure mode teams underestimate.
- The gap between what the state record says and what the model believes is a diagnosable bug class, visible only by inspecting both at each step.
State, context, and memory are three different things
The three terms get used interchangeably and they refer to different objects.
Context is what the model sees in one call. It is bounded by the context window and assembled fresh every step. Context is a view, not a store.
State is the record your system maintains for the current run: which steps are done, what each tool returned, the plan, retry counters, budget consumed, and the identifiers the agent has created. It outlives any single model call and ends with the run.
Memory is knowledge that persists across runs, such as a user preference learned last week. Memory has separate storage and separate retrieval, and agentic memory has its own entry in this glossary. The practical boundary: if the information is only meaningful inside this execution, it is state. If a future run should be able to find it, it is memory.
The flow runs one way. State is derived into context. Some state is promoted into memory when the run ends. Memory is retrieved back into context on a later run. Conflating them produces the classic bug where an agent treats a stale fact from a previous session as current execution state.
What belongs in state
At minimum, a production agent tracks:
- Task and plan state. The goal, the current step, and which planned steps are done, pending, or failed.
- Tool results. What each call returned and the arguments it was called with, so a repeat call can be recognized.
- Retrieved context. Preferably stable references rather than the documents themselves, so state does not balloon.
- External identifiers. The ticket number, the order ID, the file the agent created. These cannot be regenerated.
- Control counters. Steps taken, tokens spent, consecutive errors, elapsed time. The control loop reads these to decide whether to continue.
- Pending obligations. An approval the run is waiting on, or a callback it expects.
Anything on that list that exists only inside the message history is at risk. Histories get truncated and summarized, and the summarizer does not know the order ID mattered.
Where state lives
Three shapes cover most implementations, trading durability against simplicity.
In-process. A structured object held in memory for the run. Fast, trivial to write, and gone when the process restarts. Fine for a run that completes in seconds.
Externally persisted. A record in a database or key-value store keyed by a run or thread identifier, written after each step. It survives restarts and lets a different worker pick the run back up, at the cost of a write per step and a requirement that state be serializable, which rules out holding open connections or callbacks in it.
Append-only event log. Append each event and derive current state by folding over the log. More storage and costlier reads, but you get the full history of how the run reached its position, which is worth a lot when debugging, and it is the substrate that makes replay-based recovery possible.
For any agent that runs longer than a request timeout, externalized state is not optional, and the design question becomes durable execution: how the run resumes without redoing completed work.
How state management fails
Unbounded growth. Every tool result gets appended, context assembly includes all of it, and by step 30 you are paying to re-send stale search output. Compaction is the standard response: summarize older turns, keep recent ones verbatim, hold large artifacts behind references. The tradeoffs of managing context in a running agent are their own design problem, and no compaction scheme is lossless.
Silent staleness. State was correct when written and the world moved. A cached balance, an expired auth token, a document someone edited. Long runs make this routine. Timestamp what you cache and re-read the things that change.
Lost updates under concurrency. Two subagents read the same state, each modifies its own copy, and the second write erases the first. This is an ordinary distributed systems problem with ordinary answers: partition writes per agent, use append-only events instead of overwrites, or take an explicit lock.
Model and state disagreement. The state record says step 3 failed. The model, reading a summarized history, believes it succeeded and plans accordingly, and every later decision inherits the error. An agent observability setup that records the assembled context alongside the state snapshot at each step shows where the two diverged instead of leaving you to guess from the final output.
FAQ
What is the difference between agent state and agent memory?
State is scoped to the current run and describes execution: what has happened and what is pending. Memory is scoped across runs and describes knowledge worth keeping after the task ends. A run’s step counter is state. A user’s stated preference for concise answers is memory. Different lifetimes, different stores, different retrieval. Systems that organize memory into tiers still keep the current run’s execution record separate from long-lived knowledge.
How do you manage state in a complex multi-agent system?
Give each agent its own state and keep the shared surface explicit and small. A supervisor holds task-level state and passes each subagent a scoped input plus a scoped place to write results. Shared mutable state touched by several agents at once is where these systems break, so treat handoffs as messages with defined schemas.
What happens when state grows larger than the context window?
The state is fine, since it lives outside the window. What breaks is the projection into context. The usual approach is a mix: keep recent steps verbatim, replace older ones with a summary, and expose large artifacts as references the agent can pull back in on demand. Expect to lose fidelity, and validate that critical identifiers survive summarization.
Do I need a database for agent state?
Not for short runs that finish inside a single request. You need one as soon as a run can outlive the process, span multiple workers, pause for approval, or need resuming after a crash. The moment you ask what happens if this pod restarts mid-run, you have your answer.
