Deep Dive
Pi Agent
These 21 chapters take you from the core agent loop to the full engineering picture — based on real source analysis.
Core Agent Loop
Every AI Agent is essentially a loop. Click each step to see the corresponding source and implementation details.
User Input · Harness
The user hits enter. The Agent switches from "idle" to "busy", then bundles the chat history, model config, and available tools into a frozen "work snapshot" — every decision in this turn is based on it; changing settings mid-run won't affect the current turn.
// packages/agent/src/harness/agent-harness.tsasync prompt(text: string) {if (this.phase !== "idle")throw new AgentHarnessError("busy")this.phase = "turn"const turnState = this.createTurnState()const context = session.buildContext() // JSONL → messages[]}
From 30 Lines to 920 Files
A teaching Agent's core loop is just ~30 lines, but how much engineering does production pi stack on top of the same loop?
Four Architecture Layers
From the core engine to the user interface, pi is organized into four layers by responsibility. Click to expand and see core files, design patterns, and corresponding chapters.
8 Distinctive Design Choices in pi
pi's unusual engineering tradeoffs: minimal core + self-extension, Result types, durable session tree, lazy SDKs, supply-chain hardening — each maps to a specific chapter.
Key Source Files
Understanding these key files gives you a grasp of the entire system. File size reflects engineering complexity.
21 Chapters of Source Deep Dive
Each chapter focuses on a core subsystem with source analysis + architecture visualization + runnable demos. Filter by layer, or follow the sequence.