The words, by analogy · AI Agent Loops and Graphs: Novice to Ninja

In this appendix, we will learn nothing new and understand everything better. Every term the book uses is here, with a one-line meaning and a picture to hang it on. Read it once straight through before Part II if the vocabulary is new to you, and come back to it whenever a word stops you. The pictures are the newsroom's where the newsroom has one, and everyday ones where it does not.

Models and tokens

Term	Meaning	Picture
model	the program that reads a prompt and writes a reply, one token at a time	the reporter's brain: the same brain whether it is on the phone or in the building
token	the unit a model reads and writes in; a piece of a word, about four characters	column inches: the paper pays for every one, news or filler
prompt tokens, completion tokens	what goes in and what comes out of one call, counted in tokens	the brief you hand over, and the copy that comes back; you pay for both, and the brief gets longer every round
reasoning tokens	completion tokens the model spent thinking before answering	the scribbled notes before the clean copy; billed like copy
prompt	everything the model is shown before it answers	the whole desk the reporter looks at: the job description, the notes, the assignment
system prompt	the standing part of the prompt: who the agent is, how to behave	the job description pinned above the desk
context	the material for this one job: documents, files, remembered facts	the folder of clippings handed over with the assignment
context window	the most tokens one call can carry	the size of the desk; past it, things fall off
temperature	the randomness dial; 0 picks the most likely word every time	a careful clerk at 0, a brainstormer at 1
reasoning effort	how long the model thinks before answering	a quick note versus a considered memo; the memo costs more
model API, endpoint	the service over the network that runs the model; the address it listens at	the phone network and the number you dial
SDK	the official library for talking to the model API from code	the phone app that knows how to dial
API key	the secret that proves to the API who is calling and who to bill	the account number on the phone contract; never printed in the paper
environment variable	a setting kept outside the code, read when the program starts	a label on the switchboard saying which number to dial
worker, judge, specialist	the three model roles: does the work, grades it, handles one hard step	reporter, editor, the expert called in for one story
structured output	asking the model for an object matching a schema instead of prose	a form with boxes instead of a letter
streaming	receiving the answer word by word as it is produced	watching the wire service tick in versus reading the finished page

The loop

Term	Meaning	Picture
agent	a model plus tools, a loop, an evaluator and a place to work	a reporter with a badge, a desk and an editor, not a voice on the phone
loop	prompt, model, action, result, again, until an evaluator says pass	a reporter chasing a story until the desk accepts it
step	one model call inside a loop	one round of thinking at the desk
history, messages	the list of everything said so far, sent in full on every call	the growing folder the reporter carries to every meeting
action, result	a tool call the model asks for, and what the tool returned	making a phone call, and the note of what was said
evaluate	something other than the model deciding whether the answer is final	the editor's desk
pass, fail, feedback	the evaluator's verdict and, on a fail, the note that goes back to the model	"run it", or "back to you, and here is why"
status	how a run ended: pass, fail, max_steps, budget, error	the stamp on the folder when it leaves the desk
max_steps, max_fails	ceilings on tool rounds and on rejected answers	"three hours and two rewrites, then we run what we have or spike it"
trace	the file where every event of a run is written, one JSON line each	the archivist's log of every call made and every note filed
runaway, flailing	a loop that calls tools without end; a loop that tries many things and gets nowhere	a reporter who keeps phoning the same number; one who phones everyone and files nothing
context bloat, context rot	a history that grows until every call is expensive; a model that attends less to the middle of a long history	a folder so thick the reporter cannot find the brief; and skims the middle
compaction	shortening old tool results in the history while keeping the gist	the sub-editor trimming old notes to a line each
prompt injection	instructions hidden in text the model reads, which it may follow	a forged note slipped into the clippings folder

Tools

Term	Meaning	Picture
tool	a function the model may ask to run, described by a name, a description and a schema	a door the badge opens
signature	a function's name and its typed arguments	the label on the door and the shape of its key
docstring	the explanatory text under a function's first line	the sign on the door saying what is behind it
schema, JSON schema	the shape of a piece of data: fields, types, which are required	a form with labelled boxes
JSON	the bracketed text format programs use to exchange data	the standard form every desk can read
JSONL	a file with one JSON object per line	a ledger: one entry per line, searchable
regex	a pattern that matches text	a search with wildcards: "only digits", "ends in .json"
parser, parse	code that reads a format and complains if it is malformed	the clerk who rejects a form with the boxes filled in wrong
confinement, work directory	tools may only touch files under one folder	the badge opens doors on one floor
shell, subprocess	running another program and reading what it prints	sending a runner to another department and reading the note they bring back
exit code	the number a program leaves behind; zero means success	the runner's thumbs up or down
timeout	the longest a tool may run before it is stopped	"if you are not back in an hour, we go without you"
glob	a filename pattern with wildcards	"every folder marked 2026"
grep	search files for lines matching a pattern	flipping the archive for every page that mentions a name
container, sandbox	a sealed environment a program cannot see out of	a locked room: break what you like, it stays in the room
allow-list	the set of things permitted; everything else is refused	the guest list at the door
human in the loop, approval	a person must say yes before a tool that acts can run	legal signs off before anything risky goes out

Evaluators

Term	Meaning	Picture
deterministic check	a test a program runs with the same answer every time, free	the byline-and-word-count checklist a junior runs in a minute
judge	a second model reading the answer against a rubric and scoring it	the senior reader
rubric	a written marking scheme the judge applies	the teacher's grading sheet; a literal reader applies it word for word
threshold	the judge score at or above which an answer passes	the pass mark
all_of	run evaluators in order; stop at the first fail	checklist first, senior reader only for copy that passed it
verdict	passed or not, feedback, score	the editor's note on the top of the copy
validator, contract	a deterministic check with many rules; the rules the output must meet to be accepted	the printer's proof: either it prints or a page goes back
grounding	putting the source material in the prompt and requiring facts to come from it	"quote the document in front of you, not what you remember"

Graphs

Term	Meaning	Picture
graph	nodes and edges: steps, and which may follow which, fixed in advance	the desk's plan for the day, written down
node	one step: a function of the state that returns new keys	one person's job on the plan
edge	"when this finishes, that may start"	an arrow on the assignment board
state	the shared dictionary of everything the graph knows so far	the whiteboard everyone writes their results on
key	one named value in the state	one labelled box on the whiteboard
wave	all the nodes whose inputs are ready, run at the same time	the morning meeting sending several reporters out together
snapshot	a copy of the state taken before a wave starts	a photograph of the whiteboard before the meeting
thread	how a program does several things at once	several reporters out at the same time
fan-out, fan-in	one node feeding several; several feeding one that waits for all	assigning three angles; the rewrite editor waiting for all three
map, fanout node	the same work for every item in a list, in parallel	one reporter per town for the election results
router	a function of the state that returns a label; the label picks the next node	the news editor reading the wire and deciding which desk gets it
back edge	an edge that closes a cycle; it re-triggers its target but is not waited for	the return path when legal bounces a piece
dependency	an input a node waits for	"rewrite cannot start until all three have filed"
depth-first search	follow each arrow as far as it goes before trying the next	walk one corridor to its end before opening the next door
cycle, max_visits	a path that returns to a node; the ceiling on how often a node may run	the rewrite loop, and "three rewrites, then we decide"
state collision	two nodes in one wave writing the same key	two reporters filing into the same slot
stall	a graph that stops early with no error because a node waits for an input that cannot come	a page that never prints because it waits for a sign-off that waits for the page
sub-graph	a whole graph used as one node of another	a desk inside a desk
stub node	a placeholder function that returns its own name, for testing the shape	a rehearsal with the actors reading their names
checkpoint, resume	the state saved after every wave; a rerun that skips finished nodes	the proof sheet saved after each page, so a crashed press restarts at the right page
retries, on_error	re-running a node that failed; jumping to a fallback node when it raises	redialling, and the backup reporter
text form	the six-line notation (`a -> b, c`, `a ?label-> b`) that builds a graph	the assignment board itself as the plan
Mermaid, excalidraw	two drawing formats the graph exports to	the clean org chart and the hand-drawn whiteboard

Plugins and memory

Term	Meaning	Picture
plugin, hook	an object with named methods the loop and graph call at known moments	the people around the reporter who see everything and write nothing
Trace, Console	write every event to a file; print one line per step	the archivist; the editor shouting progress across the room
Budget	stop a run that spends or steps too much	the managing editor pulling the plug
Compact	shorten old tool results in the history	the sub-editor trimming old notes
Approval	guarded tools run only if a policy or a person says yes	legal's sign-off
skill	a markdown page of standing instructions appended to the system prompt	the style guide on every desk
memory framework, backend	software that stores facts from conversations and finds them later; the six-method interface agl talks to it through	the archive, and the archivist's counter
mem lib	the small memory backend agl ships	a one-room archive with a good index
recall, remember	fetch relevant facts before a run; extract and store facts after one	pulling the clippings before; filing the story after
extraction	a model call that turns a conversation into short dated facts	the archivist deciding what is worth clipping
keyword search, full-text index	finding facts by the words they contain	the index at the back of a book
embedding	numbers that place similar meanings near each other	a librarian who understands what you meant
user id, scoping	every fact stored under one person or project, every search limited to it	one archive drawer per client, locked
semantic, episodic, procedural	facts about the world; what happened when; how to do things	the clippings, the diary, the style guide
token budget	the most tokens of recalled facts allowed into the prompt	"one page of clippings, no more"

Measuring

Term	Meaning	Picture
measurable	a program can print one number after every attempt, and better moves it the right way	the sports desk: there is a score
open-ended, closed	the model picks what to try; we pick	"find me a story" versus "cover these three events"
exam, eval	a file of tasks with expected answers, graded the same way every time	the daily edition, checked
task, expect	one exam row: the text, the allowed tools, the checks	one assignment and its acceptance criteria
score, pass rate	mean task score; share of tasks that passed	the grade, and how many pages printed clean
latency, p50, p95	the wait for an answer; the typical wait; the wait the unlucky one in twenty sees	how long the reader waits for the paper, on a normal day and on a bad one
wall clock	real elapsed time, as a clock on the wall would show	the deadline clock, not the hours worked
noise, margin	run-to-run variation; the change required before a difference counts	the same edition is never quite identical twice; a real improvement shows past that
cache (for measuring)	exact replay of an identical run, for free	re-reading yesterday's edition instead of reprinting it
fixture	a frozen file the exam's expectations are pinned to	the reference copy in the vault
results log	one row per run: commit, score, cost, verdict, description	the lab notebook
commit, version control	a saved, named snapshot of the code; the system that keeps them all	the bound archive of every edition as printed
lint, tests	a program that checks code style; programs that check code behaviour	spelling check and fact check for code
improvement loop, brief	an agent that changes one thing, runs the exam, keeps or discards, logs, repeats; the file that tells it how	the night desk and its standing orders
scope, gate, log	what the loop may edit; what must pass before a run counts; one row per run	the night desk may touch tomorrow's pages but not the stylebook; nothing prints unchecked; every change in the log
simplicity criterion	equal results with less code wins	a shorter story that says the same is the better story

Shipping

Term	Meaning	Picture
HTTP, POST, GET	the web's request language; sending a document; asking for one	the mail room: a parcel out, a request for one back
serve, service	a program that waits for requests and answers them	the counter that never closes
localhost	this machine only; nothing from outside can reach it	an internal extension, not a public number
authentication, rate limit	proving who is calling; capping how often they may	the badge at the door; the queue
staging	where generated work waits before it is published	the proof table before the press
review before publish	a gate between generating and going live	nothing reaches the press without the editor's initials
deploy, release	putting a new version of the service into use	the edition going to press

Try it yourself

Pick ten terms from this appendix and write your own picture for each, from your own work rather than a newsroom. Then reread one chapter from Part III with your pictures in mind. The words that still stop you are the ones to look up in the code: every term here names something in agl you can open.

Common questions

Why a newsroom for everything?

One analogy, used consistently, is worth more than ten clever ones: once the reporter, the desk, the editor and the archive are fixed in your mind, every new term has a place to go. Where the newsroom has no picture, we used an everyday one and said so.

Are these definitions exact?

They are exact enough to read the book and the code. A token is not always four characters; a thread is more subtle than "several things at once". The chapters give the precise version where it matters; the picture is for remembering.

Which ten terms matter most?

Token, prompt, evaluator, rubric, state, wave, router, back edge, trace and exam. Know those and the rest follow.

Where are the words defined in code?

Tokens and cost in agl/llm.py; the loop's words in agl/loop.py; tools in agl/tools.py; the graph's words in agl/graph.py; plugins in agl/plugins.py; memory in agl/memory.py and agl/memlib.py; the exam in agl/eval.py.

Carry this

Tokens are column inches; the paper pays for every one, and the brief gets longer every round.
The loop is a reporter; the evaluator is the editor; the graph is the desk's plan; the state is the whiteboard.
A deterministic check is the junior's checklist; a judge is the senior reader; the rubric is the grading sheet.
Memory is the archive: pull the clippings before, file the story after, one drawer per client.
The exam is the daily edition; the improvement loop is the night desk; scope, gate and log keep it honest.

Check yourself

1. In one picture each: token, wave, back edge.

Answer

A token is a column inch the paper pays for; a wave is the morning meeting sending several reporters out at once; a back edge is the return path when legal bounces a piece.

2. What is the difference between a deterministic check and a judge, in newsroom terms?

Answer

The check is the junior's byline-and-word-count checklist, free and the same every time; the judge is the senior reader with a grading sheet, paid per read, and only shown copy that passed the checklist.

3. Why does a cache have to miss when one word of the question changes?

Answer

Because a cache is honest only for an identical question; serving yesterday's clipping for a different story would be a wrong answer dressed as a fast one.