Skip to main content

Bounded Agent Loop Patterns

An agent loop is useful only when progress and stopping are observable. The basic cycle is simple:

read state → choose one action → execute → inspect evidence → update state → stop or repeat

The hard part is not repetition; it is deciding what survives between iterations and what proves that another turn is worthwhile.

Four Useful Patterns​

1. In-session tool loop​

One model conversation alternates tool calls and results. It is responsive and preserves nuance, but history grows, failed approaches remain salient, and the model may declare success from its own narrative. Use it for short exploratory work with a small turn limit.

2. Fresh-context task loop​

Each iteration starts a new model process and reads durable files such as a task brief, test output, and progress ledger. This pattern—sometimes implemented as a shell “Ralph loop”—trades conversational memory for reproducibility. It works only when state is explicit; restarting the model does not repair a vague task or a stale ledger.

3. Implement–verify loop​

The worker makes one bounded change, then an external command decides the next state:

implement → format/lint/test → diagnose failure → repair

The verifier must be independent of the model's prose. Prefer exit codes, assertions, schema checks, and diff inspection. Cap repair attempts and preserve the last failing evidence.

4. Evaluator–optimizer loop​

A worker produces an artifact; a separate evaluator returns structured defects; the worker addresses only those defects. This can improve writing, plans, and code review, but the evaluator needs a rubric and must not silently expand scope. Independence is stronger when the evaluator has a fresh context or a different model.

Required Stop Conditions​

Every automated loop should define:

  • a success predicate outside the model;
  • maximum iterations, wall time, token or cost budget;
  • a no-progress rule, such as the same error signature twice;
  • a diff or side-effect boundary;
  • an escalation state for missing credentials, ambiguous requirements, or repeated failure;
  • cancellation and a recoverable checkpoint.

“Continue until done” is not a stop policy.

A Minimal Loop Ledger​

Keep the durable state small:

objective: tests pass without changing the public API
attempt: 3
last_action: replaced parser boundary check
verification: pytest tests/test_parser.py -q
result: failed, 1 assertion
next: inspect UTF-8 truncation case
blocked: false

Do not store long hidden reasoning. Store decisions, commands, artifacts, failures, and the next check. A fresh model should be able to resume from this packet without replaying the entire transcript.

Local-Model Adjustment​

Smaller local models benefit from shorter iterations, fewer tools, explicit file targets, and deterministic verifiers. Give one change at a time, summarize noisy command output, and restart context before drift becomes visible. More loop iterations do not compensate for a model that cannot reliably use the required tools.