Agent Architecture on AIBussin — AI applications, systems and books

Agent Architecture on AIBussin — AI applications, systems and books https://aibussin.com/categories/agent-architecture/ Recent content in Agent Architecture on AIBussin — AI applications, systems and books Hugo en-US Mon, 05 Oct 2026 09:00:00 +0100 The Loop You Are Writing For https://aibussin.com/books/pi/01-chapter/ Thu, 01 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/01-chapter/ <p>You are going to write an extension. Before that, you need to know what it is extending.</p> <p>This is the step most people skip. They install Pi, run a task, get something nearly right, and start writing code against a mental model built from observation. The model is usually close enough to work and wrong in a few named places, and those places are where every interesting bug lives.</p> <p>Why “wrong in a few places” is worse than “wrong everywhere” is worth one sentence of its own, because it explains the shape of the rest of the book. A model that is wrong everywhere fails loudly: you stop and read the documentation. A model that is nearly right fails as a <em>symptom</em>. The model ignores your instructions. Your tool never appears. Your injected content vanishes after a compaction. Your handler fires at the wrong moment. Each of those observations is compatible with several different causes — some in your code, some in Pi’s, some in the way you assembled the request — and the observation alone cannot tell them apart. What tells them apart is knowing the exact mechanism the symptom passed through. That mechanism is the loop.</p> Models and Thinking Level https://aibussin.com/books/pi/03-chapter/ Thu, 01 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/03-chapter/ <p>Something is not working. The agent is not using your tool. It is ignoring an instruction. It stops halfway. Before you go looking in your extension, check which model is running and what thinking level it is set to.</p> <p>This is not a joke about blaming the model. It is a description of how the system is layered: model choice and thinking level sit <em>underneath</em> every mechanism in this book, and they change behaviour in ways that look exactly like bugs in the layer above.</p> The Context Window Is a Budget https://aibussin.com/books/pi/04-chapter/ Fri, 02 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/04-chapter/ <p>You are halfway through a refactor. Pi has read forty files, run the test suite twice, and rewritten the same module three times because each attempt turned out to conflict with the last. The session is still on disk, but the request has grown too large. If Pi compacts it, older messages are represented by a summary rather than sent in full.</p> <p>Most people meet this as a mood: Pi got worse at the task. It is easier to reason about as a budget. Each request consumes a varying number of tokens within the model’s context window, across components you can inspect and, in several cases, change.</p> Sessions and Where They Live https://aibussin.com/books/pi/05-chapter/ Fri, 02 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/05-chapter/ <p>When you want to reconstruct what Pi recorded, start with its session file. It is plain JSONL that you can read with a text editor: the first line is a header, and subsequent entries describe messages, settings changes and other session events. Entries with IDs and parent IDs form a tree, but not every recorded entry is a message sent to the model.</p> <p>That tree is the reason Pi can offer <code>/tree</code>, <code>/fork</code> and <code>/clone</code>, and it carries the book’s most-repeated distinction: <strong>a session is a tree; the model’s context is one path through it.</strong></p> Skills https://aibussin.com/books/pi/13-chapter/ Fri, 02 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/13-chapter/ <p><code>/review</code> from <a href="https://aibussin.com/books/pi/12-chapter/">chapter 12</a> expands when you invoke it. The problem it solves has a sibling: work that the model should recognise as relevant to a task without you naming a command first. Skill selection is model-driven, not a guaranteed trigger.</p> <p>That is a skill, and the entire mechanism turns on one field you are tempted to rush.</p> <h2 id="what-a-skill-actually-is">What a skill actually is</h2> <p><code>skills.md</code> opens with the definition: skills give Pi specialized instructions and supporting files for a particular kind of work. Pi advertises each eligible skill by name and description. The model may then read its <code>SKILL.md</code> when it considers the skill relevant; Pi does not automatically execute the skill on a matching task.</p> Skills That Carry Files https://aibussin.com/books/pi/14-chapter/ Fri, 02 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/14-chapter/ <p>The review guard’s checklist is forty items. Three screens of Markdown in <code>SKILL.md</code> would load all forty every time the skill fires, including for the small reviews where only three apply.</p> <p><code>skills.md</code> offers a better arrangement: skills can bundle scripts, references, and assets alongside their instructions. The body stays short and names the files; those files are not included automatically in the model context. The agent must explicitly read or execute them when needed.</p> Events and the Extension Lifecycle https://aibussin.com/books/pi/16-chapter/ Fri, 02 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/16-chapter/ <p>The review guard can suggest running the checks. It cannot stop a <code>git push --force</code> that the model decides to run while fixing a conflict.</p> <p>A <code>tool_call</code> handler can block a matching invocation of a tool before its body runs. That makes it a useful extension-level guard, not an unconditional prohibition: commands can reach the same effect through other tools or paths the handler does not inspect. Getting this right requires knowing the lifecycle, because handlers run in registration order and a return value only matters for events declared to accept one.</p> Changing What Pi Knows https://aibussin.com/books/pi/18-chapter/ Fri, 02 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/18-chapter/ <p>The guard works. Pi asks before a force push, <code>run_checks</code> runs the project’s own tests, and the failing-test tool answers with structured data.</p> <p>What still goes wrong is quieter. Pi reviews a diff using <code>npm test</code> instead of <code>run_checks</code>, despite the tool being declared to the model. The tool description makes it available; it does not guarantee selection. A reminder placed only in conversation history can also disappear from the request after compaction, leaving the model without that guidance on a later turn.</p> Extension State and Persistence https://aibussin.com/books/pi/19-chapter/ Fri, 02 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/19-chapter/ <p>Your <code>guard</code> extension blocks some writes to protected paths. It works on Monday. On Tuesday you run <code>/reload</code>, and the block count in <code>/guard-blocks</code> reads zero. On Wednesday you resume the session from disk and it reads zero again.</p> <p>Nothing is broken. The count was never persisted. It lived in a <code>let</code> captured by the extension factory, and a reload or a new process creates a new instance. The fix is not necessarily to invent a separate storage file: Pi already provides a durable, branch-aware place for state in persistent sessions. An ephemeral session, however, does not survive process exit.</p> Slash Commands and Custom UI https://aibussin.com/books/pi/20-chapter/ Fri, 02 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/20-chapter/ <p>Your <code>guard</code> extension logs blocked writes. The reader wants to see them. The obvious move is a <code>/guard</code> command that opens a picker. You write it, then invoke the command in print mode on a CI machine. There is no UI to show the picker, so a command written only for interactive mode cannot complete that interaction.</p> <p>The absence of a UI is expected, but silent failure is not a useful design. Handle modes explicitly before opening a dialog. This chapter covers the available UI surfaces and the mode rules that constrain them.</p> MCP Servers https://aibussin.com/books/pi/21-chapter/ Fri, 02 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/21-chapter/ <p>The <code>guard</code> extension intercepts <code>write</code> and <code>edit</code>. It blocks those calls as intended. Then someone on the team installs a Jira MCP server, and the model closes a ticket through <code>mcp__jira__transition_issue</code> without that guard blocking the call. The MCP call has a different tool name, so a guard limited to <code>write</code> and <code>edit</code> does not match it.</p> <p>It was not consulted because the guard never claimed that path was its responsibility — and, more importantly, because whether it <em>is</em> covered turns out to be a real question with a documented answer. This chapter is about registering MCP servers, controlling how their tools reach the model, and the one thing a permission extension can and cannot learn from them.</p> Compaction https://aibussin.com/books/pi/23-chapter/ Fri, 02 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/23-chapter/ <p>Two hours into a refactor, the footer says you are at 87% context. Nothing is wrong. Then it says the agent compacted, and the model asks you to re-explain the schema it was told about an hour ago.</p> <p>That re-asking is one possible consequence of compaction, not necessarily a defect in your prompt. The original entries remain in the session file, but the older portion selected for compaction no longer reaches the next model request as individual messages. Pi sends a generated summary in its place and keeps the more recent messages. The summary may be produced by the current model, and it can omit details that the earlier conversation contained.</p> Branching and Forking https://aibussin.com/books/pi/24-chapter/ Fri, 02 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/24-chapter/ <p>The agent picked a schema you did not want, edited eleven files, and is confidently three steps into an approach you have already decided against. You press Escape. Now what?</p> <p>There are three answers for the <em>conversation</em>: <code>/tree</code> moves within the current session, <code>/fork</code> starts a new session from an earlier user message, and <code>/clone</code> copies the active branch into a new session. The distinction decides where the conversation history lives and which part of it the model sees next. None of these commands undoes the eleven edits already made on disk. If you also want the repository back in its earlier state, inspect and restore those working-tree changes separately, using version control or a backup.</p> Steering, Queuing, and Changing Direction https://aibussin.com/books/pi/25-chapter/ Fri, 02 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/25-chapter/ <p>The agent is eleven tool calls into migrating your schema. You can see it is going to be wrong in about three more steps. Aborting would stop the current run, but it would not erase the conversation or undo tool calls that have already completed. You want to preserve the useful investigation while correcting what happens next.</p> <p>You type. You press Enter. And the message waits — because Pi was not going to interrupt mid-tool-call, and the moment it delivers your instruction is a specific, documented point in the loop.</p> Message Types https://aibussin.com/books/pi/26-chapter/ Fri, 02 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/26-chapter/ <p>You write an extension that renders tool results. It works with streaming events, fails when replaying a saved session, and fails differently when inspecting a provider request. The difficulty is that a streaming message, a persisted session entry, a projected conversation, and a provider request are not interchangeable representations. One field in particular is not what its name suggests.</p> <p>This chapter is the reference for the shapes themselves.</p> <h2 id="one-union-four-surfaces">One union, four surfaces</h2> <p>“Pi uses <code>AgentMessage</code> values in SDK state, lifecycle events, RPC responses, and persisted session message entries.”</p> The Session File Format https://aibussin.com/books/pi/27-chapter/ Fri, 02 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/27-chapter/ <p>You open a session file to find out what the agent actually saw. There are four hundred lines. Somewhere in them is the system prompt, most of a conversation that has been summarized away, a branch you abandoned last week, and a <code>custom</code> entry from an extension storing its own counter.</p> <p>Which of those reached the model is not obvious from the file. This chapter is about the file and the rule that decides.</p> Context Admission Is Application Policy https://aibussin.com/books/pi/28-chapter/ Fri, 02 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/28-chapter/ <p>Compaction summarized away the schema you explained, and the model asks you to restate it. You will not restate it. The fix is a file, because loaded instructions travel with every request while a conversation gets compressed. <a href="https://aibussin.com/books/pi/23-chapter/">Chapter 23</a> ended there.</p> <p>But “put it in a file” is the start of the question, not the end. A file on disk can be ignored, replaced, filtered out, or supplied by someone other than you. This chapter is about the four separate facts hiding in the sentence <em>the model read my AGENTS.md</em>, and about who decides each one.</p> Failures, Retries, and Recovery https://aibussin.com/books/pi/29-chapter/ Fri, 02 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/29-chapter/ <p>The provider returns 529 overloaded. Pi waits two seconds and tries again. Twice more. Then it stops and tells you the model is unavailable.</p> <p>That is correct — and it is the <em>least</em> interesting failure Pi handles. There are three responses to a failed request, they are not interchangeable, and picking the wrong one is how an agent ends up retrying a request that could never succeed.</p> <h2 id="three-responses-three-meanings">Three responses, three meanings</h2> <p><strong>Retry.</strong> The failure was transient. The request was fine; the server was not. Repeat it.</p> The Interface Is Not the Agent https://aibussin.com/books/pi/31-chapter/ Fri, 02 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/31-chapter/ <p>You have spent thirty chapters mostly in a terminal, and it is easy to come away thinking the terminal is Pi. It is not. The terminal is one way to drive the agent, alongside print mode, JSON, RPC and the SDK. Switching interfaces preserves the underlying agent architecture, but can change how work is submitted, what a person can approve, and how results and failures are reported.</p> <p>That is a claim about architecture, and this part of the book ends by testing it. Chapters 32 to 35 take the interfaces one at a time. This chapter states what they share, shows that the sharing is real, and names the one place where an interface does leak into what an extension is allowed to assume.</p> Model Access Without the Coding Agent https://aibussin.com/books/pi/36-chapter/ Sun, 04 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/36-chapter/ <p>Everything so far has run inside a coding agent. You have been using a tool that reads files, runs commands and keeps a session, and you have been attaching to it. That is the right place to start, because Pi’s host is where most people meet Pi.</p> <p>It is the wrong place to stop, because most of what an application needs from a model is not an agent. It is one question and one answer: <em>is this claim supported by this evidence?</em> One input, one typed result, nothing to run, nothing to remember.</p> The Agent Core on Its Own https://aibussin.com/books/pi/37-chapter/ Sun, 04 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/37-chapter/ <p>The claim checker from <a href="https://aibussin.com/books/pi/36-chapter/">chapter 36</a> has a limit. Given the evidence you handed it, it can produce a schema-valid assessment, including <code>insufficient</code> when the evidence is inadequate. It cannot independently fetch more evidence in that single call, and the model may still judge the evidence incorrectly.</p> <p>Looking for more is a loop: the model asks for something, you run it, you give the result back, and the model decides again. You have seen that loop for thirty-six chapters, from the outside. This chapter runs it from the inside, in about forty lines, using the same class the coding agent is built on.</p> A Stochastic Step Is a Typed Function https://aibussin.com/books/pi/38-chapter/ Sun, 04 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/38-chapter/ <p>An unconstrained agent may finish with prose, and prose is a fragile interface between software components.</p> <p>You can pass a paragraph to another function, but branching on its meaning requires interpretation or parsing whose behavior you must define and test. An ordinary agent can stop after deciding it is finished, without producing the structure a downstream function expects. This chapter puts a validated value at that boundary instead.</p> <p><a href="https://aibussin.com/books/pi/36-chapter/">Chapter 36</a> fixed this for a single call. This chapter fixes it for a loop. The result is the most reusable idea in the book, and it fits in one function.</p> Seams, Hooks, and Irreversible Decisions https://aibussin.com/books/pi/39-chapter/ Sun, 04 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/39-chapter/ <p><a href="https://aibussin.com/books/pi/01-chapter/">Chapter 1</a> ended on a sentence that has been quietly organising the book since:</p> <blockquote> <p>An extension point is a real architectural seam only for decisions it can intercept before those decisions become irreversible.</p> </blockquote> <p>It was stated there as a finding about forks of the coding agent, and it was argued from three cases. This chapter tests it on something you can run. The agent core has nine function-shaped options that run around a request or a tool call, and for each one the useful question is not <em>what does it give me</em> but <em>what can I still decide by the time it fires</em>.</p> Composing Agent Operations https://aibussin.com/books/pi/40-chapter/ Sun, 04 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/40-chapter/ <p>The tempting next move is to make every part of the pipeline an agent. One agent retrieves, another assesses, another summarises, and they talk. That may be useful when the tasks genuinely require independent decisions or work, but it introduces more model calls, coordination and failure paths than this claim checker needs.</p> <p>This chapter is the argument against doing that by default, made with a pipeline you can run. The rule it demonstrates:</p> Testing Stochastic Software https://aibussin.com/books/pi/41-chapter/ Sun, 04 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/41-chapter/ <p>The tests in chapters 36 to 40 all passed. They tell you less than you might hope, and it is worth being exact about what.</p> <p>They show how your <em>code</em> handles the model responses you scripted. They cannot establish how often a real model will produce those responses. A scripted provider can simulate refusals, rambling answers and wrong tool calls, but only when you write those cases into the script. If you stop at green tests, you have not yet measured the stochastic part.</p> Authority, Isolation, and What Makes an Agent Worth Building https://aibussin.com/books/pi/42-chapter/ Mon, 05 Oct 2026 09:00:00 +0100 https://aibussin.com/books/pi/42-chapter/ <p>Everything so far has been a mechanism. Tools, extensions, events, sessions, modes, protocols. This chapter is about the one question that turns a set of mechanisms into something you would let near a production repository, and about what you are then able to claim.</p> <p>Two claims carry the chapter. <strong>Capability is not authority:</strong> Pi can do almost anything the account that started it can do, and several documented mechanisms bear on whether it <em>should</em> do a particular thing. Those mechanisms matter, but none by itself is a sandbox. And <strong>a prohibition on what the agent can reach needs enforcement outside the agent’s ability to override it.</strong> That may be an operating-system restriction, a credential with limited scope, or a remote service that independently denies an operation. A prompt, an in-process gate and a tool allowlist can still provide useful controls, but they must not be mistaken for containment of the whole process.</p>