# Book Plan — *Agents: From Theory to Production*

> Living document. Update as chapters are researched, drafted, and reviewed.

## 1. Vision

A single book that bridges two worlds that are usually taught separately:

1. **The classical theory of agents** — the rigorous, decades-old framework of
   rational agents, environments, and architectures from AI research.
2. **Modern LLM agents** — how large language models, tools, memory, planning,
   and orchestration frameworks turn that theory into working software today.

The reader should come away able to *reason* about agents (why a design works)
**and** *build* one (how to ship it).

## 2. Audience

Mixed / broad:

- **Developers & practitioners** — want runnable code and patterns.
- **Technical leaders & PMs** — want mental models, trade-offs, and strategy.
- **Students & the curious** — want the foundational theory explained clearly.

Design implication: every chapter opens with intuition, adds theory, then shows
code. "Deep-dive" and "In practice" callout boxes let readers choose their depth.

## 3. Format & Toolchain

- **Authoring:** [Quarto](https://quarto.org) book project (`.qmd` files).
- **Outputs:** HTML (web) + PDF (print) via `quarto render`.
- **Code:** Python — LangGraph / LangChain / OpenAI Agents SDK, executed in-line.
- **Citations:** `references.bib` (BibTeX) + IEEE CSL style.
- **Reproducibility:** `execute.freeze: auto` caches results; `requirements.txt`
  pins dependencies.

## 4. Structure (5 parts + appendices)

| Part | Theme | Chapters |
|------|-------|----------|
| I | Foundations of Agency | 1–4 |
| II | The LLM as an Agent | 5–7 |
| III | Building Agents | 8–14 |
| IV | Production & Trust | 15–18 |
| V | Frontiers | 19–20 |
| — | Appendices | A–C |

### Chapter map

**Part I — Foundations of Agency**
1. What Is an Agent? — definitions, agent vs. workflow, the spectrum of autonomy.
2. A Short History & the Theory — symbolic AI, BDI, RL, the rational-agent model.
3. Agent Architectures — reactive, deliberative, hybrid, the sense–plan–act loop.
4. Environments & Rationality — PEAS, observability, stochasticity, utility.

**Part II — The LLM as an Agent**
5. LLMs as Reasoners — what LLMs can/can't do; emergence, limits, hallucination.
6. The Augmented LLM — tools, retrieval, memory: the core building block.
7. Reasoning & Planning — CoT, ReAct, Reflexion, Tree/Graph-of-Thought.

**Part III — Building Agents**
8. Workflows vs. Agents — the key architectural distinction; when to use each.
9. Agentic Patterns — chaining, routing, parallelization, orchestrator-workers,
   evaluator-optimizer.
10. Tools & the Model Context Protocol (MCP) — designing the agent–computer
    interface; MCP servers/clients.
11. Memory Systems — working, episodic, semantic, procedural, and reflective memory;
    vector stores; the memory lifecycle; retrieval signals; forgetting; graph memory;
    and how to evaluate agent memory.
12. Orchestration with LangGraph — state, graphs, checkpoints, human-in-the-loop.
13. The OpenAI Agents SDK — agents, handoffs, guardrails, tracing.
14. Multi-Agent Systems — collaboration, delegation, communication, failure modes.

**Part IV — Production & Trust**
15. Evaluation — task success, trajectory eval, LLM-as-judge, benchmarks.
16. Observability — tracing, logging, debugging agent trajectories.
17. Safety & Guardrails — prompt injection, sandboxing, permissions, OWASP LLM.
18. Deployment & Cost — latency/cost trade-offs, caching, model routing, scaling.

**Part V — Frontiers**
19. Computer Use & Embodiment — GUI agents, browser/OS control, robotics links.
20. Frontiers & Open Problems — continual learning, self-improvement, governance.

**Appendices**
- A. Environment Setup — Python, keys, Quarto, running the code.
- B. Glossary.
- C. Further Reading.

## 5. Per-chapter workflow

For each chapter:
1. **Research** — gather 3–6 authoritative sources; add to `references.bib`.
2. **Outline** — H2/H3 headings + key claims.
3. **Draft** — prose + diagrams (Mermaid) + runnable code.
4. **Verify** — run code cells; check every factual claim has a citation.
5. **Review** — apply the style checklist in `.github/skills/book-style/SKILL.md`.

Use the `/draft-chapter` prompt (`.github/prompts/draft-chapter.prompt.md`) to
kick off a consistent first draft.

## 6. Style principles

- Intuition first, then formalism, then code.
- Every non-obvious factual claim is cited.
- Prefer small, runnable examples over large frameworks-heavy ones.
- Show *why* before *how*; note trade-offs and failure modes honestly.
- Keep vendor-neutral where possible; flag when guidance is provider-specific.

## 7. Status tracker

> **Structure note (2026-07):** Chapters 8 (Workflows vs. Agents) and 9 (Agentic
> Patterns) moved from Part II into Part III. They are design and architecture
> chapters that sit closer to *building* than to the model itself, so Part II now
> ends at Chapter 7 (the model and its reasoning) and Part III spans Chapters 8–14
> (deciding, then patterning, then building). `_quarto.yml`, the two preview
> builders, and the chapter map above were updated together; chapter numbers are
> unchanged.

Legend: ☐ not started · ◐ drafting · ● drafted · ✅ reviewed

| Ch | Title | Status |
|----|-------|--------|
| 1 | What Is an Agent? | ● (drafted, concept-first pass) |
| 2 | History & Theory | ● (drafted, concept-first pass) |
| 3 | Agent Architectures | ● (drafted, concept-first pass) |
| 4 | Environments & Rationality | ● (drafted, concept-first pass) |
| 5 | LLMs as Reasoners | ● (drafted; deepened with a reasoning taxonomy, CoT-faithfulness caution, process-vs-outcome supervision, reasoning topologies, a reliability ladder, a perturbation test for real reasoning, grounding-vs-verification, reasoning-vs-planning, abstention, and a Ledgerly billing case study; em-dashes swept; +5 refs) |
| 6 | The Augmented LLM | ● (drafted; deepened with the augmentation-as-control-boundary argument, a "solves a problem / creates one" trade-off table, tool-use-as-decision-chain, the model-runtime boundary + @fig-model-runtime, tool-output-as-observation prompt-injection warning, many-tools routing/eval, parametric-vs-non-parametric memory, evidence-not-truth, adaptive retrieval, orchestration-as-decisions, single-turn-vs-loop table with a ReAct bridge, and a staged Ledgerly turn + @fig-ledgerly-augmented-turn; +3 refs: mialon2023augmented, asai2023selfrag, borgeaud2022retro) |
| 7 | Reasoning & Planning | ● (drafted; deepened with a reasoning/planning/control distinction, plan-and-solve and plan anatomy, a ReAct closed-loop trace and observation caution, reflection-needs-a-judge, a branching-worth-it rule, parallel planning (LLM Compiler), a strategy-ladder table, stop conditions and plan repair, and a Ledgerly billing-investigation case study; em-dash-free additions) |
| 8 | Workflows vs. Agents | ● (drafted; deepened with the autonomy-is-a-trade / autonomy-budget argument + @fig-autonomy-budget, when-a-task-earns/deserves-autonomy subsections, start-from-the-process mapping + @tbl-task-classification, hybrid-as-mature-default and the agentic-step contract + @tbl-agentic-contract with a no-rules-in-prompts warning, autonomy-owes-evaluation section + @tbl-eval-by-architecture (task/trial/grader/transcript-vs-outcome), and a one-hard-ticket Ledgerly hybrid walkthrough + @fig-ledgerly-hybrid; +refs anthropic2026evals, mslearn2026agentic; em-dash-free additions) |
| 9 | Agentic Patterns | ● (drafted, concept-first pass) |
| 10 | Tools & MCP | ● (drafted; deepened with tool-use lifecycle, failure taxonomy, good-vs-bad tools, output design, long-running tools, large-catalog routing, tool-use evaluation, HITL tiers, and MCP trust/tool-poisoning security; +9 refs) |
| 11 | Memory Systems | ● (drafted; deepened with lifecycle, retrieval signals, forgetting, graph memory, evaluation; +8 refs) |
| 12 | Orchestration with LangGraph | ● (drafted; deepened into design discipline for graph agents: state-as-contract + @tbl-agent-state + @fig-state-contract, single-purpose nodes, edges-as-control-policy, cycles-need-limits, checkpoint-vs-long-term-memory + @fig-checkpoint-vs-memory, interrupt-before-side-effects and the approve/edit/reject/respond decisions, a designing-for-production section (observability/testing/idempotency/when-overkill), and a full Ledgerly refund graph + @fig-ledgerly-graph; +3 refs: langchain2025persistence, langchain2025hitl, otel2026genai; em-dashes swept) |
| 13 | OpenAI Agents SDK | ● (drafted, concept-first pass; deepened with a Responses/SDK/LangGraph layer-choice table, a "lightweight does not mean loose" section on the four SDK contracts, handoff-vs-agent-as-tool distinction with a new figure, guardrails-are-checks-not-prompts, Ledgerly-framed worked example; +1 ref, +1 figure) |
| 14 | Multi-Agent Systems | ● (deepened: two-camps evidence, topology chooser, multi-agent debate + caution, collaboration design-space dials, conversation-vs-workflow coordination styles (AutoGen/CAMEL/MetaGPT), telephone/context-passing, MAST failure taxonomy; +9 refs, +3 figures) |
| 15 | Evaluation | ● (deepened ~2.85k→~5.5k words on "evaluate both result and route": why-agent-eval-is-different (output/outcome/trajectory + @fig-output-outcome-path, eval vocabulary + @fig-eval-loop, why-one-run-proves-nothing/pass^k), fuller measurement map + @fig-eval-levels, golden-set coverage + capability-vs-regression evals, a grading-what-a-score-can-hide section (judge calibration, trajectory grading, component-vs-e2e, RAG/retrieval evals), benchmarks deepened (SWE-bench Verified + BFCL + private-eval caution), outcome/trajectory harness extension, Ledgerly eval-suite anatomy + @fig-ledgerly-eval-anatomy, rewritten summary/exercises; +5 refs yao2024taubench, zheng2023judge, es2023ragas, openai2024swebenchverified, anthropic2026evals; em-dashes swept; book-reviewer band: strong pass. 4 new ch15 PNGs generated via code/figures/ch15_figures.py.) |
| 16 | Observability | ● (deepened ~2.3k→~5.6k words on "record the run, then watch production": why-agents-are-harder-to-watch (semantic/non-deterministic/stateful/long-running failures), span anatomy + @fig-span-anatomy (inputs/outputs make semantic failures debuggable), standardizing-the-recording + @fig-otel-standard (Dapper→W3C Trace Context→OpenTelemetry gen_ai.*/OpenInference, instrument-once-send-anywhere), sessions/runs/steps granularity + @fig-session-run-step (multi-turn failures live between runs), recording-at-scale/sampling (head vs tail), new Watching-production section + @fig-production-loop (online evaluation, explicit/implicit feedback, SLOs + drift), reworked debugging loop, new Safeguarding-the-recording section (OWASP sensitive-information-disclosure: redact/retain/access), expanded Ledgerly case (session double-refund, online judges, SLOs, redaction, +2 metric rows), rewritten summary/exercises; +3 refs sigelman2010dapper, w3c2021tracecontext, arize2024openinference; em-dashes swept (epigraph only); book-reviewer band: strong pass. 4 new ch16 PNGs to generate via code/figures/ch16_figures.py — terminal unavailable this session, run pending.) |
| 17 | Safety & Guardrails | ● (drafted, concept-first pass) |
| 18 | Deployment & Cost | ● (drafted, concept-first pass) |
| 19 | Computer Use & Embodiment | ● (drafted, concept-first pass) |
| 20 | Frontiers & Open Problems | ● (drafted, concept-first pass) |

### Continuous case study: the Ledgerly support agent

A single fictional system, the **Ledgerly** subscription-billing support agent, is
threaded through the book as a recurring `## Case study` section placed just before
each chapter's Summary. It matures one concept at a time, from "workflow or agent?"
to a deployed, cost-aware service. Each installment opens with a "Where we left off"
recap and ends with a hook to the next, so the reader can follow one system from idea
to production.

| Ch | Installment (what the case study advances) |
|----|--------------------------------------------|
| 1  | Workflow vs. agent → hybrid design; introduces Ledgerly |
| 4  | PEAS specification of the support task |
| 6  | The augmented LLM: tools, retrieval, memory |
| 8  | Sorting traffic into three lanes (single call / workflow / agentic) |
| 9  | Assembling the lanes from agentic patterns |
| 10 | The billing tools grouped by human-in-the-loop tier, exposed as a first-party MCP server |
| 11 | Episodic, semantic, procedural, and reflective customer memory as a lifecycle |
| 12 | Orchestration as a graph with a human-approval checkpoint on refunds |
| 15 | The evaluation set (golden tickets, adversarial cases) |
| 16 | Traces and metrics for a single ticket |
| 17 | Defense-in-depth guardrails on refunds |
| 18 | Cost levers, reliability (idempotent refunds), and shipping; closes the arc |

Each installment now also ends with a tiny **"🧾 Ledgerly so far"** recap callout, a
cumulative numbered list that folds prior capabilities into a summary line and flags the
newest with **"New this chapter."** The recaps run from Ch6 (the first built system) through
Ch18 (the finished system). A single reusable architecture figure, `fig-ledgerly-blueprint`
(source: `code/figures/ledgerly_blueprint.py`, `build(highlight=...)`), is introduced whole in
Ch9 and then re-rendered with one part lit in later chapters: memory (Ch11), observability
(Ch16), and the human-approval guardrail (Ch17), so the same system is highlighted part by
part rather than redrawn.

An editorial pass sharpened how the case study teaches. Ch6 now shows the *failure first*: a
bare model guesses a stale policy, cannot see the account, and forgets the customer, with a
table mapping each failure to the augmentation that cures it. Ch9 states the design as five
explicit decisions (one per Ledgerly need). Ch17's guardrail installment adds the *indirect*
prompt-injection variant, a malicious instruction planted in retrieved content, so the
recurring over-refund incident that runs through evaluation (Ch15), observability (Ch16),
safety (Ch17), and deployment (Ch18) matches the real agent threat model. Ch19 makes one
honest connection to the frontier: Ledgerly's clean API tools are contrasted with screen
automation for legacy systems that expose no API. The frontier chapters otherwise do not force
Ledgerly where it does not belong.