Pi Agents

Most people write agents by writing prompts. That works right up until the moment it does not: the prompt gets longer, the instructions start to contradict each other, and the same task works on Tuesday and fails on Thursday for reasons nobody can name.

Pi is useful here because an agent is not merely a conversation; it is a program with explicit places to attach behaviour. Context files, prompt templates and skills shape what the model reads. Extensions add executable tools, commands and event handlers inside Pi’s process. Those choices have different costs in maintenance, review and trust. Some other mechanisms, such as providers and packages, solve different problems rather than simply adding more power.

This book is about choosing a mechanism that fits the requirement, then building it in the layer that owns the decision. The goal is not always to climb upward: different mechanisms solve different kinds of problem.

What is the least powerful Pi mechanism that solves this problem?

Underneath that question runs a second: not which mechanism, but which layer owns the decision? Chapter 11 turns the two into a practical procedure:

Use the least powerful mechanism that solves the requirement — and put it in the narrowest layer that actually owns the decision.

A third question becomes unavoidable when a requirement is a prohibition: what will still stop the action if the model or agent makes a mistake? Chapter 42 answers that in terms of independently enforced permissions and authority boundaries.

Chapter 1 grounds the layering argument in Pi’s package graph, then asks where that neat separation runs out. Pi has an embeddable agent core, but some lifecycle decisions are not exposed at a public extension seam early enough to control them. Chapter 39 tests the difference between observing a decision and intercepting it. A custom SDK host may own decisions that an extension cannot.

What the book builds

Six parts, forty-two numbered chapters, three appendices, and this introduction. Part I makes the agent loop and its inputs concrete. Part II chooses between instructions, prompts, skills, extensions and related ways of changing Pi. Part III examines the state that survives, the work that can continue, and the failures that must be recovered. Part IV compares five ways to drive the coding agent: interactive, print, JSON, SDK and RPC. Part V uses the model-access and agent-core packages directly to build and evaluate a claim checker. Part VI asks what any of those mechanisms is authorised to do.

The layers, in the direction of dependency:

interface                 drives and observes: terminal, print, JSON, RPC, an SDK host
application / host        purpose and deployment policy; external controls may enforce authority
agent application         sessions, compaction policy, extensions, workflow   (pi-coding-agent)
agent core                loop, messages, state, tool execution, events       (pi-agent-core)
model / provider access   one request to one model                           (pi-ai)
provider                  Anthropic, OpenAI, a local server

An agent sits above the model layer and below the application that gives it a purpose. The book argues that many hard-to-diagnose agent failures are mistakes about which layer owns a decision. Pi makes that claim concrete: you can inspect its layers, run examples against a pinned release, and recognise when an extension is too late to enforce the requirement.

Part I: The Agent Loop (chapters 1 to 10). What Pi is and what you are writing against. The loop that every extension attaches to, installation and a first task, models and thinking level, the context window as a budget rather than a container, where sessions live, the built-in tools, where configuration comes from and in what order it wins, the project .pi directory and the trust decision in front of it, the shell Pi actually invokes, and how to write a task the agent can finish.

Part II: The Four Building Blocks (11 to 22). How you change Pi. Chapter 11 is the decision chapter, and everything after it assumes you have made the decision. Then prompt templates and their argument substitution; skills and their description-based routing; skills that carry scripts, references and assets; your first extension; the lifecycle and the event contracts; tools in depth including exposure and nested calls; changing what the model knows; where state goes and why the four storage choices are not interchangeable; slash commands and terminal UI; MCP; and shipping the result as a package.

Part III: Long Sessions and Control (23 to 30). What happens when the conversation gets big. Compaction and what a summary does and does not preserve; branching and forking over a tree rather than a list; steering, queueing and aborting work in flight; the message types the whole system is built from; the session file format on disk; context admission, meaning who decides which instructions reach the model; failures, retries and recovery; and debugging by layer.

Part IV: Pi as a Program (31 to 35). When the interface is not the agent. Why the terminal is one driver of one agent; headless operation through print and JSON modes; the JSONL event stream and how to reconstruct state from it; the TypeScript SDK creating sessions in process; and driving a live Pi over RPC.

Part V: Building Below the Coding Agent (36 to 41). Using the layers Pi is built from. One chapter per layer step, with one running example, a claim checker, and code that runs: a single model call that returns a typed value; the agent core on its own; a stochastic step as a typed function; the hooks on the core and which decisions each can still change; composing operations without turning everything into an agent; and testing software that contains a model.

Part VI: Authority (42). What any of it may do. A closing chapter that gathers trust, permissions, tool annotations and isolation into one answer to the question the reader should have been asking since chapter 1: what makes an agent worth building at all?

Appendices. A: references and further reading. B: the terminal interface in detail, for the reader who is building a terminal component. C: Pi Patch Desk: the capstone, a supplement added after initial publication that brings the mechanisms together in one runnable, evidence-bearing fixture repair. Its implementation lives in the public pi-agents repository.

The decision the book is really about

Pi’s quickstart advises starting with the least powerful mechanism that meets the need, and offers this practical choice of mechanisms:

AGENTS.md        persistent instructions for a folder
prompt template  reuse a prompt from the / menu
skill            task-specific instructions plus supporting files
extension        executable tools, commands, or event handlers
terminal UI      a custom component in the terminal
custom provider  an unsupported model service
package          install or distribute several resources at once

Chapter 11 turns those choices into a procedure. They are not a strict ladder of permissions: a package distributes resources, a provider connects a model, and a terminal component changes presentation. The crucial difference is between text that guides behaviour and executable code that can act with Pi’s process permissions. An extension may inspect messages, tool calls, files and session history; a prompt template cannot execute code on its own. For a prohibition, the mechanism choice is not enough. Chapter 42 identifies the external control that must enforce it.

What kind of claims this book makes

Three kinds, kept apart in the prose.

Documented is what Pi’s documentation or its exported type declarations state. The book asserts these plainly and names the doc topic. Observed is behaviour that was run and recorded, with the version noted. Proposed is a pattern that belongs to this book and not to Pi — a reasonable way to structure an extension, a shape for a skill directory — and it is always signalled as such.

The runnable examples are kept in examples/ and target the book’s pinned Pi 1.0.4 release. Example markers and the verification scripts help check that documented snippets agree with their source files; any prose or code edits must be synchronized with those files before claiming a fresh test result. Run this book’s examples gives the commands and prerequisites. A green scripted-provider suite demonstrates specific code paths, not the reliability of a real model. Chapter 41 explains what a real-model evaluation would require.

This separation is the book’s method. Most agent writing goes wrong not because a technique was wrong but because a pattern that happened to work got described as though the framework guaranteed it. Where the book recommends something Pi does not require, it says so.

Who this is for

You have used a coding agent and want it to do one specific thing reliably. You are comfortable enough with TypeScript to read an event declaration. You would rather understand the mechanism than copy a snippet, and you want to know which parts of what you built depend on a documented contract and which parts are your own judgement.

No prior Pi experience is assumed. Parts I and III explain the mechanics without requiring TypeScript. Part II introduces extensions and expects you to read small async functions and schemas; Parts IV and V are most useful to readers building integrations or software on the SDK and core packages.

Find your problem

Most readers arrive with a symptom, not a plan. This table starts from the symptom. Chapter 42’s closing table is the foundation — it maps a requirement to a mechanism — but you should not have to reach the end of the book to find which chapter owns your problem.

How to read it

If you are here to build one thing, start with chapter 11 and follow its decision procedure. If you want to build below the coding-agent application, read chapter 1, then Part V. For extensions, start with Part I and use Parts II and III as references. For integrations, Part IV compares the available interfaces; Part V shows what changes when you own the model call and loop. For unattended or privileged operation, read chapter 42 before granting the agent access to production resources.