AI Agent Architecture: Tools & Environments

Every effect an agent has on the world should go through one door — and the door should keep the book.

Atlas, Meridian Supply Co.'s customer-operations agent, could plan, remember, and reason by Book 3. It reached the world through function calls scattered across three books of code, and on a Tuesday a regression suite logged ninety-eight tickets in a real CRM because the mock covered the model and not the world. Nobody had a list of the places Atlas could touch the world; the whiteboard was wrong twice. This book builds the action boundary as one system, wall by wall, each justified by an incident and proved by a test.

Every chapter is a lab on the companion repository — one dependency, fully offline with a scripted mock, every listing printed from a verified line range, every command paired with its expected output. Five moves per chapter: Run

the demo, Read the listing, Break it with the chapter's planted failure, Fix it with the design move, Prove it with a test that turns green. You will:

Tag every side effect — kind, target, reversibility, compensator — generate the catalogue, and run a lint that finds the five untagged effects in three versions of Atlas

Build a tool layer as ports and adapters: a registry the core never names, a new capability in one registration, and a schema that refuses wrong, missing, and invented arguments by name

Serve and consume tools over MCP — JSON-RPC on stdio, three methods, a gateway on both ends — and draw the trust line that quarantines a carrier's injected description

Route every call through one gateway with policy by principal, quotas, keys, bounded retry, and an audit line written in a finally — then attempt the bypass and watch it refused and counted

Sandbox the tools that execute: a jail, an allowlist, path-free flags, a clean environment, a timeout — and measure blast radius as a number

Reproduce a retry storm (five refunds for one carton), fix it with idempotency keys, and undo a half-placed order with a saga whose irreversible step goes last

Drive a web shop through a text browser behind the gateway, break the plan with a page change, and write it in the page's words instead

Every chapter carries a research lineage (purity and safety-critical surfaces, Cockburn's ports and adapters, RPC from Birrell–Nelson to MCP, Anderson's reference monitor and Saltzer–Schroeder, chroot to containers, Garcia-Molina's sagas, WebArena, master data and bank reconciliation, Meszaros's test doubles and chaos engineering), a five-item failure catalog, an applied deep-dive, and exercises in three tiers. Ten figures, a hundred and ninety tests, thirty-five decision records, one running system that grew from Book 3's graph without removing a node of it.

Who it's for:

engineers integrating agents with real systems — anyone who has given a model a tool and wants to know what it can do, who may call it, what happens when it is retried, and how to prove afterwards what happened. Assumes Book 2 or the equivalent; basic Python; no framework, no GPU.

The AI Agent Architecture Series is the architect's track: one architectural layer per book, on one running system the reader refactors and grows by hand. This is Book 4, Tools & Environments — the action boundary, designed and audited.