« Phase 01 README · Warmup · Deep Dive · Principal Deep Dive · Core Contributor · Staff Notes

Phase 01 — Hitchhiker's Guide

30-second mental model

An agent is while not done: proposal = model(scratchpad); execute. ReAct interleaves (one LLM call per step, adaptive, quadratic tokens). ReWOO plans once + solves once (two calls, cheap, blind to surprises). Plan-execute-replan is ReWOO that re-plans on failure. The three are points on the adaptivity ↔ cost axis; pick per task. Guards (max_steps), the parse boundary, and errors-as-observations are what make the loop production code.

The numbers to tattoo on your arm

NumberMeaning
ReAct llm_calls == stepsone model call per step (the quadratic-cost source)
ReWOO llm_calls == 2planner + solver, regardless of tool count
plan-execute llm_calls == 1 + replansyou pay only when you recover
max_stepssafety guard, not a target — set from the reliable budget + margin
exact #E1 ref → keep the typeint stays int, or the next tool breaks

Framework one-liners

  • LangGraph — StateGraph: nodes (model/tool), edges (control), persisted state. ReAct and plan-execute are both templates; a re-plan edge = plan-execute-replan.
  • OpenAI Agents SDK — Agent + Runner.run() is the ReAct loop; handoffs route between agents; guardrails validate in/out.
  • Google ADK — LlmAgent for reasoning; SequentialAgent/ParallelAgent/LoopAgent compose deterministic workflow structure around it.
  • All of them — sugar over parse → dispatch → observe → repeat.

War stories

  • The agent that "hung." No max_steps. A confused policy proposed the same search forever; the process pinned a CPU and drained the token budget until someone killed it.
  • The 6× bill on a research agent. Pure ReAct re-reading a growing scratchpad. Switching the independent-lookup phase to a ReWOO fan-out (2 calls, parallel tools) cut cost and latency.
  • The crash on a rate limit. A tool raised on HTTP 429; the whole run died. Wrapping dispatch to return the error as an observation let the agent back off and retry (idempotently).

Vocabulary

ReAct · ReWOO · plan-execute-replan · scratchpad · policy (injected model) · ToolError / error-as-observation · variable substitution (#E1) · planner / solver · max_steps / max_replans · stopped_reason.

Beginner mistakes

  1. No max_steps guard (infinite loop).
  2. Letting a tool exception crash the loop instead of observing it.
  3. Stringifying an exact #E1 reference so the next tool gets "6" not 6.
  4. Defaulting to ReAct for everything (pay per step even when the path is known).
  5. Thinking the ReWOO planner sees observations (it doesn't — that's the name).
  6. Testing against a live model, so tests are flaky and test the model, not your loop.