What Is Loop Engineering? How to Design AI Agent Loops That Stay Grounded

Loop engineering is the practice of designing the system that prompts, checks, and re-runs an AI agent until a goal is met or a stop rule ends the run. Instead of typing every next instruction yourself, you build the loop that does it for you.

Addy Osmani popularized the practice in June 2026. In Osmani's loop engineering essay, he put it plainly: "Loop engineering is replacing yourself as the person who prompts the agent. You design the system that does it instead."

A simple example is a "fix the failing tests" loop. The agent reads the test output, edits the code, and runs the tests again. The loop repeats until every test passes, a budget runs out, or the agent reports that it is blocked.

The practice matters now because most software professionals already use AI. Google's 2025 DORA report found that "AI adoption among software development professionals has surged to 90%, marking a 14% increase from last year." As AI use spreads, more of the bottleneck moves from writing prompts to designing how agents run.

One point that is easy to miss: a loop's world is not only the code repository. Many loops also read documentation, changelogs, pricing pages, and other live web sources. If those inputs are stale, every iteration builds on outdated facts.

How Loop Engineering Differs From Prompt, Context and Harness Engineering

In Osmani's framing, loop engineering sits one floor above the harness. Prompt engineering shapes a single instruction, while loop engineering designs the repeat, verify, and stop system around many agent runs.

If you want the background on the first two layers, see context engineering vs prompt engineering. The harness is the next layer up, and it helps to know what an agent harness does before you design a loop around one.

So is loop engineering part of harness engineering? Not exactly. A loop runs on top of a harness. The harness gives one agent its tools, and the loop decides when that agent runs again and whether its work counts as done.

There is also a hidden assumption here. Context engineering assumes the context you give the model is correct. A loop that runs for days or weeks breaks that assumption, because the world keeps changing while the loop keeps reading the same files.

The Building Blocks of an Agent Loop

An agent loop is a cycle in which an AI agent plans, acts, checks the result, and decides whether to continue. Most well-designed loops share five core parts.

• Goal and trigger: what the loop must achieve, and what starts it.
• Inputs and fresh context: what the agent reads on every pass.
• Verifiers: the checks that decide whether the work is correct.
• Stop rules and budgets: the conditions that end the loop.
• Human checkpoints: the points where a person must approve.

Goal and Trigger

A loop needs a goal it can measure, such as "all tests pass" or "the pricing table matches the vendor's page." Vague goals like "improve the code" give the loop no way to know when it is finished.

A trigger is the event that starts a run. Common triggers include:

• A schedule, such as every night at 2 a.m.
• A new pull request or issue.
• A change on a web page the loop depends on.

The third trigger is the easiest to overlook. With the Olostep Monitors API, a monitor watches a page and sends an alert, such as a webhook, when it changes. That alert can start a loop run, so the agent works only when something it depends on has actually changed.

Inputs and Fresh Context

Inputs are everything the agent reads at the start of each pass. That includes the code, memory files such as AGENTS.md, and outside sources like API docs or release notes.

Memory files and cached docs can go stale without warning. Nothing in a stale memory file signals that it is out of date, so the agent keeps using it with confidence. This is why data freshness matters in any loop that runs more than once.

The fix is to treat outside inputs as something you refresh, not something you store. On each pass, the loop should fetch current versions of the external pages it relies on, convert them to clean Markdown or JSON, and give that to the agent.

Verifiers

A verifier is a check that runs after the agent acts and decides whether the result is correct. Osmani argues the checker should be separate from the agent, because a model reviewing its own output tends to approve it.

That separation matters more as trust in AI output falls. The Stack Overflow 2025 survey reported: "In fact, trust in the accuracy of AI has fallen from 40% in previous years to just 29% this year."

Loops commonly use four types of verifiers:

The live-source check matters most when a loop depends on external facts. A successful API call only shows that a request was accepted, not that the end state changed, so the verifier should check the end state directly. A live-source check closes that gap. For example, the loop can call a single-URL scrape endpoint, get the page as Markdown, and confirm the agent's update matches what the page says now.

Stop Rules and Budgets

Stop rules are the conditions that end a loop. Without them, a loop can keep retrying the same failing step, and every retry spends tokens.

A good loop uses several stop rules together:

• Success condition: the verifier passes.
• Iteration cap: a maximum number of passes, such as 10.
• Budget cap: a token or dollar limit per run.
• Repeated-action detection: stop if the agent tries the same action twice with the same result.
• Blocked exit: let the agent report "blocked" instead of guessing.

Keep each iteration small. METR long-task research found that "current models have almost 100% success rate on tasks taking humans less than 4 minutes, but succeed <10% of the time on tasks taking more than around 4 hours." METR has since noted that parts of that post are out of date, and the figures describe early-2025 models, but they support a practical design choice: short, checked steps instead of one long unchecked run.

Human Checkpoints

A human checkpoint is a point where the loop pauses and waits for a person to approve. Use checkpoints for actions that are hard to undo, such as merging code, deploying, publishing, or spending money.

The goal is not to review everything. A good loop handles routine work and sends only unclear or risky results to human-in-the-loop review. As Osmani warned, "A loop running unattended is also a loop making mistakes unattended."

What Is a Ralph Loop?

A Ralph loop is the simplest form of loop engineering: a shell loop that feeds the same prompt file to a coding agent over and over. The name comes from Ralph Wiggum, a character from The Simpsons. Developer Geoffrey Huntley popularized the technique and described it in Geoffrey Huntley's Ralph post in July 2025.

As Huntley puts it, "In its purest form, Ralph is a Bash loop." A minimal version looks like this:

while :; do
  cat PROMPT.md | claude -p
done

The agent's progress lives in files and git history, not in the chat. Each pass starts fresh, reads the current state of the repo, and picks up the next piece of work.

Ralph loops are popular because they are easy to start. They also have clear limits:

• No built-in verifier: the loop does not check whether the work is correct.
• No stop rule: it runs until you kill it.
• Repeated failures: the agent can hit the same error on every pass.
• Open-ended cost: every pass spends tokens, whether it makes progress or not.

You can turn a Ralph loop into an engineered loop by adding the building blocks above. Add a test or live-source check after each pass, an iteration and budget cap, and a rule that stops the loop when it repeats itself.

Example: A Loop That Keeps Agent Knowledge Current

This example loop keeps an integration up to date when a vendor changes its API docs. It shows how a web-change trigger, fresh inputs, and a live-source verifier work together.

Objective: update your integration code whenever a vendor's API reference page changes.

Prerequisites: an Olostep API key, a coding agent you can call from a script, and a test suite for the integration.

1. Trigger: a monitor watches the vendor's API reference page and sends a webhook when it changes.
2. Refresh: the loop scrapes the page and gets the current version as Markdown.
3. Act: the agent compares the new docs to your code and proposes changes.
4. Verify: the loop runs your tests, then re-scrapes the page to confirm the docs the agent used are still current.
5. Stop or escalate: if checks pass, open a pull request for review. If they fail after the cap, mark the run as blocked and notify a person.

Here is a simplified Python version. The scrape call uses Olostep's /v1/scrapes endpoint. The run_agent and run_tests functions stand in for your own agent and test runner.

import os
import requests

API = "https://api.olostep.com/v1/scrapes"
HEADERS = {"Authorization": f"Bearer {os.environ['OLOSTEP_API_KEY']}"}
MAX_ITERATIONS = 5

def fetch_markdown(url: str) -> str:
    resp = requests.post(
        API,
        headers=HEADERS,
        json={"url_to_scrape": url, "formats": ["markdown"]},
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()["result"]["markdown_content"]

def handle_docs_change(docs_url: str) -> str:
    """Called by your webhook handler when a monitor reports a change."""
    docs = fetch_markdown(docs_url)          # fresh input, not a cached copy
    last_error = None

    for i in range(MAX_ITERATIONS):
        patch = run_agent(docs=docs, previous_error=last_error)
        ok, last_error = run_tests(patch)

        if ok:
            # Live-source check: make sure the docs did not change mid-run
            if fetch_markdown(docs_url) == docs:
                open_pull_request(patch)       # human checkpoint
                return "done"
            docs = fetch_markdown(docs_url)    # docs moved again; refresh and retry
            continue

    notify_human(f"Blocked after {MAX_ITERATIONS} iterations: {last_error}")
    return "blocked"

Expected result: a pull request that updates the integration to match the latest docs, or a clear "blocked" alert with the last error.

How to verify it works: change a test fixture to simulate a docs update, trigger the handler manually, and confirm the loop either opens a pull request or stops at the iteration cap.

The same pattern applies outside coding. Olostep's write-up on agents as data maintainers describes a detect, refresh, and validate loop for web-backed datasets: detect changed URLs, scrape a sample to confirm the change, refresh the batch, validate, and send only unclear changes to a reviewer. As that post puts it, "If web refreshes are unreliable, the entire agent loop becomes unreliable."

Common Loop Failure Modes and How to Prevent Them

The table below lists common loop failure modes and design checks that can help prevent them. Treat it as practical guidance rather than measured failure rates.

Two of these risks are well documented. OWASP's prompt injection guidance warns that "Indirect prompt injections occur when an LLM accepts input from external sources, such as websites or files." And METR's reward hacking findings describe frontier models "attempting (often successfully) to get a higher score by modifying the tests or scoring code."

Search alone does not fix stale context. The Look It Up preprint, a single study that has not been peer reviewed, found that models with web search still topped out around 70% accuracy on fast-changing questions, with most failures caused by weak queries and poor source selection. In other words, a loop needs good queries and the right sources, not just access to search.

When Not to Build a Loop

You should not build a loop when the task has no clear way to check success. If neither a test, a rubric, nor a source page can confirm the result, the loop cannot know when to stop.

Other cases where a loop is the wrong tool:

• One-off tasks, where a single prompt is faster than designing a loop.
• Irreversible, high-stakes actions, such as payments, legal filings, or production data deletion, which need a person in charge.
• Taste and judgment calls, such as brand voice, product direction, and design choices, which still need human review.

A safer path is to start with a supervised loop. Watch several runs, fix the checks that fail, and only then remove human steps one at a time.

Frequently Asked Questions

Who Popularized the Term Loop Engineering?

Addy Osmani popularized the term in a June 2026 essay, which also credits earlier work by Peter Steinberger and Boris Cherny. It describes designing the system that prompts and checks an agent instead of prompting it by hand.

Is Loop Engineering Part of Harness Engineering?

No, loop engineering sits on top of harness engineering. The harness equips one agent with tools, and the loop decides when that agent runs again and when its work is done.

Is Loop Engineering Only for Coding Agents?

No, any task with a checkable goal can use a loop. Research, dataset maintenance, and price or docs monitoring are common examples outside coding.

How Do You Stop an Agent Loop From Running Forever?

Combine a success condition with an iteration cap, a budget cap, and a rule that stops the loop when it repeats the same action. Also let the agent report that it is blocked.

Why Should the Verifier Be Separate From the Agent?

Osmani recommends a separate checker because a model reviewing its own work tends to approve it. A separate test, judge, live-source check, or person gives an independent answer.

How Do You Keep a Loop's Knowledge Up to Date?

Refresh external sources on every pass instead of relying on cached files. Use a monitor to trigger runs when a page changes, and re-fetch the page to verify the result.