Agent state is the complete, structured record of everything an AI agent needs to continue its work at the next step: the goal, the conversation and tool history, intermediate results, plans, counters and the current status of the task. In AI agents, a core area of artificial intelligence, state is what turns a single stateless model call into a multi-step process that can pause, resume, branch and recover.
The underlying language model is stateless between calls: it remembers nothing unless the relevant information is placed in its input again. Agent state therefore lives outside the model, in the agent harness or framework, which decides what is stored, what is shown to the model on each turn and what is persisted for later.
What agent state contains
Agent state contains every piece of information that influences the next decision of the agent. In practice, frameworks organize it as a typed object or dictionary that the agent loop reads at the start of each step and updates at the end.
The components below appear in most production designs, although their names differ between frameworks.
| Component | Content | Purpose |
|---|---|---|
| Task specification | Goal, constraints, success criteria | Keeps the agent aligned with the request |
| Message history | User turns, model outputs, tool calls and results | Provides context for the next model call |
| Plan | Ordered or hierarchical list of subtasks | Tracks progress and remaining work |
| Working data | Retrieved documents, variables, file paths, partial outputs | Carries results between steps |
| Control fields | Step count, token budget, retries, status flags | Enforces limits and termination |
| Environment references | Session IDs, sandbox handles, open browser tabs | Links the agent to external resources |
A useful distinction separates explicit state, stored in structured fields the program can inspect, from implicit state, which exists only inside the message history. Implicit state is convenient but hard to validate, query or recover after a failure.
How state flows through the agent loop
State flows through the agent loop as a read, decide, act and update cycle. At each iteration, the harness assembles a model input from the current state, the model proposes an action, the harness executes it and writes the observation and any changes back into state.
Graph-based orchestration frameworks make this explicit: each node is a function that receives the state and returns an update, and reducers define how updates merge, for example appending new messages rather than overwriting them. This design makes state transitions deterministic and testable, even though the model decisions inside them are not.
Because the context window is finite, the harness also performs context selection. Long histories are trimmed, summarized through context compaction, or moved to an external store, so that the state the model sees on each turn is a curated projection of the full state rather than all of it.
Agent state compared with related concepts
Agent state is often confused with agent memory, the scratchpad and the context window, but these terms describe different scopes and lifetimes. The comparison below clarifies the boundaries.
| Concept | Scope | Lifetime | Main role |
|---|---|---|---|
| Agent state | One task or session | Until the task ends or is archived | Drives the next step |
| Agent memory | Across tasks and sessions | Days to indefinite | Recalls facts and preferences |
| Agent scratchpad | Reasoning within a task | Usually one task | Holds intermediate thoughts |
| Context window | One model call | A single request | What the model actually reads |
| Checkpoint | Snapshot of state | Until deleted | Enables resume and replay |
In short, state is the source of truth, the context window is a view of it, memory is long-term knowledge that may be loaded into it, and a checkpoint is a frozen copy of it at a given step.
Persisting and checkpointing state
Persisting agent state means saving it to durable storage after each step, so that a long-running or background agent survives crashes, deployments and waits for human approval. Agent checkpointing stores these snapshots with a thread or run identifier.
Persistence enables several capabilities that are otherwise impossible: human-in-the-loop interruption, where execution pauses until a reviewer approves an action; time travel, where a developer replays or forks a run from an earlier step; and fault tolerance, where a failed tool call is retried without repeating completed work.
The storage choice depends on scale and durability needs, as the table shows.
| Storage option | Typical use | Trade-off |
|---|---|---|
| In-process memory | Prototypes, short interactive runs | Lost on restart |
| Key-value store | Fast resume of many concurrent sessions | Limited querying |
| Relational database | Auditable production workflows | Schema management effort |
| Object storage | Large artifacts and full transcripts | Higher latency |
| Event log | Replay, auditing, compliance | Requires state reconstruction |
Design risks and common mistakes
Poorly designed agent state is a leading cause of unreliable agents, because errors in state silently compound over many steps. The table lists frequent symptoms and their remedies.
| Symptom | Likely cause | Fix |
|---|---|---|
| Agent repeats finished steps | Progress kept only in message text | Store an explicit plan with status fields |
| Quality drops in long runs | Unbounded history fills the context | Summarize or offload older history |
| Resumed run behaves differently | State depends on in-memory objects | Serialize all state needed to continue |
| Subagents overwrite each other | Shared mutable state without merge rules | Use reducers or isolated substates |
| Sensitive data leaks into logs | Credentials stored in state | Keep secrets in a vault, store references only |
A further risk is state poisoning: content injected through a tool result, such as a malicious web page, can enter state and influence later steps. Treating tool outputs as untrusted data, validating structured fields and limiting what is persisted reduce that exposure.
The idea in brief
Agent state is the notebook an AI agent keeps while it works. The AI model itself forgets everything between steps, so the surrounding software writes down what the goal is, what has been done, what was found and what comes next.
Imagine a contractor renovating a kitchen over several days. Each morning, the contractor checks the job sheet to see which tasks are finished and which materials have arrived. Without that sheet, the work would start from scratch every day. Agent state is that job sheet, and keeping it accurate is what lets an agent finish long tasks reliably.
A practical scenario
A finance team uses an agent to reconcile about 1,200 monthly vendor invoices against purchase orders. The task takes several hours and includes a pause whenever an invoice differs from its order by more than 2 percent, at which point a human accountant must approve or reject the discrepancy.
The agent state holds the list of invoices with a status field for each, the running totals, the IDs of flagged items and a pointer to the current batch. After every batch of 50 invoices, the harness writes a checkpoint to a database. When the agent reaches a flagged invoice, it records the question in state and stops.
One afternoon, the server restarts while 14 approvals are pending. Because the state was persisted, the agent resumes at invoice 731 the next morning, applies the accountant decisions and finishes the run. No invoice is processed twice and none is skipped, which is exactly what the audit requires.