Agent Systems · core
Agent Work State & Handoffs
Versioned goals, plans, checkpoints, evidence, blockers, and next actions that let a new session resume without relying on hidden conversational memory.
Mental model
A context window is a worker shift, not durable storage. The repository or workflow log owns the recoverable state: what was requested, what changed, what was verified, what failed, and the smallest safe next action. A handoff is correct when a fresh process can resume from artifacts alone.
How to study Agent Work State & Handoffs
Begin by restating the mental model in your own words, then connect it to a concrete system you have built or operated. Name the mechanism, the constraint it addresses, and the trade-off it introduces. Use Effective Harnesses for Long-running Agents (Anthropic), OpenAI — Symphony orchestration specification to check details, but close the source before writing your explanation. Retrieval is the learning step; rereading is only preparation.
Next, compare Agent Work State & Handoffs with Durable Agent Execution, Agent Memory & Context Management, Agent Run Lifecycle. Ask what changes in correctness, latency, resource use, operability, and failure recovery. Complete Create a durable agent handoff and preserve the command, input, output, and one failed attempt as evidence. Finish by explaining the idea without jargon to someone who has not studied the track.
Proof of understanding
- Explain the mechanism from first principles and identify the state it reads or changes.
- Give one situation where the concept is the right choice and one where it is not.
- Predict a realistic failure mode before running the drill, then compare the prediction with evidence.
- Connect the result to a roadmap or build artifact instead of treating the concept as isolated trivia.
Where it matters
Long-running coding tasks, session compaction, workflow checkpoints, crash recovery, shift handoffs, and resumable background agents.
Common mistakes
- Saving a narrative summary without exact files, commands, or observed results
- Marking a task complete without durable verification evidence
- Letting the chat transcript become the only record of decisions and remaining work
Learn from primary sources
Practice and explain it back
Create a durable agent handoff
Implement createHandoff(input) returning a JSON-safe object with schemaVersion 1, goal, status, completed, evidence, blockers, and nextAction. Reject an input that claims status 'complete' without evidence. nextAction must be one concrete action, not a list, and every evidence item must include both command and observed output.
Expected evidence: A checkpoint that a fresh session can validate and resume without reading prior chat.
Open the interactive drill →Review prompts
- What minimum state must survive a context reset so a different agent session can safely resume an unfinished change?
Build evidence
Build a Complete Coding-Agent Harness
Build a repository-local harness that can take one bounded engineering task from initialization through implementation, verification, durable handoff, and explicit termination without relying on hidden machine state or chat memory.
- A fresh isolated workspace can bootstrap and prove readiness from repository-local commands
- Instruction scopes, allowed edit roots, capabilities, budgets, and escalation triggers are explicit and mechanically inspectable
- The run persists goal, progress, evidence, blockers, and the next safe action across a forced restart
- A checker gathers independent evidence and can reject an unsupported maker claim
- The lifecycle terminates only as complete, blocked, failed, cancelled, or escalated with durable evidence
Automate and Evaluate a Maker-Checker Loop
Automate a bounded loop in which a maker attempts one task, an independent checker evaluates explicit acceptance criteria, failures return actionable evidence, and the orchestrator stops on success, escalation, cancellation, or budget exhaustion. Compare it with a baseline harness on a frozen task suite.
- Maker and checker roles have separate inputs and the checker ignores unsupported self-reported success
- The loop has explicit goal, task and retry budgets, durable state, and semantic termination criteria
- A frozen evaluation suite measures success, unsafe actions, cost, latency, retries, and human interventions
- At least one component ablation isolates whether instructions, tools, verification, or retry policy caused the observed change
- Release or rejection follows a declared multi-objective gate rather than pass rate alone