cCarebun Reading‹ All reading
Carebun Interactive/Agents whiteboardpattern catalogueglossary Study view

An interactive textbook

AI Agent Loops and Graphs
Novice to Ninja

Loop engineering and graph engineering for people who have used agents and want to build them: loops first, then graphs, then real problems. One small open-source library, agl, is the companion code.

Start readingOpen the whiteboard

19 chapters · about 3.4 hours · 6 interactives · no background needed

The library behind the book

agl

One loop. One graph. Everything measured.

agl is a small Python framework for AI agents: the OpenAI SDK against any model API, a loop you can read on one page, a graph engine that runs in waves, a memory plugin, hooks for everything else, and an exam you write for your own agent. About 1,200 lines. This book explains every one of them and shows how to bend them to your own problem.

Pick a problem shape and see the graph that fits it, in the six-line text form the library reads. Every pattern in the picker is built in Part III and applied in Part V.

How to read this book

  1. In order. Loops before graphs. Each chapter uses only what the earlier ones taught.
  2. With the code open. When a chapter names a file, open it: agl/loop.py is one page.
  3. With your hands. Step the loop, type a graph, pick a pattern before you read on.
  4. With your own problem in mind. Every example is a template. Part V shows five problems mapped to graphs; the sixth is yours.

Part I · Foundations

What an agent is, which problems suit a loop, and the anatomy of one.

01From chatbots to agentsWhat changes when a model gets tools, a loop and an editor: the four things an agent has that a chatbot does not, the five-rung ladder, and the whiteboard this book follows.9 min · interactive02Which problems suit a loopThe first question to ask before building any agent: can a program print one number after every attempt? Measurable versus non-measurable, open-ended versus closed, and how to make a vague task measurable enough to loop on.9 min · interactive03Anatomy of a loopThe seven boxes on the whiteboard, the two cycles hidden in them, how a loop ends, and a step-through of one real run where you can watch the prompt grow.10 min · interactive

Part II · Building loops

Your first loop, tools, evaluators, models and cost, and the problems every loop hits.

04Your first loopInstall agl, make one client, one loop, one tool and one check, run it, and read agl/loop.py line by line so that every arrow on the whiteboard has a line of code.11 min05ToolsA typed Python function becomes a tool the model can call; errors go back as text instead of raising; paths are confined; and the way to steer a model is to design narrow tools with good first lines.10 min06EvaluatorsThe box that makes a loop a loop: deterministic checks, model judges with rubrics, cheap checks before expensive ones, feedback written for the model, and why the judge must never be the worker.11 min07Models, tokens and costOne client for every model call, why prompt tokens dominate, three model roles and how to pick them by measurement, reasoning effort, caching, structured output, and the budgets that stop a bill.11 min · interactive08Loop problems and fixesThe eight ways a loop goes wrong, each with the symptom you will see in a trace, the cause, and the fix in code: runaway, flailing, tool errors, context bloat, format drift, invented facts, injection through tools, and non-determinism.12 min

Part III · Building graphs

Why graphs, how the engine runs them, how to draw and design one, and the problems graphs hit.

09Why graphsA loop discovers what to do next; a graph pre-determines it. When to reach for a graph, the seven patterns you will reuse, their industry names, and the shape of the whiteboard's graph board as code.11 min · interactive10The engineagl/graph.py: nodes are functions of a shared state, edges say what may run next, ready nodes run together in waves and write disjoint keys, routers pick a path at run time, and errors are recorded, never raised.11 min · interactive11Drawing and designing a graphThe diagram is the code: a six-line text form, back edges that jump instead of waiting, map nodes for run-time width, sub-graphs, export to Mermaid and excalidraw, and a design method that starts from the output contract.11 min12Graph problems and fixesThe seven ways a graph goes wrong, each with its symptom, cause and fix: no merge node, a literal judge, a graph that stalls, a cycle that never ends, two nodes on one key, a node that dies, and judges that cost more than workers.11 min

Part IV · Around the loop

Plugins and tracing, memory, and the exam that keeps your agent honest.

13Plugins, tracing and skillsEverything around the loop is a hook: Trace writes every event, Console prints it, Budget stops a runaway, Compact keeps the history short, Approval puts a person in the path, and Skills turn markdown pages into standing instructions.10 min14MemoryHow a loop remembers across runs: a memory framework behind a six-method interface, recall before and remember after, the two tools, scoping by user, what not to store, and how to test memory on its own.10 min15Evals and the improvement loopWrite an exam for your own agent: tasks as JSON lines, cheap checks then a judge, one grep-able summary, a results log with the commit. Then the autoresearch pattern: a brief that lets an agent improve your project overnight, kept honest by scope, gate and log.12 min

Part V · Real world

A full case study, five problems mapped to five graphs, and shipping.

16Case study: a course from a topicPriya's course builder end to end: the output contract, one writer loop per chapter with a validator, the site's real build check as the last node, a repair path, grounding in a source or a PDF, and a content judge. Every idea in the book, used at once, as a template.12 min17Five problems, five graphsResearch assistant, support triage, code-review bot, document extraction pipeline, weekly report writer: each as a graph in the text form, with its evaluators, where memory goes, and what breaks first. Templates for the sixth problem, yours.12 min18ShippingServing loops and graphs over HTTP, the safety checklist for an agent that runs without you, review before publish, the exercises, and the whole book on one whiteboard, cold.10 min

Appendix

Every term in the book, explained by analogy.

19The words, by analogyEvery technical term in the book, each with a plain meaning and a picture from everyday life or the newsroom, grouped the way the book is: models, the loop, tools, evaluators, graphs, plugins and memory, measuring, shipping.12 min