Glossary
Every term the course names, in two plain sentences, in the course's own words.
Each entry says which lesson earns the term. The lessons never use a name before you have built the thing it names, so if a definition here reads as abstract, that lesson is where it turns concrete. Where Tau, the reference implementation, has its own name for the same thing, the entry gives it, with a link to the exact lines at the commit this course is pinned to.
Three entries are the invariants the whole course hangs on: I1, I2 and I3. A sentence marked [general] describes how model providers usually behave; it is not something your code, or Tau's, guarantees.
A
- aborted
- The stop reason of a reply that ended because someone pressed Stop. After a cancel, your loop writes one in-band assistant message carrying it at the top of the next turn and ends the run, so no paid request follows a Stop.
- adapter
- The one part of the program that knows a vendor: two pure translations, one from your messages into the vendor's JSON and one from the vendor's stream back into a single assistant message. The object that owns the socket is built from those two and offers the same
acomplete(system, messages, tools, signal)as the fake model, which is why no line of the harness changes. - agent
- A model call inside a
whileloop that runs the tools the model asks for and sends the results back. The model steers; the loop only turns. - agent loop
- The loop in
run_agent: call the model, run the tool calls in its reply, append the results, call again. It continues if and only if the reply contains tool calls, and it keeps no state of its own: the caller's list is the product. - append-only
- Lines are added to the end of the session log and never edited or removed. A crash can then damage at most the last line, and everything before it is still exactly what happened.
- await
- Shareable waiting: while one piece of code waits on the model or a tool, other code, such as a Stop button's handler, gets to run. A plain generator gives the floor away between events and never inside one, which is why lesson 15 needs it.
C
- call id
- The
idon a tool call, repeated astool_call_idon the result that answers it. It is how the model tells which result belongs to which call when one reply asks for several. - cancellation token
- A small object with
cancel()andis_cancelled(), made fresh for every run and handed to the model call and to every tool assignal. Cancelling only sets a flag; nothing stops until slow code looks at it. - colour rule
- A function is
asyncif and only if it waits, directly or through something it calls, on the model or a tool. It is the one rule that turns the lesson 14 file into the lesson 15 file without changing its design. - compaction
- What happens when the transcript nears the context window: the old messages are summarised, the recent ones are kept word for word, and one entry recording the summary and the id of the first kept message is appended to the log. Nothing is deleted; replay now reads the log as summary, then kept tail, then later messages.
- consumer
- Whatever code iterates a run's events: a renderer's loop, a test, a web handler. It sets the pace, because the loop is suspended while the consumer handles an event, and it can walk away by closing the run.
- content block
- One item in an assistant message's
contentlist:{"type": "text", ...}or{"type": "toolCall", ...}. The list is ordered, so prose and calls stay in the order the model wrote them. - context file
- A file of standing project instructions,
AGENTS.md, collected from the top of the workspace down to the working directory and placed in the system prompt with its path. Whoever wrote that file is writing part of your system prompt. - context window
- The most tokens a model accepts in one request. [general] Past it a provider answers with an error such as
prompt is too longinstead of a reply; the lab's model has a window of 2,000 tokens so that you can hit the wall quickly. - cooperative cancellation
- Stopping a run by asking:
cancel()sets the token, and each slow piece (the top of a turn, the tool boundary, thebashtool's poll loop) checks it and stops itself. It leaves a valid record, and it cannot stop code that never looks. - cut point
- The index at which compaction splits the log's rows into those to summarise and those to keep. It snaps forward to a turn boundary, a user message, so the kept tail never opens on a tool result whose call was summarised away.
D
- dangling call
- A tool call in the record with no result after it, left behind when a run was closed or killed mid-tool. Sent as it stands, it makes a provider reject every later request, so one bad pair can brick a whole session.
- delta
- A fragment of a reply as it streams in: a few characters of text, or a piece of the JSON string that will become a tool call's arguments. Text deltas may be shown at once; argument deltas may only be collected, and are parsed once, when the block ends.
- deny-list
- A check that blocks calls matching known-bad patterns, as
deny_destructiverefusesrm -rf. It is a speed bump, not a sandbox:rm -fr buildwalks straight past it.
E
- entry
- One line of the session log: a JSON object with an
idand atype. Lesson 11 has one type,message; lesson 12 addscompaction. - error as observation
- A tool failure is not raised at the programmer; it is returned to the model as a tool result with
is_error=Trueand a text written to help it recover. The reader who can fix the mistake is the model, so the error message is a prompt. - eval
- Running one fixed task several times against a real model and counting the successes, then changing one thing and counting again. Tests against a fake prove that the harness keeps its contract; only an eval says whether the agent is any good.
- event
- A plain dict with a
type, yielded by the loop to say what just happened:agent_start,turn_start,message_end,tool_execution_start,tool_execution_end,turn_end,agent_end. Events come in balanced pairs on every exit path and carry data only; how they look is a frontend's business.
F
- fail closed
- When the check guarding a tool crashes, the call is blocked. A check that raised has not said yes.
- fake model
- A stand-in for the model that replies from a script, so every run is instant, free and repeatable. It keeps the same contract as a real provider, which is why a harness built against it runs unchanged against the real thing; it tests the harness, never the model.
- follow-up
- A user message queued for the moment the run would otherwise end ("when you're done, run the tests"). The loop asks for one only when a reply holds no tool calls and no steering is waiting, and takes one at a time.
- frontend
- Code that turns a run's events into something for a reader: a live terminal display, one final answer, JSON lines. It is a fold over the events,
render(event)for each and thenfinish(), and the loop never learns it exists.
G
- generator
- A Python function containing
yield: calling it runs nothing, eachnext()runs it to the nextyield, andclose()runs itsfinally. It is what lets the loop hand over one event and wait until the consumer asks for the next. - guard
- A wrapper around a tool, under the same name and schema, whose
executefirst asks a check whether the call may run. A refusal is raised inside the wrapper, so the tool boundary turns it into the call's one error result, and the loop never learns a guard exists. - guideline
- A sentence of advice carried by a tool, such as
Use read to examine files instead of cat or sed.
A schema can say what a tool takes; only words can say when to use it, so the advice lives on the tool and reaches the prompt only while that tool is enabled.
H
- hard cancel
- The backstop for a tool that ignores its token:
task.cancel()raisesCancelledErrorinside theawaitthe tool is stuck in. It must pass through the tool boundary and the guard untouched, which is why the boundary catchesExceptionand nothing wider. - harness
- Loosely, everything you build around the model in this course; the file is
harness.py. Precisely, from lesson 8, theHarnessobject: it owns the one transcript and the settings that stay the same from run to run, and lets one run at a time write to it.
I
- I1: the only memory
- The first of the course's three invariants: the transcript is the only memory, and all of it is re-read and re-paid on every call. Whatever the model should know on the next turn has to be in the list, and whatever is in the list costs tokens again.
- I2: one call, one result
- The second invariant: one call in, exactly one result out, right after it. Every tool call in the transcript is followed by exactly one tool result carrying its id, whether the tool worked, failed, was blocked or was cancelled.
- I3: the record is not the view
- The third invariant: the record is not the view. Keep everything that happened; compute, for every request, what you send.
- idempotent
- Doing it twice gives what doing it once gives:
repair(repair(x)) == repair(x), and a valid history comes back unchanged. That is what makes it free to repair before every request instead of once at load. - in-band error
- A stop or a provider failure written into the transcript as an assistant message, with empty content,
stop_reason"error"and the reason inerror_message, instead of being raised. Every exit then leaves a transcript you could send again. - is_error
- The flag on a tool result that says the tool could not do its job: an unknown tool, bad arguments, an exception and, in later lessons, a blocked or a cancelled call. Bad news is not an error: a test run that exits with code 1 did its job, and comes back as an ordinary result ending
Command exited with code 1.
J
- JSON Lines
- A text file holding one JSON object per line. Appending a line never touches the earlier ones, and a torn last line is easy to detect and to name by its number.
M
- max_turns
- A cap on the number of model calls in one run, checked at the top of a turn: before the call, never after it. When it is reached the loop appends an in-band error,
Agent stopped after max_turns=N, and ends the run with every call answered. - message
- One dict in the transcript, tagged with the role that spoke. A user message holds a string; an assistant message holds a list of content blocks, a stop reason and its usage; lesson 2 adds a third shape for tool results.
- mutate, then announce
- The loop's one ordering rule: append a message to the record first, and only then yield the event that announces it, with no yield between a tool returning and its result being recorded. A consumer who stops listening at any moment has therefore never seen something the record lacks.
O
- orphan result
- A tool result whose call is nowhere in the transcript. Repair drops it instead of inventing the call: nobody knows the arguments, and an invented call is a lie the model would reason from.
- output budget
- The cap on what one tool result may bring back: 2,000 lines or 50,000 bytes in your harness. It exists because whatever a tool returns is re-read and re-paid on every later turn.
P
- persona
- A scripted model step that reacts to each request by one simple rule, printed beside the cell that uses it:
forgetful,stuck,pager,summariser,gullible. Because the rule is on the page, every reveal follows from text you can read. - prompt cache
- [general] A provider can bill the unchanged prefix of a request at a lower rate, reported in
usageascache_read. One changed byte near the top, such as a timestamp with seconds, ends the match, so the system prompt is kept byte-stable and the date goes last. - prompt injection
- Text inside something the agent reads (a file, a web page, a tool result) that is written as an instruction and gets obeyed as one. It works because instructions and data travel on one channel, so no sentence in the system prompt reliably prevents it; the rules that matter are enforced in code, at the tool boundary.
- provider
- The service that runs a model behind an HTTP API. [general] The API is stateless: it is sent the whole conversation with every request and keeps nothing between them.
R
- raw arguments
- What the adapter passes on when a tool call's collected argument text is not valid JSON:
{"_raw_arguments": text}in place of an exception. The tool's ownstr_argcheck then rejects it, and the model reads the error and corrects itself. - record
- The list of everything that happened, in order, including failed replies and calls nobody answered. It is appended to and never rewritten to look better.
- repair
repair_tool_history: a pure function that returns a copy of the transcript in which every tool call is followed at once by exactly one result. A recorded result is moved into place, a duplicate or an orphan is dropped, a call with no result gets a synthetic one; it is applied to the view on every request and never written back into the record.- replay
- Computing the current transcript by reading the log from its first line: the state is a fold over entries and is never itself saved. Resuming a session is
Harness(..., messages=log.replay())and nothing more. - role
- The tag on a message that says who spoke:
user,assistantand, from lesson 2,toolResult. Underneath, the model receives one sequence of text; roles exist so that nobody can forge who said what. - run
- Everything that happens from one prompt until the loop stops: one turn or many. From lesson 7 a run is a generator of events, and it is either driven to its end or explicitly closed, never abandoned.
- run guard
- The check in
Harness.promptthat refuses a second run while one is going on:RuntimeError,already running.promptis a plaindef, so the refusal lands on the caller's line and not at the firstnext().
S
- sandbox
- Confinement enforced from outside the agent's code, such as a container or a restricted account, that limits what a command can touch whatever the command says. Your tools have none; a guard is policy at the door, not a sandbox.
- scripted model
lab.ScriptedModel, the course's fake model: a list of steps, each a fixed reply or a function of the request. It is strict: sent an invalid transcript, it answers with a 400-style error reply, as a real API would, and never raises.- session log
SessionLog: the session on disk, one JSON line per entry — a message as it completes, and from lesson 12 a compaction. The log is the truth; the transcript is what you get when you read it back.- shell (lab)
lab.Shell: a simulator, not a shell, and the page says so. It answers the handful of commands the lessons need with scripted output and exit codes, because no real process can run in the browser.- skill
- A file of instructions for one kind of task, kept on disk. Only an index (name, description, path) goes into the system prompt, and the model loads a body with the
readtool when a task matches, so thirty skills cost a few lines per request instead of their full text. - SSE
- Server-sent events: the line-based text format in which a provider streams a reply over HTTP. [general]
parse_ssereads itsdata:lines and turns them into deltas and exactly one terminal event. - stateless
- Keeping nothing between calls.
model.completeanswers from the text of the request it was just sent, and from nothing else. - steering
- A user message queued to land as soon as it safely can ("actually, use spaces"): once the current turn's whole batch of tool calls has been answered, before the next model call. It does not abort the tool that is running, and a steer sent while idle goes in with the next prompt.
- stop reason
- The label on a reply that says why the model stopped:
stop,length,toolUse, and two you meet later,errorandaborted. The loop does not use it to decide whether to go on: content beats label, so tool calls in a reply are run whatever the label says. - subagent
- This harness used as a tool: the tool's
executeruns a freshHarnessto its end and returns the child's final text as the call's one result. The child's transcript never enters the parent's. - subscriber
- A function registered with
Harness.subscribethat hears every event of every run, after the record has changed and before the run's consumer is handed the event. Persistence is a subscriber, so the log is the same whichever frontend consumed the run. - synthetic result
- The tool result that repair supplies for a call that has none:
is_error=Trueand the textTool call interrupted: no result was recorded. ...It says only what is honestly known, and tells the model to check before repeating the call. - system prompt
- The standing instructions sent with every request, as an argument separate from the messages. From lesson 13 it is build output: a pure function of the enabled tools, the project's context files and a skills index, with the date and the working directory last.
T
- terminal event
- The one event that ends a streamed reply,
doneorerror, carrying the whole assistant message.parse_sseguarantees exactly one: a stream that simply stops yields anerrorthat keeps the partial content. - token
- The unit a model reads, writes and bills in: a word, or a piece of one. The lab counts four characters as one token; real tokenizers differ, and none of the course's arithmetic depends on the difference.
- tool
- Three things advertised to the model, a name, a description and a parameter schema, plus one function,
execute, that only your code ever runs. The model never sees the function; it can only ask. - tool boundary
run_tool, the one place that runs a tool and turns any failure into a result: tools just raise, and a singletry / except Exceptionconverts. One call in, exactly one result out, on every path.- tool call
- A content block of type
toolCallin an assistant message: anid, a toolnameand anargumentsdict. It is a specially shaped piece of the reply, a request and no more; nothing happens until your code runs it. - tool result
- A message with role
toolResultthat carries a tool's output back to the model, tied to its call bytool_call_id. It goes right after the assistant message that asked: one per call, in call order. - tool spec
- What the model is told about a tool: its name, its description and its parameters, and nothing else.
tool_specs(tools)builds the list, and it is sent, and paid for, with every request. - transcript
- The ordered list of role-tagged messages that your code owns and sends in full with every call. It is the only memory the model has.
- truncation
- Cutting a tool's output down to the budget: whole lines only, measured in UTF-8 bytes, keeping the head of a file and the tail of command output, where the verdict comes last. It is never silent.
- truncation notice
- The last line of a truncated result, which tells the model what it is not seeing and what to do next:
[Showing lines 1-20 of 50. Use offset=21 to continue.]Without it the model concludes, with confidence, that what it was not shown does not exist. - turn
- One pass of the loop: one model call, then the tool calls its reply asked for, each with its result. From lesson 7 a turn is bracketed by
turn_startandturn_end, and a user message may enter only at the top of one.
U
- usage
- The token counts a reply carries:
input,outputandcache_read. The lab's bill meter adds them up, which is how the cost of resending the transcript becomes something you can watch.
V
- valid transcript
- A transcript in a shape a provider accepts. [general] Real APIs reject a malformed one with an HTTP 400 instead of a reply; the lab's strict model does the same, and
lab.validatelists what is wrong. - view
- What the model is actually sent:
context_for_model(messages), computed afresh from the record for every request. It leaves out empty failed replies and, from lesson 10, repairs the pairing of calls and results; the record itself is never changed.
W
- wire format
- A vendor's own JSON for a request, as opposed to your neutral message dicts.
to_anthropicis a pure translation from one to the other; on that wire a tool result travels as atool_resultblock inside ausermessage. - workspace (lab)
lab.Workspace: the in-memory file system that the course's tools read and write. It keeps a log of every read and write, so a test, or you, can ask what really happened.
Terms by lesson
The same entries in the order the course earns them. A lesson never uses one of these names above the point where you have built the thing it names.
- 01 The function that forgetsfake model, message, persona, provider, role, scripted model, stateless, token, transcript, usage, valid transcript
- 02 Words are not deedscall id, content block, tool, tool call, tool result, tool spec, workspace (lab)
- 03 Turn the crankagent, agent loop, run, stop reason, turn
- 04 Tell the model what went wrongerror as observation, I2: one call, one result, is_error, shell (lab), tool boundary
- 05 Knowing when to stopin-band error, max_turns
- 06 The firehoseI1: the only memory, output budget, truncation, truncation notice
- 07 Show your workconsumer, event, frontend, generator, mutate, then announce
- 08 Who holds the list?harness, run guard
- 09 But I had something to sayfollow-up, steering
- 10 The poisoned transcriptdangling call, I3: the record is not the view, idempotent, orphan result, record, repair, synthetic result, view
- 11 Pull the plugappend-only, entry, JSON Lines, replay, session log, subscriber
- 12 The wallcompaction, context window, cut point
- 13 The briefingcontext file, guideline, prompt cache, skill, system prompt
- 14 The vetodeny-list, fail closed, guard, prompt injection, sandbox
- 15 The stop button that does not stopaborted, await, cancellation token, colour rule, cooperative cancellation, hard cancel
- 16 Capstone: out of the browseradapter, delta, eval, raw arguments, SSE, subagent, terminal event, wire format