dful.
Dful Dark
Theme
Knowledge tree
On this page

Agent State

What an application must record so an agent can continue without confusing context, evidence, and external state.
Updated 6 Oct 2026

An agent’s state lives in the application. The model receives a selection of that state for each call, makes a decision, and returns an answer or tool call. The repository, API, or service the agent works on has its own state.

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 matter. An observation updates the application’s record. An action tries to change the environment. Context contains only what is sent to the model for its next decision. None of these layers is a guaranteed copy of another.

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

This is a design example, not a required schema. It separates observation from inference. The request log keeps exact bytes, while obs-014 provides a stable reference without copying them all into context. hyp-003 remains unverified until the later read shows what happened. The timeout cannot be recorded as a successful write or a rejection.

Keep paths, external IDs, and hashes exact when the same resource must be retrieved later. A summary can explain why invoice 1042 was tested, but it cannot replace the request and response evidence. State should hold a reference to a controlled secret store rather than copying token values.

What belongs in context

For the next decision in this example, the model needs the objective, test scope, invoice ownership, the unanswered PATCH, and the next verification step. The complete HTTP log can remain outside context if the model can retrieve it. There is no reason to resend every earlier request.

The selection changes as work proceeds. Once the invoice is read again, the new response becomes the immediate evidence. The baseline remains available for comparison. Before a new request, the application can retrieve the exact scope and authorization rules as well as the relevant HTTP exchange.

After a tool call

The runtime should record the attempted operation, arguments, result, and observation time. An HTTP status alone does not prove that a write persisted. An error response may mean the operation never started, partially ran, or completed while its 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 says when a fact was seen, not how long it remains true. Invoice ownership, permissions, job status, and API responses can change without the agent acting. Revalidate before an action that depends on such a fact, especially after a pause or when another actor may have intervened.

A checkpoint restores the step and saved references. On recovery, check the invoice and session state before continuing. A checkpoint does not freeze the target. If the marker is already present or a token has expired, the next request changes.

References