Agent State

What an application records so an agent can resume a task and verify changes in the system it acts on.
Updated 11 Oct 2026

The application keeps the agent’s working state across calls. Before each decision, it prepares the context the model will receive; the model returns an answer or requests a tool call. The API, repository, or service has its own state, which can change while the task runs.

External world, application state, and model context Observation flows from the external world to application state. Actions flow back to the world. The application selects a subset of state for model context. External world Repository, APIs, services Application state Task record and evidence Model context Selected for the next call Observe Act Select External world, application state, and model context Observation flows from the external world to application state. Actions flow back to the world. The application selects a subset of state for model context. External world Repository, APIs, services Application state Task record and evidence Model context Selected for the next call Observe Act Select
The agent observes and acts on the environment. The application records results and selects what reaches the model.

The arrows show the cycle: the agent observes the environment, the application records the result, and it prepares information for the next call. An action can request a change in the environment; the next observation updates the working record.

A usable working record

Suppose an agent is checking whether user_b can modify an invoice owned by user_a in a test API. Its working record might look like this:

objective: verify-cross-account-write
scope:
  origin: https://api.example.test
  identities: [user_a, user_b]
  allowed_actions: [read, replay, reversible-write]
observations:
  - id: obs-014
    source: GET /api/invoices/1042 as user_a
    value: "owner=user_a; note=before"
    observed_at: 2026-10-05T09:12:00Z
    evidence: artifacts/requests/obs-014.http
hypotheses:
  - id: hyp-003
    claim: "user_b can change invoice 1042 despite owning a different account"
    based_on: [obs-014]
    status: unverified
actions:
  - id: act-021
    operation: PATCH /api/invoices/1042 as user_b
    marker: auth-check-01
    result: timeout-unknown
    observed_at: 2026-10-05T09:15:00Z
pending:
  - read invoice 1042 as user_a and compare its note with obs-014
checkpoint:
  step: verify-write-effect
  request_log: artifacts/requests/act-021.http

The record keeps observations, hypotheses, and actions in separate fields. The log preserves the exact request bytes; obs-014 points to them without copying the full exchange into context. hyp-003 stays pending until a later read shows what happened. Because the PATCH timed out, its result remains unknown until the invoice is checked.

Keep paths, external IDs, and hashes literal when they will be needed to retrieve the same resource. The summary explains why invoice 1042 was tested; the requests and responses preserve the evidence. For tokens, store a reference to a controlled secret store.

What belongs in context

For the next decision, give the model the objective, test scope, known invoice owner, uncertain PATCH result, and pending verification step. The full HTTP log can remain as an artifact; the application retrieves the exact exchange when needed.

The selection changes as work proceeds. When the agent reads the invoice again, the new response becomes the latest evidence and the baseline remains available for comparison. Before another request, the application can retrieve the scope, authorization rules, and relevant HTTP exchange.

After a tool call

The runtime records the attempted operation, its arguments, result, and observation time. To confirm a write, read the resource again and compare its stored value. An error response needs follow-up: the operation may not have started, may have partly run, or may have completed while the reply was lost.

A timeout after a side-effecting action is ambiguous. If the PATCH above times out, read the invoice as its owner before replaying the write. Compare the marker and original value, then record completed, not-applied, or unknown. Where the API supports an idempotency key or operation ID, keep it with the action record.

Facts that go stale

observed_at records when a fact was seen; its validity depends on what has changed since. Invoice ownership, permissions, job status, and API responses can change while the agent works. Revalidate before an action that depends on such a fact, especially after a pause or when another actor may have intervened.

On recovery, restore the step and saved references. Check the invoice and session state before continuing; the target system may have changed during the pause. If the marker is already present or a token has expired, adjust the next request to the state you observed.

Agent state across calls

Agent state is the working record the application keeps so the task can continue: objective and scope, observations with evidence references, hypotheses, actions and results, the next step, and a checkpoint. Before each call, the application selects the information the model needs to decide; that selection forms the context. The environment keeps its own state, which the application checks when the next action depends on its current value.

References