Prologue · The New Colleague's First Question
Xiao A reported to the project team on his first day. He had barely sat down at his desk when the team lead dropped an incident post-mortem on him: an Agent had run for three hours overnight, and along the way the model stream broke, a tool call carried invalid arguments, and session recovery failed. The three records look unrelated, yet the whole night's work was wasted.
Xiao A went through the logs, and the more he read, the less sure he felt. He had just finished learning TypeScript, could use the command line, and had seen Agent demos. But when asked to say clearly "what exactly is this Agent made of", he found he could not.
He went to Lao Z, steeling his nerve: "Of these three entries in the log, which one should I start investigating?"
Lao Z didn't answer the question. He asked one back: "Don't rush to change code. Can you walk from input to output and say what the model, the tools, the loop, the session, and the human are each responsible for?"
Xiao A thought for a moment. "I know it calls the model and executes tools. But when a failure happens, I can't tell which layer it's in, and I have no idea which file to open first when I want to read this Agent's source."
"That's not your fault," Lao Z said. "What you're missing isn't lines of code. It's a shared language. Without it, a log is a pile of isolated errors, and a source tree is a pile of unfamiliar directories."
He tapped three lines in the log. "These three happen to sit at three different layers. A broken model stream is an integration-layer problem: how the request goes out, how the stream comes back, and whether an interruption counts as a normal end. Invalid tool arguments are a tool-layer problem: how the schema is declared, how arguments are validated, and who is supposed to block an invalid call. A failed session recovery is a state-layer problem: where the history lives and how you pick it back up after the process restarts. With this language, your first look already tells you which layer to investigate."
Xiao A's eyes lit up. "So this book doesn't teach me how to drive some particular Agent. It teaches me how to tell these things apart first."
"Right — and telling them apart is only the start." Lao Z drew a line on the paper. "From telling them apart, to understanding them, to building one yourself. The book moves in three steps:"
The route of this book
- Establish a shared language: what are the engineering boundaries of the model, the tools, the loop, the context, extensions, and safety
- Verify against real source code: follow one call chain through pi-mono with questions in hand, and see how these concepts land
- Close the source and build it yourself: implement a scoped, runnable, verifiable TypeScript Agent
"Each step keeps two things in view," Lao Z said. "What it solves, and what it deliberately does not solve yet. When you finish those three steps and come back to this page of logs, you'll find the answer yourself."
"Roughly how long will that take me?" Xiao A asked.
"The book is ordered by dependency," Lao Z said. "Concepts are the prerequisite for the source, and the source is the prerequisite for the build. You need to finish the concepts before the source reads clearly; you need to finish the source before you know which abstractions are worth keeping in your own build and which belong only to that project."
"And what does each of the three parts solve, and what does it leave out?" Xiao A pressed.
"This table answers it." Lao Z wrote out a tour:
The Book at a Glance
The book has three parts:
| Part | Responsibility | What it solves here | What it leaves out for now | Chapters |
|---|---|---|---|---|
| I · Concepts | Establish the shared language | The engineering boundaries of the model, tools, loop, context, extensions, and safety | No discussion of Pi or any specific project | 17 |
| II · Pi in Source | Read pi-mono along its call chain | Core entry points, types, state, error paths, and design costs | Not a line-by-line tour of all the source, and no coverage of every edge feature | 12 |
| III · Build It | Implement a bounded TypeScript Agent | Assemble the code from each chapter into one runnable, verifiable artifact | No production-grade platform, and no extensions the requirements haven't justified | 12 |
"Let me translate those three rows for you," Lao Z said. "Part I · Concepts answers 'what is each of these things on its own'. It isn't tied to any specific product, so you won't walk away with a directory layout that goes stale. Part II · Pi in Source answers 'how does a real project organize these together'. It covers the single pi-mono repository, and what it teaches is the organizing ideas you can reuse. Part III · Build It answers 'if all I have is TypeScript, what's the least I must write'. Its scope is deliberately narrow: only the parts the requirements prove necessary."
"Then why doesn't Part I · Concepts just teach pi-mono directly?" Xiao A asked.
"Concepts don't divide along product lines. Products do," Lao Z said. "If we started with pi-mono's directories, you would take the directory names for concept boundaries. Switch to another product, the names change, and you won't recognize anything. Build product-independent concepts first, then look at a concrete implementation, and the concepts won't travel with the directory names. Part I · Concepts takes 17 chapters — nearly half the book — precisely to lay that foundation for the other two parts."
"Part II · Pi in Source only covers pi-mono. Does finishing it mean I'll only know pi-mono?"
"Not 'only know' — 'able to compare'. pi-mono is a complete, runnable Agent repository: real Provider integration, a loop, sessions, a protocol, evaluation. Walk its call chain once and what you learn is 'what responsibility boundaries an Agent system has, and how each boundary is wired'. Those boundaries hold in any project you put them back into. That's what Part II · Pi in Source gives you: a sample you can check yourself against."
"And Part III · Build It? If Part II · Pi in Source already explains it thoroughly, why build one myself?"
"The point of Part III · Build It is to make you take each trade-off in person. Reading and building are two kinds of understanding. When you read, you accept many abstractions as obvious: why there has to be a Harness, why the session must be persisted, why tools need approval. When you build, you have to ask each abstraction again whether your requirements actually need it."
Chapter index: the full chapter list is on the Part I · Concepts, Part II · Pi in Source, and Part III · Build It home pages and in the Appendix.
Reading route: read Part I · Concepts first to build the shared language, then use the real project in Part II · Pi in Source to check those concepts, and finally implement and verify the required capabilities in Part III · Build It.
"A few reminders about how to read. Remember them — you'll use them all the way through," Lao Z added.
How to read this book
- Confirmed facts, inferences grounded in the source, general engineering opinions, and explicitly labeled illustrations carry different evidential weight. Don't conflate them.
- Part I · Concepts names no specific product. Part II · Pi in Source is pinned to one commit of pi-mono. Part III · Build It commits only to the
examples/mini-agentartifact. Each part has its own evidence boundary.- Every chapter ends with a verification: Hands-on Verification in Part I · Concepts, Source Walkthrough in Part II · Pi in Source, Stage Acceptance in Part III · Build It. None counts until you produce evidence.
- When you meet a source symbol cited in the text, go back to the corresponding pi-mono commit and check it. Don't trust the line numbers in the book alone; they are a locator for that snapshot.
"Evidence boundary?" Xiao A looked puzzled.
"That's 'what makes this claim stand up'. The kinds of statements in this book come from different places. Some you can see directly in the source. Some are inferred from the structure. Some are the author's judgment from experience. Some are illustrations drawn for you. Tell those four apart and, while reading, you know which conclusions you can trust, which you must verify yourself, and which are only food for thought. That is the reading discipline this book keeps repeating."
Having read the tour, Xiao A still had that page of logs on his mind. He asked Lao Z: "So what's the smallest question I should start from?"
Lao Z pointed at the first line of the log. "Start there. Why does a piece of text generated by a model sometimes become one controlled engineering action?"
Chapter 1: The Model Is a Component — The Role of the LLM and Choosing One