Engineer agent loops

Engineer Agent Loops

Core model

Treat the harness and the loop as different layers:

Harness = what an agent can observe and do during a run
Loop    = when and why the run repeats, changes state, stops, or escalates
Contract = harness capabilities + temporal control + evidence

Produce a loop contract, not a new agent framework. Keep model choice and runtime implementation replaceable.

Choose the task mode

• Design: create a new contract from a workflow or recurring task.
• Audit: inspect an existing agent loop, scheduler, workflow, or orchestration file without changing it.
• Repair: modify a contract or loop design to fix specific findings.
• Compare: score two designs against the same invariants and explain the tradeoffs.

Do not create a persistent loop for a one-shot task unless repetition, resumption, or unattended execution is actually required.

Workflow

1. Inventory the harness

   • Identify available tools, permissions, context sources, state storage, sandboxes, hooks, and external side effects.
   • Separate confirmed capabilities from proposed capabilities.
   • Mark destructive actions, external writes, money movement, credential use, and permission expansion as high risk.

2. Define the loop boundary

   • State one measurable objective and the work-discovery source.
   • Declare execution_mode as single-run, event-driven, scheduled, or queue-worker.
   • Define the smallest independently verifiable unit of work.
   • Name the initial, recovery, terminal, and human-escalation states.
   • Prefer observe -> plan -> act -> verify over a free-form while true loop.

3. Specify evidence and progress

   • Use deterministic verification when available: tests, schemas, exit codes, hashes, diffs, or policy checks.
   • Do not let the producing agent be the only judge of success.
   • Define progress signals and a fingerprint that detects repeated state/action/observation triples.
   • Require verification evidence before entering done.

4. Bound and recover

   • Set at least two hard budgets, normally iterations plus wall time; add cost or tool-call budgets where relevant.
   • Bound every retry by failure class.
   • Define rollback, checkpoint, resume, no-progress, and budget-exhaustion behavior.
   • Escalate when the loop lacks authority or new evidence, rather than repeating a failed action.
   • For scheduled or queue-worker loops, define per-item budgets, lease expiry, a durable cursor, quarantine-and-continue behavior, concurrency, and a disable switch.

5. Draft the contract

   • Copy assets/loop-contract.template.json and adapt it.
   • Read references/contract-schema.md when changing fields or writing an integration.
   • Read references/loop-patterns.md only for the relevant loop shape.

6. Validate and visualize

   • Run:

     python scripts/loop_contract.py validate <contract.json>
     python scripts/loop_contract.py score <contract.json>
     python scripts/loop_contract.py diagram <contract.json>
     

   • Fix all errors. Explain accepted warnings rather than hiding them.

   • Treat the score as a coverage heuristic, not proof that the runtime is safe.

7. Hand off implementation

   • Name the runtime hooks needed for each transition, signal, gate, and verifier.
   • Preserve the contract as the source of truth; avoid duplicating rules only in prompts.
   • Do not enable schedules, external writes, or production execution unless the user requested that operational change.

Non-negotiable invariants

• Every loop has reachable terminal states for success and escalation or failure.
• Every cycle is bounded by budgets and a no-progress detector.
• Every retry is failure-specific and finite.
• done requires recorded evidence from named verification conditions.
• State is externalized enough to resume or explain why resumption is impossible.
• High-risk actions have explicit permissions and human gates.
• Traces record state transitions, actions, observations, verification, interventions, and the stop reason.
• A new attempt must change evidence, strategy, authority, or context. Repetition alone is not recovery.
• One malformed queue item must be quarantined after bounded attempts and must not block unrelated work.

Output contract

Return:

1. confirmed harness inventory and unresolved assumptions;
2. the loop contract path or proposed contract;
3. validator errors, warnings, and score;
4. a state diagram;
5. runtime integration points;
6. residual risks and the next safe test.

Never claim that static validation proves model correctness, business correctness, or production safety.