AI Agent State Management: Keeping Runs Legible From Start to Finish
How to model AI agent run state across queues, tools, checkpoints, approvals, side effects, validation, handoff, and recovery.

An AI agent run can look like a conversation, but operationally it is a stateful process. It begins with an assignment, enters a queue, gathers context, calls tools, waits for responses, produces intermediate artifacts, asks for approval, changes or declines to change external systems, validates the result, and hands off evidence. If the workflow treats all of that as a stream of messages, the human may see activity without understanding where the work actually stands.
State management is the discipline of naming and preserving the run’s condition as it moves from request to result. It answers ordinary but important questions. Has the task started? What is the agent waiting on? Which sources have already been inspected? Which tools have changed external state? Which approval applies to which action? Is the output a draft, a verified artifact, or accepted work? Can the run be resumed safely after interruption? Without state, every answer has to be reconstructed from a transcript.
This topic connects to AI Agent Checkpoints , AI Agent Observability , and AI Agent Control Surfaces . Checkpoints preserve a moment in the work. Observability records what happened. Control surfaces show the human what matters. State management is the model underneath them: the run’s current position, allowed transitions, and evidence that each transition is legitimate.
Running is not one state
Many systems begin with a simple status field: queued, running, done, failed. That is enough for a background job that either computes a result or does not. It is too thin for delegated work. An agent can be running while reading sources, running while waiting for a tool, running while blocked by missing access, running while holding a draft for approval, running while validating a side effect, or running while deciding whether to stop. Those are different states because they require different human responses.
A useful state model names the operational meaning. Queued means the work has been accepted but no delegate is active. Preparing means the agent is collecting scope, context, or credentials before acting. Investigating means it is reading and comparing evidence. Waiting on tool means the next step depends on an external response. Blocked means the agent cannot proceed without new information, access, or a decision. Ready for approval means a specific action or artifact is available for review. Applying means an approved action is being executed. Validating means the agent is checking whether the action produced the intended result. Handed off means the work is complete enough for the next human or system to decide.
Those names do not need to be universal. A customer-support agent, coding agent, research agent, and finance operations agent may use different words. The important habit is that the state should tell the workflow what kind of attention is needed. A blocked run should not look like ordinary progress. A draft should not look like accepted output. A tool timeout after a state-changing request should not look like a clean failure. The state should preserve the difference.
Keep the run’s phase separate from the status of each action. A run may be blocked while a previous action has an unknown outcome, or it may be validating one successful action while another remains proposed. One label cannot describe all of those facts. Define terminal outcomes such as completed, cancelled, declined, and failed as well as the conditions for reopening or creating a new run. Completion should say whether it means the agent finished its work or a human accepted it; those are separate events.
A small run record
Start with a durable record that the workflow, rather than the model alone, updates. For a support agent preparing a reply, a minimal record could contain:
| Field | Example and purpose |
|---|---|
| Run identity and version | run-4821, version 7; identifies the run and detects conflicting updates. |
| Phase and next step | ready_for_approval; a reviewer must decide whether draft 3 may be sent. |
| Scope and evidence | Ticket 4821, ticket revision 8, policy source and its observed version; identifies the basis for the draft. |
| Artifact and approval | Draft 3 and its fingerprint; approval is pending and must identify the permitted recipient and action. |
| Action and outcome | Action send-4821-3 is proposed, with no send attempt yet; later store the provider receipt or an unknown outcome. |
| Recovery | Check the current ticket and approval before sending; name the owner, blocker, and next review time when relevant. |
This is an illustrative record, not a required schema. Keep artifact references and versions where possible rather than copying entire documents into state. The model can propose a state change, but the orchestration layer should check the transition and persist it. A status generated in a final answer is not proof that the durable record or external system changed.
Decide which store is authoritative for each fact. The run record can be authoritative for the workflow’s phase and recorded approval; the ticket system remains authoritative for whether the ticket was answered. A checkpoint is a snapshot of what the workflow knew at a particular version, not proof that an external record is still unchanged. Record when external facts were observed and refresh the ones that matter before acting. If the stores disagree, keep the discrepancy visible until it is resolved rather than silently choosing the more convenient value.
Transitions are where risk appears
The risky moment in an agent run is often the transition, not the state itself. Reading evidence is one kind of activity. Moving from reading to action is another. Drafting a message is one state. Sending it is a transition. Preparing a database update is one state. Applying it is a transition. Producing a code patch is one state. Merging or deploying it is a transition.
Each important transition should have a reason and a record. What evidence allowed the run to move from investigation to proposal? What approval allowed the run to move from proposal to execution? What result allowed it to move from execution to verification? What check allowed it to move from verification to handoff? If the system cannot answer those questions, the final status is too blunt.
AI Agent Permissions becomes easier to enforce when transitions are explicit. The permission ladder is not only a static property of the agent. It changes what transitions are allowed. A read-only run should not transition into applying changes. A draft-only run should not transition into sending. A run with expired approval should return to approval or blocked state rather than proceed under stale authority.
Transitions also help with incident review. If a run caused a bad side effect, the team can ask whether the wrong transition was allowed, whether the transition lacked evidence, whether the tool failed to preserve idempotency, or whether the agent misreported its state. That is more useful than saying the agent made a mistake.
For the support example, ready_for_approval can move to applying only after the workflow checks that the approval covers draft 3, the intended recipient and action, and remains valid. It must also check whether the ticket or draft changed while the reviewer was deciding. A changed draft or intervening human reply should lead to a conflict or renewed review, not a silent send. A declined approval is a decision to record, not a tool failure. After sending, record the receipt and move to validation; a timeout moves the action to an unknown outcome until it can be reconciled.
The same example can be written as a small transition contract:
| From | Event and required check | Result |
|---|---|---|
investigating | Draft and evidence are ready for a named reviewer. | Save their versions and move to ready_for_approval. |
ready_for_approval | Approval matches the draft, recipient, action, and current ticket; authority is still valid. | Record the approval and action intent, then move to applying. |
applying | The provider returns a receipt. | Record the receipt and move to validating. |
applying | The response is lost or times out. | Mark the action outcome unknown and pause for reconciliation. |
validating | The intended result is confirmed against the ticket and receipt. | Record the check and hand off; acceptance can follow separately. |
If an approval is declined or a check fails, record the decision or conflict and route it to the appropriate person. These are example rules; a real system must define who can make each transition and what happens if a required check is unavailable.
Record the prior and new state, time, actor, reason, and references to the evidence or approval for each consequential transition. Enforce allowed transitions and their conditions in the workflow or tool boundary, not just in instructions to the model. AWS Step Functions’ error-handling documentation illustrates how a workflow can route different errors to retry or recovery paths; the particular transitions and safeguards still have to be designed for the task.
Side effects need durable state
State management becomes serious when the agent can affect systems outside its own transcript. A search can be repeated with little consequence. A sent email, changed customer record, archived file, opened pull request, or executed workflow is different. The run state must remember what external action was attempted, whether it succeeded, whether it may have partially succeeded, and how to find the resulting record.
Give each intended action a stable identity before the first attempt and retain any identifier or receipt the tool returns. If the agent submits a request and the network fails before the response returns, the workflow needs a way to determine whether the action happened. An idempotency key can prevent duplicates only when the receiving service supports and enforces it for that operation, within its documented scope and retention period. Otherwise use a reliable lookup or reconciliation procedure; if the outcome cannot be established, pause rather than blindly repeat the write. AI Agent Retries and Idempotency is not only about tool design. It is also about run state. The agent has to know whether it is retrying a safe read, confirming an uncertain write, or attempting a new action.
Side-effect state should be boring and inspectable. It should name the target object, requested change, actor identity, approval record, time, result, and recovery path when one exists. The agent does not need to write a dramatic explanation after every action. It does need to leave enough state that a reviewer can distinguish proposed work from applied work.
This distinction matters in handoffs. A final answer that says “I updated the record” is weak if the state does not show the record ID and tool result. A final answer that says “I prepared the update but did not apply it” should be supported by the action record. If a request may have escaped before the record was updated, report the outcome as unknown rather than inferring that nothing happened. State makes claims checkable when it is reconciled with the systems that actually perform the work.
Protect the record from competing updates
Two workers, or a worker and a human, can read the same state and attempt incompatible transitions. Use an atomic conditional update or transaction against the expected run version so only one transition from that version succeeds. The loser should reload the current state and handle the conflict, not overwrite it. For example, DynamoDB’s optimistic locking pattern checks a version condition on update and rejects a conflicting write. A claim or lease can coordinate workers, but an expired worker may still be running; protected writes need enforcement at the destination, and external services may not support it. AI Agent Concurrency explains the limits of leases and version checks.
A local transaction cannot generally include an unrelated external service. Persist the action intent before calling it, retain the result when available, and reconcile after an interruption between the remote action and the local update. An append-only transition history can help explain changes, but it is useful only if its writes and access controls are reliable. State labels alone do not provide atomicity or prevent duplicate effects.
On recovery, first load the latest run and action records, then inspect any intent without a confirmed result. Query the destination using the action ID or another reliable identifier if the service supports that lookup. Record what the destination confirms and only then decide whether validation, a safe retry, or human investigation is next. For example, Stripe’s API v1 idempotency rules include parameter matching and a retention limit; reusing a key after it has been pruned can create a new request. A key is therefore not a substitute for knowing the provider’s behavior or resolving an old unknown outcome.
Checkpoints are state with intent
A checkpoint is more than a saved transcript. It is a deliberate state that says the run can pause here and resume later without losing the shape of the work. It should preserve the assignment, current state, evidence gathered, decisions made, open questions, artifacts produced, approvals granted or denied, and side effects already attempted. Without those fields, resuming means rereading the whole transcript and hoping the next agent reconstructs the same situation.
AI Agent Checkpoints explains the resumability problem in detail. State management gives checkpoints a backbone. The checkpoint should not merely say “paused.” It should say paused while waiting for source access, paused after draft preparation, paused before applying an approved action, or paused after a failed validation. Each pause has different next steps.
Good checkpoints also prevent accidental repetition. If an agent has already sent a message, the resumed run should not see only a draft and send it again. If it has already inspected three sources and rejected one as stale, the next delegate should not repeat the same search as if nothing happened. If an approval was granted for a specific artifact, the resumed run should know whether the artifact changed after approval. State carries the continuity that conversation alone cannot guarantee.
This is especially important for long-running or queued work. A human may start a run in the morning, answer an approval request later, and review the result at the end of the day. Several systems may have changed in between. The checkpoint should tell the workflow what was true when the agent paused and what must be refreshed before it continues.
Human review depends on state labels
Human reviewers do not need to read every internal step of every agent run. They do need to know what they are being asked to judge. State labels make that possible. A reviewer looking at an investigation state should expect evidence and hypotheses. A reviewer looking at ready-for-approval state should expect a proposed action and consequences. A reviewer looking at validation state should expect checks and results. A reviewer looking at handed-off state should expect a concise record of what was done and what remains uncertain.
This connects directly to Human Review for AI Agents and AI Agent Output Verification . Review is weaker when every artifact arrives as a final answer. The reviewer has to infer whether the agent is asking for advice, approval, acceptance, or further work. State labels remove that ambiguity. They tell the reviewer which decision is on the table.
The control surface should show state without turning it into noise. A person does not need constant theater about small steps. They need meaningful changes: blocked, waiting, ready for approval, applying, failed validation, complete with uncertainty. The label should be backed by evidence. If a run says ready for approval, the proposed action should be visible. If it says blocked, the blocker should be named. If it says validated, the validation result should be attached.
State labels also protect attention. A queue full of “running” tasks is hard to supervise. A queue that separates blocked work, review-ready work, and ordinary progress lets people spend attention where it changes the outcome.
State should survive model and tool changes
Agents change. Prompts are edited, models are upgraded, tools are renamed, schemas evolve, and permissions tighten. If the state model is only an informal narrative generated by the current prompt, it may break when those pieces change. A durable state model gives the system a stable language across versions.
AI Agent Change Management is easier when run state is explicit. A team can compare whether the new version spends more time blocked, asks for more approvals, retries tools differently, or moves to execution with less evidence. Those are operational signals. They are hard to measure if the only available record is a pile of transcripts and final answers.
State also helps with routing. AI Agent Routing decides where work should go before it starts, but a run can discover new facts after launch. A simple task may become sensitive. A read-only investigation may reveal the need for a state-changing action. A lightweight model may encounter a conflict that deserves escalation. The state model should allow the run to change lanes without losing its history. Escalation is a transition, and it should preserve why the route changed.
This does not mean every organization needs a complex workflow engine before using agents. It means even a small agent system should avoid treating conversation as the only memory of work. A handful of well-named states, stable action records, and clear handoff fields can do more for reliability than a large unstructured transcript.
Version the state schema and transition rules as well as the prompts and tools. When a field or state changes, define how existing paused runs will be migrated or continue under their old rules, and test recovery before rollout. Keep sensitive content out of status fields and action IDs; restrict access to stored evidence, retain it only as long as needed, and apply the same deletion and redaction rules to checkpoints and logs. See AI Agent Data Boundaries for handling sensitive material.
Failure is also a state
Failed agent runs should not collapse into a single error. A task can fail because the assignment was unclear, a source was missing, a tool was unavailable, a permission was denied, validation failed, approval was withheld, an external system changed, or the agent made an incorrect inference. Those failures imply different next steps. Some should be retried. Some should be escalated. Some should become evaluation cases. Some should stop permanently.
When AI Agents Fail is easier to apply when failure state is specific. A failed validation after an applied change is urgent in a different way from a blocked source lookup. A denied approval is not a system failure. A tool timeout after a state-changing request is not the same as a tool timeout before any action. Specific state prevents response teams from treating unlike cases as one generic failure bucket.
Failure state should preserve evidence rather than erase it. The original assignment, sources inspected, tool calls, approvals, artifacts, and side effects are the material needed for repair. If the system hides them behind a red failed label, the next person has to rebuild the run from fragments. A useful failure state says what failed, what is known, what is unknown, what changed outside the agent, and which transition should not be attempted again without review.
Test the transitions before relying on them
Use a safe test target and exercise the boundaries that matter for the workflow:
- Try an invalid transition, such as sending before approval, and confirm that the enforcing component rejects it.
- Approve a draft, change the draft or target record, and verify that execution stops for a fresh check or review.
- Race two workers from the same run version and confirm that only one state update succeeds; test takeover after a lease expires if leases are used.
- Interrupt an action after the remote system accepts it but before the receipt is saved. On resume, confirm that the outcome is reconciled or remains explicitly unknown, with no unguarded repeat.
- Resume a checkpoint after a schema change and check that its evidence, approval, and next step still mean what they did before the change.
Record the expected and observed outcomes, including cases that require a person. These exercises test whether the state model controls real behavior, not merely whether a dashboard displays the right labels.
State management is not glamorous. It is the quiet structure that lets delegated work be supervised, resumed, audited, retried, and accepted. The agent may be fluent, but fluency is not state. A clear state model tells people where the work stands, what authority has been used, what evidence supports the next transition, and what remains unfinished. That is what turns an agent run from a stream of messages into work that can be managed.
Written By
JJ Ben-Joseph
Founder and CEO ยท TensorSpace
Founder and CEO of TensorSpace and the editor of Fondsites: an engineer working across software, AI, cybersecurity, and biosecurity who builds the site's games and tools.