Browse notes
Agent State
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.
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.