agent-loop

The Agent Loop — the perceive → decide → act → feedback cycle that runs until the model returns plain text. Per tw93 in 2026-04-27-agent-principles-architecture-engineering, the core loop is ~20 lines of code and is structurally stable across implementations: SDKs differ, but the loop barely changes from the minimal version through the ones that support sub-Agents, context compaction, and Skills loading. New capability is added outside the loop — extending tools, restructuring system prompts, externalizing state — not by editing it. The loop’s underlying frame is ReAct — reasoning + acting (Yao et al. 2022), which Shunyu Yao’s The Second Half later rationalizes as the bridge between language pretraining priors and generalizable agents — see react for the conceptual page.

The minimum implementation

Roughly 20 lines of TypeScript from the source:

const messages: MessageParam[] = [{ role: "user", content: userInput }];
while (true) {
  const response = await client.messages.create({
    model: "claude-opus-4-6",
    max_tokens: 8096,
    tools: toolDefinitions,
    messages,
  });
  if (response.stop_reason === "tool_use") {
    const toolResults = await Promise.all(
      response.content
        .filter((b) => b.type === "tool_use")
        .map(async (b) => ({
          type: "tool_result" as const,
          tool_use_id: b.id,
          content: await executeTool(b.name, b.input),
        }))
    );
    messages.push({ role: "assistant", content: response.content });
    messages.push({ role: "user", content: toolResults });
  } else {
    return response.content.find((b) => b.type === "text")?.text ?? "";
  }
}

The takeaway is the shape: the model decides; the harness executes; results re-enter the conversation; repeat.

Workflow vs. Agent

anthropic‘s framing, sharpened in this source: Workflow = control flow chosen by code; Agent = control flow chosen by the LLM. Many products labeled “Agent” are actually Workflows.

Five common control patterns

Most “AI systems” decompose into combinations of these five (Anthropic’s enumeration, summarized in the source). Many use cases don’t need full Agent autonomy — picking the smallest pattern that fits is the cheaper engineering choice.

Selection rule of thumb

Source heuristic — pick by task certainty × verification automation:

Default to single-Agent ReAct + an explicit task graph; reach for multi-Agent only after measuring the single-Agent ceiling — coordination overhead often eats the parallelism gain.

Three ways new capability gets added

The source’s load-bearing observation. The loop doesn’t change; capability is layered around it via:

1. Extending the tool set and handlers. New tools, not new loop branches.
2. Restructuring the system prompt. Identity / Skills / runtime injection layers (see context-engineering tiers).
3. Externalizing state to files or databases. The model reasons; the surrounding system carries state and boundaries.

Don’t turn the loop into a giant state machine. Once this division is fixed, the core loop rarely needs to change.

Named loop variants

A few specific patterns that ride on top of the base loop have their own pages:

• react — the underlying concept (reasoning + acting) the loop instantiates; primary-source page based on Yao’s 2022 paper and his 2025 The Second Half essay.
• ralph-wiggum-loop — agent self-review pattern: the agent requests further agent reviews, responds to feedback, and loops until reviewers + verifiers are satisfied. Closest to the Evaluator-Optimizer row above, but with the evaluator multiplexed across multiple agents and verifiers. Used by codex in 2026-04-27-harness-engineering-codex-agent-first to drive most PRs to merge without human review.
• llm-agent — the broader 2023 anatomy (LLM brain + Planning + Memory + Tool use) this loop is the runtime core of. The Thought / Action / Observation template comes from ReAct, cataloged in Weng’s 2023 survey.
• loop-engineering — anthropic‘s productized taxonomy over the base loop (2026-07-12-loop-engineering-getting-started): turn-based (this loop, human-directed — the post calls it “the agentic loop”), goal-based (/goal, evaluator-checked stop condition), time-based (/loop//schedule triggers), proactive (event-driven, no human live). Classified by who supplies the trigger and the terminator — the loop body stays this page’s cycle.

The loop as optimization target

2026-07-07-harness-engineering-self-improvement frames the agent loop not just as a design pattern but as an object for optimization. The progression: first humans hand-craft the loop; then systems like ADAS and AFlow search over workflow graphs; then self-improving-harness systems let the agent evolve its own loop. The loop’s structural stability (noted above) means optimization happens around it — extending tools, restructuring prompts, externalizing state — rather than modifying the ~20-line core.