Agent Engineering / Reading the Source / Building It

Big Talk Agent

Start from a shared language for Agents, read the source along a real project's call chain, then complete a runnable, verifiable bounded agent in TypeScript.

Start with the Prologue →Jump to Chapter 1 ↗

1. 01Part I · Concepts

   Ch. 1–17. With no product in sight, build a shared language for models, tools, loops, context, extension, and safety.

2. 02Part II · Pi in Source

   Part II chapters 01–13. Follow the real call chain of pi v1.0.0 and see where these boundaries land in engineering.

3. 03Part III · Build It

   Part III Ch. 1–12. Close the source and write a bounded, runnable, verifiable TypeScript Agent from an empty directory.

42 chapters · 11 appendices · source baseline pi v1.0.0 · 40 tests in the Build part

Preface

To you, opening this book:

When you first open a real Agent project, the usual obstacle is not TypeScript syntax. It is not knowing which call chain to follow: where input enters, how state changes, how tools and the model hand off to each other, and who wraps things up when an error occurs.

This book is a reading map. First build a mental model of Agents that depends on no product. Then walk the control flow and data flow through pi-mono, taken from a fixed snapshot. Finally, implement the necessary parts as one runnable TypeScript Agent.

Xiao A is a newcomer who has just joined the project; Lao Z is an experienced colleague. The two work through problems via code walkthroughs, design discussions, and paired debugging. The dialogue serves the problems, the evidence, and the trade-offs; it does not stand in for technical explanation.

What this book is

This is a book about Agent engineering for developers, with 42 chapters (Part I 1–17, Part II 1–13, Part III 1–12) and 11 appendices (1–11). It assumes you already have basic experience with TypeScript, the command line, and Git, that you want to understand how an Agent is built, and that you are willing to ground conclusions in code and verification. It is not written for readers with no programming experience, and it is not a manual for any one product.

The goal of the whole book can be condensed into one sentence: read an Agent system from "I've heard of it" to "I can build one myself."

The three-step route

1. Build a shared language: models, tools, loops, context, extension, and safety — what are the engineering boundaries of each?
2. Check against real source code: walk pi-mono's call chains once, with questions in hand, and see how these concepts land in practice.
3. Put the source away and do it yourself: implement a TypeScript Agent whose scope is controlled, that runs, and that can be verified.

Why this book exists

There is a distance between "knowing the concepts" and "being able to read real engineering." Concepts detached from implementation easily become a list of jargon; source code without a path easily degrades into wandering the directory tree. This book connects the two, but it does not promise to walk through every line of source.

The problems it tackles are concrete. Given an Agent project, which file should you start reading from? Where does a model request originate, how does the stream pass through the adapter layer, how does the loop advance state, how does a session survive a process restart, and who wraps things up when errors occur? The Concepts part gives the framework for these questions, the Source part gives real instances, and the Build part gives you the chance to build one yourself.

• Part I · Concepts (chapters 1–17) builds a shared language for models, tools, loops, context, extension, and safety, without substituting Pi or any specific project for the general concepts.
• Part II · Pi in Source (chapters 1–13) covers the core entry points, key types, main call chains, state changes, error paths, and design costs; edge features left uncovered are stated explicitly.
• Part III · Build It (chapters 1–12) implements only the capabilities that requirements prove necessary, and verifies that they work together through runnable artifacts, tests, and Stage Acceptance.

Who it is for

• Developers with basic TypeScript, command line, and Git experience who want to understand Agent engineering;
• Programmers who want to read the pi-mono source but need a reliable walkthrough path;
• People who want to implement a bounded agent in TypeScript and are willing to run the verification commands.

If you fit any of these, reading in order gives the most out; if you care about only one part, the "How to read it" section below gives paths you can skip.

How to read it

• You only need the shared language: read Part I · Concepts;
• You want to build source-reading skills: follow Part I → Part II in order;
• You want to finish a runnable artifact: follow Part I → Part III in order; Part II supplies comparisons from a real project for architectural trade-offs.

The three parts conclude with Hands-on Verification, Source Walkthrough, and Stage Acceptance respectively. The structure, baseline, and reading discipline of each part are explained on its own part home page.

Reading discipline for the whole book

• First tell four kinds of content apart: confirmed facts, inferences grounded in source code, general engineering opinions, and illustrations that are explicitly marked
• The Concepts part features no specific product; the Source part is pinned to one commit of pi-mono; the Build part promises only the artifact examples/mini-agent
• Every chapter ends with a verification (Hands-on Verification / Source Walkthrough / Stage Acceptance) — a chapter counts as read only once you have done it
• When you meet a cited source symbol, go back to the pinned commit to check it; don't rely on the line numbers in this book alone

About pi

The Source part of this book reads pi-mono (now named earendil-works/pi) through the snapshot of the single tag v1.0.0 (commit a13d35a742c6ef8462812a28fbe1d8c8b7431c32). The root repository version of that snapshot is 0.0.3, while the eight packages this book selects are version 1.0.0; the two must not be mixed. The pi/ directory at the root of this book's repository is the source snapshot of that tag, annotated with added comments; paths and symbols match upstream, but line numbers shift because of the comments. It provides interrelated engineering boundaries — multi-provider model calls, the Agent runtime, the coding CLI, the terminal UI, the protocol, and remote sessions — which makes it well suited to tracing one complete request.

The source code shows verifiable facts; explanations derived from call relationships are marked as inference; pseudocode, abridgements, and hypothetical scenarios are marked as illustration or simplification. The opinions in this book are engineering trade-offs; they do not represent the intent of Pi's authors or maintainers.

Relationship to the Prologue

This Preface answers "what is this book, who is it for, and how do I read it." The Prologue is a concrete work scenario: a new colleague, Xiao A, takes over an incident post-mortem and cannot tell which layer to investigate from three log lines — "the model stream broke, the tool arguments were invalid, session recovery failed." The Prologue turns "why build a shared language first" into a problem you can feel, and it is where the book's narrative begins.

If you have just opened this book, read the Prologue first (about three minutes), then come back here for the structure, and then start with Chapter 1 of the Concepts part.

Acknowledgments

Thanks to the open source community for providing real projects that can be read and verified, and thanks to readers willing to ground conclusions in code and verification.

Start from the Prologue, join Xiao A and Lao Z in taking the problems apart, and walk your way to your own runnable Agent.