From chatbots to agents

In this chapter, we will learn what an agent is, precisely enough to build one. You have used chatbots and probably an agent or two. We will name the four things an agent has that a chatbot does not, climb the five-rung ladder from prompt engineering to graph engineering, and read the whiteboard that this whole book follows. By the end you will be able to say in one sentence what a loop is, what a graph is, and why the order matters.

Same model, different access

An agent is a model plus tools, a loop, an evaluator, and a place to work. The model is the same one you chat with; everything around it is new. Put a chatbot and a coding agent side by side and the model is the least interesting difference.

Each row is a thing you build. Tools give the model hands. The loop lets it act, look, and act again. The evaluator decides when it is done, so the model does not decide that for itself. The place to work, a folder with a brief and a memory, is what makes the same agent useful on Tuesday that was useful on Monday. In code, these are four arguments to one constructor:

from agl import LLM, Loop, Toolbox, check, default_plugins
from agl.std_tools import read_file, grep, shell

loop = Loop(
    LLM(),                                   # the model
    tools=Toolbox(read_file, grep, shell),   # what it can do
    evaluate=check(lambda a: a.strip().isdigit() or "reply with only the number"),   # who says it is done
    plugins=default_plugins(),               # trace, console, budget: the place to work
)
result = loop.run("How many lines does agl/loop.py have, times 7? Reply with only the number.")

Take away the tools and it is a chatbot with a loop. Take away the evaluator and it is a chatbot that calls tools until it feels like stopping. Take away the loop and it is a chatbot. We will build each piece in Part II.

Three sentences to hold

The unit of design is no longer the prompt. It is the loop around the prompt, and then the graph around the loops. Three short lines from people who build agents for a living say it faster than a chapter can.

@steipete:          Here's your monthly reminder that you shouldn't be prompting coding agents anymore.
                    You should be designing loops that prompt your agents.
@steipete:          Are we still talking loops or did we shift to graphs yet?
@sean_ai_stories:   a loop discovers what to do next. a graph pre-determines what happens next.

The first says where the work is: in the loop, not the prompt. The second says the loop is not the end. The third is the cleanest definition of the difference we know, and it is the spine of this book: a loop lets the model decide at run time what to do next; a graph fixes the order in advance and lets the model work inside each step.

The ladder

Agent engineering is a ladder of five rungs, and each rung keeps the ones below it.

rung 5   GRAPH engineering     several loops in a fixed order, some in parallel, with a reviewer
rung 4   LOOP engineering      prompt -> model -> action -> result -> evaluate -> again
rung 3   SKILLS                standing instructions, "how we do this here", in files the agent reads
rung 2   CONTEXT engineering   put the right facts and documents in front of the model
rung 1   PROMPT engineering    phrase the question well

Rung 1 is where everyone starts: "explain like I am five" and "answer in JSON" change the output (JSON is the bracketed text format programs use to pass data to each other; asking for it means asking for an answer a program can read, not a paragraph). Rung 2 is the discovery that the model is only as good as what it can see, so you paste in the document, the error log, the schema. Rung 3 is writing down how your team wants things done, once, in a file the agent reads every time. Rung 4 is the jump: instead of asking once, you let the model act, look at what happened, and ask again, with a check at the end. Rung 5 is the realisation that when you already know the order of the work, you should not make the model rediscover it on every run.

This book is rungs 4 and 5, with rung 3 as a tool you will use constantly. It assumes you have done rungs 1 and 2 by using agents.

The whiteboard

This book follows one drawing, made for a class on loop engineering and graph engineering. It is rendered below from its original file. Step through the boards now. You do not need to understand them yet; the point is to see the shape of the argument before we take it apart.

The code behind the book

agl is a small Python library that implements every board, and it is the worked example of every chapter. Its name stands for agentic graph loop. It is open source, it uses the OpenAI SDK against any model API, and it is about 1,200 lines, split so that each idea lives in one file.

agl/llm.py       one client for every model call: tokens, dollars, milliseconds, cache, retries
agl/tools.py     a Python function becomes a tool the model can call
agl/loop.py      THE LOOP: prompt -> LLM -> action -> result -> evaluate -> final       (Part II)
agl/graph.py     THE GRAPH: nodes, edges, routers, waves, state                         (Part III)
agl/plugins.py   hooks around the loop: trace, console, budget, skills                  (Part IV)
agl/memory.py    long-term memory behind a small backend interface; mem lib ships     (Part IV)
agl/eval.py      the exam you write for your own agent                                 (Part IV)
agl/viz.py       draw a graph as Mermaid or excalidraw; replay a run                    (Part III)

A few words in that table will be new. A token is the unit a model reads and writes in: a piece of a word, about four characters on average, so 'graph engineering' is about four tokens. Models are billed per token, which makes tokens the newsroom's column inches: the paper pays for every one, whether it carries news or filler. The OpenAI SDK is the official Python library for talking to a model over the network, the way a phone app talks to the phone network, and a model API is the service on the other end that runs the model. A cache is a saved copy of an answer so the same question is not paid for twice.

Why so small? Because you have to read it, and because every line we did not write is a line that cannot hide a bug. When a chapter names a file, open it next to the page. Every example in the book is a template: the course builder in Part V writes books; change the output contract and the same shape writes reports, reviews code, or triages tickets.

Who this book is for

You, if you have used agents and want to build them, and want to trust what you built. Our running student is Priya. She is building an interactive course app. She wants a program that can take a topic, or a PDF, and write a course from it, and she wants to be sure of the result before a student sees it. She builds a loop in Part II, a graph in Part III, and ships the course builder in Part V. Every chapter ends with her applying the idea to her app, so that you can apply it to yours.

Try it yourself

Step through every board of the whiteboard. Write one sentence for the loop board and one for the graph board. Keep them. After Part II and Part III, compare. Then find the one arrow on the loop board that points backwards. Everything about loops is in that arrow.

Common questions

Is a loop just a chatbot that calls itself?

Almost. The difference is the boxes after the model: Action and Result, where the model does something and sees what happened, and Evaluate, where something other than the model decides whether to stop. A chatbot has neither.

If graphs are better, why learn loops first?

Because a graph is made of loops. Every node that does real work in a graph is a loop or a plain function. You cannot design the desk without knowing what a reporter does.

Do I need to know Python?

You need to read it. The library is written to be read: short functions, plain names, comments where a decision was made. If you can follow a recipe you can follow agl/loop.py.

Which model should I use?

Any model with tool calling, through any OpenAI-compatible API. The book names models by role: a worker, a judge, a specialist. Chapter 7 shows how to choose them by measurement rather than reputation.

Is this book about a particular vendor's agent product?

No. It is about the loop and the graph, which every agent product implements somewhere inside. agl is small enough to show them bare.

Carry this

• An agent is a model plus tools, a loop, an evaluator and a place to work. The model is the same.
• Design loops that prompt your agents; then ask whether you need a graph.
• A loop discovers what to do next. A graph pre-determines what happens next.
• Five rungs: prompt, context, skills, loop, graph. This book is rungs 4 and 5.

Check yourself

1. Name the four things an agent has that a chatbot does not.

Answer

Tools (it acts and sees results), a loop (it acts again), an evaluator (something else decides when it is done), and a place to work with standing instructions and memory.

2. In one sentence, what is the difference between a loop and a graph?

Answer

A loop lets the model decide at run time what to do next, step by step; a graph fixes the order of steps in advance and lets the model work inside each step.

3. Which rung of the ladder do skills belong to, and what are they?

Answer

Rung 3: standing instructions on how work is done here, kept in files the agent reads on every run.