docs/loop-vs-langgraph.md

metadata

kind: comparison
compared:
  - agent/loop.py
  - agent/graph.py
date: 2026-07-06T00:00:00.000Z
verdict: >-
  manual loop for now; LangGraph when checkpointing / parallelism /
  human-in-the-loop arrives

Manual loop vs. LangGraph — same agent, two control flows

Both implementations drive the identical three tools (search_docs, read_page, ask_source), the same planner prompt, the same budgets (6/2/1), and end in the same answer_from_sections. Only the control flow differs: a Python while loop vs. an explicit StateGraph.

Numbers

	agent/loop.py	agent/graph.py
Code lines (non-comment)	90	98
External dependency	none (stdlib)	langgraph
State	local variables in one function	a TypedDict threaded through nodes
Control flow	for step in range(MAX_STEPS) + if/elif	nodes + a conditional edge (_route)

LoC is nearly identical — the graph's node signatures and explicit state dict cost ~8 lines over plain locals. At this size the manual loop is slightly smaller and has zero dependency.

Debuggability

• Manual loop: a stack trace points at the exact line; you can drop a print/breakpoint anywhere and read the local transcript. Nothing between you and the code. Easiest to reason about at this scale.
• LangGraph: the flow is inspectable as data — you can render the graph, and (with a checkpointer) replay a run node-by-node. That visibility is worth little for a 3-node graph but grows with complexity.

Latency

Both make the same LLM calls (one planner call per step + one final generation), so wall-clock is dominated by the network, not the framework. LangGraph's per-node overhead is microseconds — immeasurable next to a free-tier LLM call that can wait 30s on a rate limit. No practical difference.

When LangGraph earns its dependency

Nothing in this agent needs a graph — which is exactly why the manual loop is the default. LangGraph becomes the right tool the moment we add any of:

• Checkpointing — pause a run and resume after a restart (multi-turn sessions, long jobs). The manual loop would have to serialize its locals by hand; LangGraph gives it for free.
• Human-in-the-loop — interrupt before an action (e.g. approve running code) and continue. A native graph feature; a manual bolt-on otherwise.
• Parallel fan-out — run several search_docs queries concurrently for a recipe question. Natural as parallel edges; awkward in a linear loop.

Verdict

Ship the manual loop (agent/loop.py): fewer lines, no dependency, trivially debuggable, same behavior. Keep agent/graph.py as the drop-in upgrade — identical tools and prompt — for when checkpointed sessions, approval steps, or parallel retrieval arrive. Building it twice proved the control flow is understood, not delegated to a framework on faith.