3 State Engineering: Preserve Agent Progress with Structured State

If the Goal tells the agent where it is going, State tells it where it is now.

Many long-running agents fail because they confuse state with conversation history. The transcript keeps everything. State keeps what still matters.

That difference is the heart of State Engineering.

1. State Is Not a Transcript

A transcript contains every turn. State is a compact working record.

For example, after researching an AI model, the state might say:

{
  "topic": "Gemma model review",
  "finished": ["official docs collected", "basic specs extracted"],
  "todo": ["compare community feedback", "write conclusion"],
  "decisions": ["use tutorial tone", "avoid benchmark claims without sources"],
  "blockers": [],
  "next_action": "summarize official capabilities"
}

This is much easier for the model to use than a giant chat log.

2. A Practical State Schema

A useful state object can start with these fields:

{
  "topic": "",
  "finished": [],
  "todo": [],
  "decisions": [],
  "artifacts": [],
  "blockers": [],
  "observations_summary": "",
  "next_action": ""
}

Each field has a job.

Topic

The current subject or project.

Finished

What has already been completed. This prevents repeated work.

Todo

What remains. This keeps the agent from wandering.

Decisions

Important choices already made, such as style, source policy, or technical direction.

Artifacts

Files, links, drafts, screenshots, reports, or other outputs created during the task.

Blockers

Things that prevent progress, such as missing credentials, broken tests, or unclear requirements.

Observations Summary

A compressed summary of tool results and findings.

Next Action

The one next step the executor should focus on.

3. Update State After Observation

State should be updated after the agent observes reality.

The loop looks like this:

Task
-> Tool Call
-> Observation
-> State Update
-> Next Task

Do not update state too early. If the agent plans to run a build, the state should not say "build passed" until the build actually passes.

This sounds obvious, but it is one of the most common ways agent systems become unreliable.

4. Keep State Small Enough to Read

State should be detailed enough to guide the next step, but small enough to read quickly.

A good rule:

The current state should be readable in about 30 seconds.

If the state becomes too long, summarize it. Move durable preferences into long-term memory. Drop temporary details that no longer affect the work.

5. Practice: Convert a Transcript into State

Take a messy task transcript and rewrite it as:

{
  "goal": "",
  "finished": [],
  "todo": [],
  "decisions": [],
  "artifacts": [],
  "blockers": [],
  "next_action": ""
}

If another agent can continue the task from this object, your state is useful.

6. Lesson Summary

State Engineering is the discipline of preserving progress in a structured, compact, and reliable form.

The transcript is history. State is the current working map.

When Goal and State are both explicit, the agent no longer has to guess what it is doing or where it left off.