AI Agent Loops and Graphs: A Production Field Guide

An agent completes a task, shows a plausible answer, and waits for a person to inspect every intermediate step. The model may be capable; the system around it is still manual. Removing that supervision does not mean asking the model to be more autonomous. It means giving each unit of work a test that can reject it, then arranging those units in a control flow that knows what may run, what must wait, what can run in parallel, and where a failure goes.

Hanako's widely shared “Loops and Graphs” article on X offers a memorable distinction: a loop improves one unit of work, while a graph decides which units exist and how they connect. This guide fully covers that model, but turns it into a production contract. The key addition is governance: checks must be executable, graph state must be typed and durable, retries must stay inside the failed unit, learned constraints must be reviewed and versioned, and human approval must sit at the boundary of greatest consequence.

What the loops-and-graphs model gets right

The strongest idea in the original article is that a repeated action is not automatically a loop. A production loop has four stages:

produce → check → correct → repeat or stop

The check must be able to change what happens next. “No exception occurred,” “the answer looks good,” and “the model is confident” are observations, not acceptance tests. A gate produces a machine-readable verdict tied to evidence and routes the state to accept, correct, escalate, or stop.

The second useful distinction is architectural: the loop lives inside a node; the graph lives between nodes. A local loop can improve a translation, patch, extraction, or research slice. It cannot determine whether two slices are independent, whether a deterministic transformation should replace a model, or whether a dangerous action requires approval. Those are graph decisions.

This fits the broader engineering record. Anthropic's catalog of effective agent patterns separates prompt chaining, routing, parallelization, orchestrator-workers, and evaluator-optimizer loops. Google's Agent Development Kit workflow documentation likewise treats sequential, parallel, and loop execution as explicit control-flow structures rather than improvised prompting.

The model is therefore a useful design lens, not a complete runtime specification. A production implementation still needs state ownership, identity, persistence, concurrency rules, stop conditions, side-effect controls, and evidence.

Keep the loop contract separate from the graph contract

Mixing these two contracts creates systems that are hard to test and impossible to recover safely.

A node should have one input schema, one output schema, one owner, one side-effect policy, and one local acceptance contract. An edge should name the state that crosses it and the condition that makes the destination eligible.

Ask one question about every edge: which exact output of the current node does the next node consume? If no variable, artifact, decision, or event crosses the boundary, the edge is probably a sequencing habit rather than a dependency. Remove it and the nodes may run in parallel. This is the concrete version of the original article's warning against treating every “and then” as an arrow.

The current LangGraph Graph API documentation formalizes a similar separation through state, nodes, and normal or conditional edges. Its documentation also notes that a node can be ordinary code, not necessarily an LLM. The concepts are portable even if a team uses a queue, workflow engine, state machine, or its own orchestration layer.

Write the gate before the generator

A loop becomes useful when its acceptance condition is defined before generation. Start with evidence that a program, qualified reviewer, or adjudicated evaluator can actually inspect.

Good gates include:

• the test command exits successfully and the expected test count ran;
• every factual claim resolves to an allowed source identifier and quoted evidence span;
• structured output validates against the pinned schema version;
• the diff touches only the files authorized for this unit;
• the Persian and English editions contain the same source URLs, numbers, sections, and caveats;
• a proposed action matches an active policy, current record version, and valid approval hash.

Weak gates include confidence, eloquence, absence of visible errors, or agreement from a second model that received the same assumptions. A model judge can help with open-ended properties, but it needs a written rubric, calibration against human-adjudicated examples, disagreement handling, and a deterministic outer gate for facts, schemas, permissions, and side effects.

Represent the verdict as data:

{
  "unit_id": "handlers-auth",
  "status": "reject",
  "failed_rule": "test_auth_redirect",
  "evidence": "expected 302; received 200; handlers/auth.py:88",
  "allowed_scope": ["handlers/auth.py", "tests/test_auth.py"],
  "attempt": 2,
  "next": "correct_same_unit"
}

The verdict is not a report attached after the run. It is control data. If it cannot alter the next edge, it is observability—not a gate.

Use four node roles—and do not make every role an agent

The linked article proposes splitter, worker, code node, and gate. That vocabulary is sufficient for many systems when each role has a narrow contract.

1. Splitter: turns the objective into bounded units and declares dependencies, scopes, and acceptance rules. Split by the dimension that reduces overlap—interface, blast radius, evidence domain, customer cohort, or independent document—not automatically by folder or file count.
2. Worker: produces one unit through a focused model-and-tool context. A worker should not silently acquire adjacent work or edit another worker's state.
3. Code node: performs deterministic transformations such as validation, deduplication, sorting, joining, hashing, diffing, aggregation, or policy lookup. If the transformation has one correct result and can be specified without judgment, code is usually cheaper, faster, and more stable than a model.
4. Gate: compares evidence with the acceptance and risk contract, then emits a route. Some gates are code, some combine multiple evaluators, and a small set require authorized human judgment.

OpenAI's current agent orchestration guide distinguishes model-directed orchestration from code-directed orchestration and explicitly describes structured routing, sequential chains, evaluator loops, and parallel independent work. That is the practical design choice at each node: use model judgment where the path cannot be predetermined; use code where it can.

Do not let “multi-agent” become an objective. A single worker with reliable tools may beat a graph whose nodes duplicate context, disagree without a resolution rule, and pay model cost to merge strings. Add a node only when it creates a distinct information boundary, parallel unit, control, or specialization.

Isolate worker context and return only the failed unit

Parallel workers need separate working context. If four reviewers share a live scratchpad, the first finding anchors the other three and apparent diversity collapses into repetition. Give each worker the common brief, its own unit, the relevant evidence, and its local acceptance contract. Do not stream peer conclusions into its context unless collaboration is part of the planned method.

The join node should receive structured outputs and provenance, not four uncontrolled transcripts. It can deduplicate findings, detect conflicts, and request targeted adjudication without asking a general model to reread everything.

When one of four units fails, return one unit. Returning the entire batch rewrites three accepted results, expands cost, and introduces three new sources of variance. A correction packet should include:

• stable run and unit identifiers;
• red or rejected verdict;
• failed rule and concrete evidence;
• exact files, records, or fields that may change;
• dependencies and accepted sibling versions that must remain unchanged;
• remaining attempt, token, time, and cost budget.

This is more than efficiency. Scoped correction protects already verified work. It also makes a retry idempotent and reviewable. The related guide to durable AI agent workflows covers persisted state, replay, idempotency, cancellation, and compensation when nodes can outlive a process or interact with external systems.

Build two feedback edges, but govern the learning edge

A working graph needs two different return paths.

The correction edge is short: a gate sends a rejected unit back to its producer with evidence and scope. It fixes the current run. The original article correctly emphasizes that this return should target the unit, not the batch.

The learning edge is long: a confirmed lesson becomes a candidate constraint for future splitting, routing, tools, or gates. It can prevent the same failure across later runs. For example, “adapters must preserve keyword arguments exactly” belongs in the brief used to create later porting units, not only in one worker's temporary feedback.

Production systems should not let one successful or failed run rewrite future policy automatically. Treat learning as a governed change:

observed failure → evidence review → candidate constraint → regression test → approval → versioned release

Store the source runs, applicability, owner, expiry or review date, and tests for every learned constraint. Detect conflicts with existing rules. Roll it out on historical traces and a canary population before broad use. A learning edge without this firewall can turn an outlier, evaluator bug, attack, or stale exception into permanent behavior. Our production-learning feedback firewall provides the broader promotion and rollback pattern.

Build this edge last. A system cannot learn reliably from “accepted” results until acceptance itself is trustworthy.

Give every loop multiple exit conditions

“Repeat until green” is unsafe without ceilings. Each local loop needs independent exits for:

• pass: the acceptance contract succeeds;
• attempt cap: the maximum number of corrections is reached;
• token or cost budget: the unit exhausts its allocation;
• wall-clock deadline: the result becomes too late or its assumptions expire;
• no progress: the same state, diff, or failed rule repeats across attempts;
• error threshold: consecutive infrastructure or tool failures exceed policy;
• human interrupt: an authorized operator pauses or cancels the unit;
• external event: the request is withdrawn, the dependency changes, or the objective is already satisfied elsewhere.

The linked article recommends escalating after three failed corrections because the problem may be in the plan rather than the worker. Three is a useful default for many content and coding tasks, not a universal constant. Set the cap from the cost of an attempt, expected correction rate, risk, and evidence from historical runs. More importantly, route exhaustion to replan, human_review, or failed; never convert it into an implicit pass.

Hash relevant state and compare attempts to detect cosmetic activity. A model that rewrites prose while the same test fails is busy, not progressing. Also propagate cancellation through queued children so a graph does not keep spending after its purpose disappears.

Open human gates by consequence, not model confidence

Confidence is a poor authorization signal. It may be uncalibrated, task-dependent, and generated by the same component seeking permission. The stronger question is what happens if the proposed transition is wrong.

Use at least three lanes:

This is a ZharfAI engineering recommendation derived from consequence-based risk management, not a threshold supplied by the linked post or a framework vendor. The NIST AI RMF directs organizations to assess deployment in context using relative risks, impacts, costs, and benefits, and to use human judgment when selecting metrics and thresholds.

Inside an open lane, read evidence in a stable order: deterministic results, trajectory and scope, historical rollback or escape rate for that node, independent evaluation, and model self-assessment last. Place the person where authority changes the outcome—usually approval of a consequential merge or action—not between every harmless intermediate step. The detailed pattern is in human approval design for AI systems.

Worked example: a repository-wide authentication change

Suppose an agent system must update authentication behavior across a service without changing public API responses unexpectedly.

1. Intake code node: pins the repository commit, requested behavior, permitted directories, test commands, risk lane, budgets, and cancellation key.
2. Splitter: reads dependency and ownership information, then creates units for session middleware, callback handlers, UI state, and tests. It links the UI unit to the middleware contract but lets independent test-fixture work run in parallel.
3. Workers: each receives only its unit, allowed files, interface contract, and local tests. Each runs produce-check-correct inside its node.
4. Local gates: verify tests, type checks, diff scope, secret scanning, and declared interface invariants. One failed callback unit returns with its evidence; accepted siblings remain frozen.
5. Code join: merges accepted patch artifacts against the pinned base, detects overlapping hunks and contract conflicts, and refuses an ambiguous merge.
6. System gate: runs the full suite, integration scenarios, security checks, and a graph-level policy that verifies every planned unit has exactly one accepted version.
7. Risk gate: classifies the combined change as reversible but wide because shared authentication code affects many callers. It prepares a fixed release receipt, rollout plan, rollback reference, and evidence links.
8. Human approval: an accountable maintainer chooses whether that specific release receipt may proceed. Any material change invalidates the approval hash.
9. Release and learning: rollout telemetry determines success. A confirmed interface failure may propose a new splitter constraint, but it enters review and regression testing before changing future graphs.

The graph is valuable because it protects independent work, exposes the critical path, and localizes rejection. The local loops are valuable because each unit can correct itself without a person watching every attempt. Neither replaces the other.

Persist enough state to resume and explain the path

A useful graph state is more than chat history. Persist at least:

• run, objective, requester, tenant, and cancellation identity;
• graph, policy, model, prompt, tool, schema, and evaluator versions;
• node and unit identifiers, inputs, outputs, dependencies, owners, and status;
• attempt number, budgets, deadlines, failed rules, and evidence references;
• side effects, idempotency keys, approvals, and authoritative external results;
• merge inputs, accepted artifact hashes, release receipt, and final disposition.

Checkpoint at committed transitions. Do not restore a run by asking a model to infer state from a transcript. If a worker can perform side effects, persist the intent and idempotency key before execution, then reconcile unknown outcomes before retrying.

Framework behavior varies. LangGraph's workflow and agent patterns demonstrate parallelization, orchestrator-workers, and evaluator-optimizer structures, while its persistence layer can preserve graph checkpoints. Teams still need to document the guarantees of their selected runtime, datastore, queue, and external systems.

Measure the path, not only the final answer

An output score cannot reveal whether the graph wasted work, repeated a dangerous action, hid a failed gate, or passed only after uncontrolled retries. Collect one end-to-end trace with child spans for nodes, model calls, tools, handoffs, gates, corrections, approvals, and side effects. OpenAI's Agents SDK tracing documentation is one current implementation example; use equivalent vendor-neutral telemetry if that better fits the system, and apply privacy controls to captured inputs and outputs.

Track metrics at four levels:

• unit quality: first-pass acceptance, attempts to green, evaluator disagreement, escaped defects;
• graph efficiency: critical-path latency, parallel speedup, queue time, duplicate work, merge conflicts;
• control health: gate rejection precision, false-pass rate, scope violations, approval overrides, stale approvals;
• operational cost: tokens, tool calls, wall time, retries, abandoned work, human review minutes.

Replay a fixed regression set when a prompt, model, splitter, gate, state schema, tool, or learned constraint changes. Grade trajectories as well as outcomes: which nodes ran, what evidence they saw, which tools they used, what was retried, and why the run stopped. A system that produces the right answer through an unauthorized path is not healthy.

Failure modes the diagram hides

• The friendly judge: generator and evaluator share the same blind spot, so the loop converts agreement into false assurance.
• Phantom dependency: independent nodes wait because their prompts were written in sequence.
• Context convergence: nominally independent workers see one another's conclusions and return four versions of one opinion.
• Batch rewind: one rejection causes accepted siblings to regenerate and the run stops converging.
• Agent-shaped code: a model performs deterministic merging, counting, or validation with unnecessary variance.
• Retry amplification: nested node, tool, queue, and client retries multiply one failure into excessive work or duplicate effects.
• Learning poisoning: one bad evaluator result becomes a permanent splitter or policy rule.
• Ceremonial approval: a person approves a vague summary without fixed artifacts, evidence, authority, or a rollback plan.
• Infinite polish: the artifact changes every attempt while the failed acceptance rule stays red.
• Graph success, business failure: every node passes, but the objective, user need, or release effect was defined incorrectly.

Test these conditions deliberately. Kill workers around commits, repeat events, corrupt one unit, create conflicting patches, expire approvals, cancel mid-fan-out, force an evaluator disagreement, and replay historical traces under the new graph.

A staged way to build the system

Start with one repeated, bounded workflow that already has a clear result and expensive manual inspection.

1. Write the acceptance and terminal conditions before changing the automation.
2. Draw the current units and delete edges that carry no data or decision.
3. Replace deterministic model work with code nodes.
4. Add local correction to one low-risk unit with strict scope and a small attempt budget.
5. Persist identifiers, versions, verdicts, evidence, and side effects.
6. Parallelize only proven-independent units, then add an explicit join contract.
7. Add consequence lanes and one meaningful approval boundary.
8. Compare path, quality, cost, and intervention metrics with the previous process.
9. Introduce governed learning only after the gates and regression suite are trusted.

Do not begin with a fleet. Begin with a gate that can fail loudly and a state record that can explain why. The production milestone is not “the agents ran without us.” It is “the system completed bounded work, rejected invalid units, stopped within budget, preserved evidence, and asked a person only for the decision that required human authority.”

Production readiness checklist

Before release, confirm:

1. Does every node have typed input, output, scope, owner, budget, and terminal states?
2. Does every edge carry a named dependency, decision, or event?
3. Can each gate emit accept, correct, escalate, cancel, or fail with evidence?
4. Are deterministic transformations implemented outside the model?
5. Do parallel workers have isolated context and conflict-safe state updates?
6. Does a rejected unit return alone while accepted siblings remain immutable?
7. Are attempt, cost, time, no-progress, error, interrupt, and external-event exits enforced?
8. Are side effects idempotent, authorized, reconcilable, and compensable where possible?
9. Is the human gate based on consequence and bound to a fixed artifact hash?
10. Are learned constraints reviewed, regression-tested, versioned, and reversible?
11. Can the graph resume from persisted state without replaying completed effects?
12. Do evaluation and tracing reveal the actual trajectory, not just the final output?

If a required answer is no, keep the lane closed. A loop without a real gate is repetition. A graph without scoped state and consequence controls is only a faster route to unverified work.

Source notes — reviewed August 30, 2026

The linked X article supplies the loops-and-graphs framing and practical heuristics. The architecture, control rules, and readiness checklist above are ZharfAI analysis cross-checked against current primary or official documentation.

• Hanako, “Loops and Graphs”: source article and terminology covered in this guide.
• Anthropic, “Building effective agents”: prompt chaining, routing, parallelization, orchestrator-workers, evaluator-optimizer loops, and stopping conditions.
• Google Agent Development Kit workflow agents: explicit sequential, parallel, and loop control-flow structures.
• LangGraph Graph API: state, node, edge, branching, parallel, and loop semantics.
• LangGraph workflows and agents: orchestration pattern examples and model-versus-workflow distinction.
• OpenAI Agents SDK orchestration: model-directed and code-directed orchestration patterns.
• OpenAI Agents SDK tracing: end-to-end workflow, model, tool, handoff, and guardrail trace structure.
• NIST AI RMF 1.0: contextual risk, impact, human judgment, and trustworthiness guidance.