Long-running agents
Work that outlasts one context window needs structure: a plan, a progress file and clean handoffs.
Words on this page (6)
- context window
- : The maximum number of tokens a model can look at in one call: your prompt, the conversation, tool results and the answer together.
- agent
- : A model run in a loop that chooses its own tools and steps until the task is done.
- compaction
- : Summarizing older conversation so a long task fits in the context window.
- git
- : The standard tool for tracking changes to code.
- logarithm
- : The power you raise a base to in order to get a number. log base 2 of 8 is 3 because 2 to the power 3 is 8.
- token
- : A piece of text the model reads and writes, usually a word or part of a word. About 4 characters of English on average.
The problem
Over hours, context fills, coherence drops and may wrap up early. summarizes in place. A reset clears the window and starts a fresh agent with a written handoff. Resets give a clean slate at the cost of writing a good handoff.
A workable design
An initializer agent expands the spec into a feature list and a setup script. A worker agent takes one feature at a time, commits and updates a progress file. An evaluator agent runs the app and the tests and reports failures with evidence. Tests and the are the shared state. Each agent starts by reading the progress file and the latest commits.
A worked example: a progress file
progress.md: "Goal: build the invoicing app. Features done: login, customer list. In progress: invoice PDF export. Next: email sending. Tests: 24 passing, 2 failing (export). Notes: use the existing PDF library." A new agent session reads this file and the latest commit messages and continues in minutes.
Evaluator agents
A separate agent runs the app and tests it, then writes what it found. The worker agent fixes those issues. Splitting the roles stops the worker from marking its own homework generously.
Compaction versus reset in numbers
Invented numbers. The window holds 100,000 and after hours of work 90,000 are used.
Compaction replaces the history with a 5,000-token summary and the same agent carries on. It is quick, but each summary is made from the last one, so small errors and lost details stack up.
A reset starts a new agent with a 1,000-token handoff plus the files it reads itself. It costs more effort to write the handoff, but the new agent sees the real files, not a retelling.
What goes wrong: declaring victory early
The symptom is an agent that announces "done" with five of twenty features working. The cause is that it judges completion by feel. Confirm it by comparing its claim with the feature list and the test results. The fix is to make the list the definition of done. Each feature has a status, and only a passing test may change it to done. The run ends when the list is complete, not when the agent says so.
What a handoff must contain
The example progress file lists goals and state. Good handoffs also hold three more items:
- The exact next step.
- What was tried and failed, so the next agent does not repeat it.
- How to run the tests.
Without the second item, a fresh agent often rebuilds the same dead end.
Common mistake
Letting a single context run for hours. Quality drops. Reset with a handoff.
A marathon runner does not carry every memory of every mile in their head. They carry a plan, check the watch, and refuel at stations. A long agent run is similar: it cannot carry everything in its context, so it uses a plan, a progress file and checkpoints.
Check yourself
What is the difference between a reset and compaction?
Not quite. A reset avoids lingering context anxiety but needs a good handoff.
What is the shared state between sessions of a long task?
Not quite. Durable artifacts let a fresh agent pick up the work.
An agent marks its own work as done, but half the feature is missing. What helps?
Not quite. Separating the doer from a skeptical checker stops generous self-grading.
You got 0 of 3 right.
Go deeper
- Article
Anthropic · Initializer and coding agents with progress artifacts.
- Article
Anthropic · Planner, generator and evaluator over multi-hour runs.
Spotted a mistake or something unclear? Report it on GitHub.