Chapter 1: The agent paradigm shift
The chapter introduction uses a coding-agent failure to explain why model-directed decisions require agent design patterns, while connecting those patterns to established engineering practice.
After this chapter you will be able to
- Missing project knowledge. Explain why the coding agent's rollout implementation was a problem even though it looked reasonable on its own, and why choosing the right implementation calls for more than a conventional code pattern.
- Model-directed runtime decisions. Describe what agent design patterns address when an AI model makes runtime decisions, and why that decision-maker creates a reliability challenge.
- Model-Directed Agent Control. Distinguish an agent from a fixed pipeline that calls an LLM: in an agent, the model chooses the next action at runtime within an engineered harness.
- Bounded Feedback Loop. Explain the roles of the deciding model, the bounding harness, and the feedback loop that makes each result the next observation until completion or a stopping rule.
- Model-directed runtime control. Distinguish a developer-fixed sequence from an agent loop in which the model chooses actions at runtime and may revisit a step or stop when new evidence appears.
- Bounded resource allocation. Explain the division between the model spending resources to pursue possibilities and the harness budgeting, constraining, routing, and verifying that spending.
- Design-Time and Runtime Control. Explain how the developer’s role changes from scripting structural decisions to setting the actors and constraints within which a model reasons at runtime.
- Uncertainty as an Operating Condition. Explain why uncertainty must be accounted for in an agent’s architecture from the start, rather than treated only as an exception to contain.
- Output Uncertainty and Retries. Describe how the same prompt can yield different model responses and why retrying an LLM call need not reproduce the earlier result.
- Unpredictable Runtime Decisions. Explain behavioral uncertainty as the agent making runtime choices whose sequence and content were not fixed at design time.
- Changing External Environment. Describe environmental uncertainty as changes in the world or data sources between the agent’s observations.
- Pattern Lineages and Runtime Control. Distinguish what object-oriented, distributed-systems, and agent patterns organize, and explain what changes when a model selects actions at runtime.
- Runtime Decisions and Prompt Interfaces. Distinguish agent systems from GoF-style systems in who chooses a strategy and how components communicate.
- Distributed State Management. Explain why agent state needs persistence, provenance, and attention policies.
- Failure as a Design Constraint. Explain why agent failure modes and their operational effects must shape patterns from the start.
- Engineer control over agents. Explain why agent engineering is compared to gardening: engineers choose the conditions and boundaries that shape an agent’s behavior rather than directly controlling every step.
- Cognitive function reference architecture. Describe how the seven cognitive functions organize agent design choices, and distinguish alternatives within a function from the way work is wired.
- Review context and initial decisions. Trace how Argus moves from a caching pull request to an initial review: it selects relevant code, retrieves prior context, adjusts its reasoning to the change’s complexity, and takes checked actions.
- Review refinement and posting controls. Trace how Argus critiques its draft, brings in a specialist for a high-severity finding, and checks authority and evidence before posting the review.
- Modular functions and execution choices. Distinguish the seven functions that describe what Argus does from execution topology, which describes how a function runs; explain why teams can add capabilities incrementally without granting human-like trust.
- Harness constraints and engineering leverage. Explain how the agent harness turns design choices into constraints and budgets, and why engineers focus on those constraints, acceptable behavior, and evaluation as implementation becomes more model-assisted.
- Operating tradeoffs of design choices. Explain how choices about context, tool permissions, and verification affect an agent’s reliability, latency, cost, or risk. State that a successful design fits those outcomes to the task.
- Comparable evidence for pattern choices. Explain why patterns serving the same cognitive function should be compared on end-to-end outcomes using a fixed evaluation harness. Describe the limits of such a comparison: it applies to a defined workload and operating point, and no single benchmark settles every architecture question.
Section by section
Introduction
The chapter introduction uses a coding-agent failure to explain why model-directed decisions require agent design patterns, while connecting those patterns to established engineering practice.
- Missing project knowledge: Explain why the coding agent's rollout implementation was a problem even though it looked reasonable on its own, and why choosing the right implementation calls for more than a conventional code pattern.
Why it matters: A locally sensible change can still be wrong for the system it joins. - Model-directed runtime decisions: Describe what agent design patterns address when an AI model makes runtime decisions, and why that decision-maker creates a reliability challenge.
Why it matters: The system must remain dependable even when its decision-making component is not fully predictable. - Earlier patterns as ancestors: Explain how agent design patterns relate to earlier engineering patterns without treating the underlying uncertainty as identical.
Why it matters: Existing reliability instincts remain useful, but they must be applied to a different source of uncertainty.
Key terms: working context, rollout utility, Gang of Four patterns, agent design patterns, runtime, probabilistic, opaque, distributed-systems patterns, engineering ancestors, decision-maker
1.1 What exactly is an agent?
This section defines an agent by model-directed control flow, explains how its harness and feedback loop bound that control, and introduces the vocabulary used to describe agent systems.
- Model-Directed Agent Control: Distinguish an agent from a fixed pipeline that calls an LLM: in an agent, the model chooses the next action at runtime within an engineered harness.
Why it matters: This distinction tells you when you are designing an agent rather than adding an LLM call to a preset workflow. - Bounded Feedback Loop: Explain the roles of the deciding model, the bounding harness, and the feedback loop that makes each result the next observation until completion or a stopping rule.
Why it matters: It explains how an agent can make flexible choices without having unrestricted autonomy. - Agent Architecture Vocabulary: Distinguish an agent system, a cognitive function, a pattern, and an execution topology as the section defines them.
Why it matters: These terms let you describe separately what responsibility a design addresses and how it runs. - Finite Context And Tokens: Explain what the context window and tokens are, and why token limits affect what an agent can see in a call and the cost of a design.
Why it matters: An agent's available information and operating cost both depend on finite token capacity. - Tools As External Actions: Describe a tool as a function an agent can invoke to read or change the outside world, rather than merely produce text.
Why it matters: Tools are the means by which an agent's choices can have effects beyond its generated response.
Key terms: agent, model-directed control flow, model, harness, feedback loop, stopping rule, agent system, cognitive function, pattern, execution topology
1.2 From fixed control flow to model-directed control
This section contrasts fixed software control flow with model-directed agent decisions and explains why engineers must design resource budgets, boundaries, and specifications rather than every branch.
- Model-directed runtime control: Distinguish a developer-fixed sequence from an agent loop in which the model chooses actions at runtime and may revisit a step or stop when new evidence appears.
Why it matters: It explains why designing an agent is not the same as coding a fixed workflow. - Bounded resource allocation: Explain the division between the model spending resources to pursue possibilities and the harness budgeting, constraining, routing, and verifying that spending.
Why it matters: It turns agent autonomy into a design problem with explicit limits and evidence of completion. - Specification over implementation: Explain the implementation plateau and design inversion: after basic prompt competency, output quality depends more on the agent’s specification than on further improvements to its code.
Why it matters: It identifies where the section says engineers gain the most leverage when improving an agent.
Key terms: fixed control flow, agent loop, model-directed control, bounded resource allocation, harness, context window, task boundary, implementation plateau, design inversion, specification
1.2.1 What breaks and why
The section uses four classical design patterns to show why agent systems move decisions from developer-written control flow to model-directed runtime behavior.
- Design-Time and Runtime Control: Explain how the developer’s role changes from scripting structural decisions to setting the actors and constraints within which a model reasons at runtime.
Why it matters: This shift explains why familiar patterns need rethinking without making them useless everywhere. - Singleton and Distributed State: Explain why one shared instance cannot guarantee an agent a consistent working view, and identify the resulting memory-design questions.
Why it matters: A single shared object cannot settle which information an agent should retain or trust. - Factory and Open Action Space: Contrast a factory’s fixed product taxonomy with an agent’s open-ended actions and explain the need for capability discovery based on intent.
Why it matters: An agent cannot rely solely on a developer’s compile-time list of possible actions. - Observer and Attention Limits: Explain why notifying subscribers for every event does not scale to large event cascades and how active perception changes the agent’s response.
Why it matters: Receiving more events is not useful if the agent cannot allocate attention to what matters. - Strategy Selection Inside the Agent: Describe how an agent, rather than a developer, selects and revises a sequence of actions while carrying out a task.
Why it matters: A task may require many choices and course corrections that a developer did not script individually.
Key terms: GoF, design time, runtime, model, Singleton, working state, volatile context, durable task records, retrieved evidence, Factory
1.2.2 Uncertainties of agent systems
The section explains why agent architectures must account for uncertainty from the start and distinguishes uncertainty in model outputs, agent behavior, and the environment.
- Uncertainty as an Operating Condition: Explain why uncertainty must be accounted for in an agent’s architecture from the start, rather than treated only as an exception to contain.
Why it matters: This premise explains why the section treats uncertainty as an architectural concern. - Output Uncertainty and Retries: Describe how the same prompt can yield different model responses and why retrying an LLM call need not reproduce the earlier result.
Why it matters: A retry is not necessarily a repeat when the model can produce a new answer. - Unpredictable Runtime Decisions: Explain behavioral uncertainty as the agent making runtime choices whose sequence and content were not fixed at design time.
Why it matters: Behavioral uncertainty means a designer cannot assume every step of an agent run is predetermined. - Changing External Environment: Describe environmental uncertainty as changes in the world or data sources between the agent’s observations.
Why it matters: An agent’s earlier observation may no longer describe the world it is acting in.
Key terms: uncertainty, operating condition, architecture, output uncertainty, non-deterministic outputs, idempotency, behavioral uncertainty, runtime decisions, ReAct agent, environmental uncertainty
1.3 What makes agent patterns fundamentally different
This section explains how agent patterns inherit familiar engineering pressures while changing their implementation because a probabilistic model selects actions at runtime.
- Pattern Lineages and Runtime Control: Distinguish what object-oriented, distributed-systems, and agent patterns organize, and explain what changes when a model selects actions at runtime.
Why it matters: This distinction helps you recognize what is familiar about agent design and what requires new design choices. - Transferable Engineering Instincts: Explain why earlier engineering instincts help with agent architecture while their mechanisms cannot simply be copied unchanged.
Why it matters: Familiar principles can guide an agent design without hiding the differences in how that design must work.
Key terms: object-oriented patterns, distributed-systems patterns, agent patterns, probabilistic model, isolation, reconciliation, durable state, budgets, context, tools
1.3.1 What this changes for developers
The section contrasts agent systems with conventional design patterns and identifies the resulting design constraints for developers.
- Runtime Decisions and Prompt Interfaces: Distinguish agent systems from GoF-style systems in who chooses a strategy and how components communicate.
Why it matters: These differences change what developers can specify in advance and what they must constrain at runtime. - Distributed State Management: Explain why agent state needs persistence, provenance, and attention policies.
Why it matters: Making state explicit helps teams account for conflicting evidence and reproduce behavior. - Failure as a Design Constraint: Explain why agent failure modes and their operational effects must shape patterns from the start.
Why it matters: Treating failures as design constraints makes agent behavior more reviewable and operable. - Extension-Oriented Agent Systems: Describe why the section treats modular extension as a design consideration for agent systems.
Why it matters: Planning for extension lets an agent platform accommodate new capabilities without treating each addition as a one-off redesign.
Key terms: GoF, LLM, prompts, typed method signatures, volatile context, durable task records, retrieved evidence, tool outputs, persistence, provenance
1.4 Designing agents through cognitive functions
This section frames agent design as shaping model behavior through engineering choices and introduces cognitive functions as a reference architecture for those choices.
- Engineer control over agents: Explain why agent engineering is compared to gardening: engineers choose the conditions and boundaries that shape an agent’s behavior rather than directly controlling every step.
Why it matters: This distinction clarifies what an engineer can design even when the agent chooses its own steps. - Cognitive function reference architecture: Describe how the seven cognitive functions organize agent design choices, and distinguish alternatives within a function from the way work is wired.
Why it matters: This gives the reader a way to organize design choices without confusing a function, a pattern, and the wiring of the work.
Key terms: models, context, memory, tools, guardrails, evaluation, perception, reasoning, action, reflection
1.4.1 Argus reviews a pull request
Argus’s pull-request review illustrates how seven cognitive functions fit together, while showing why agent engineers must design the harness and specifications that constrain the resulting behavior.
- Review context and initial decisions: Trace how Argus moves from a caching pull request to an initial review: it selects relevant code, retrieves prior context, adjusts its reasoning to the change’s complexity, and takes checked actions.
Why it matters: These functions explain how Argus spends its attention and effort on the evidence most relevant to the review. - Review refinement and posting controls: Trace how Argus critiques its draft, brings in a specialist for a high-severity finding, and checks authority and evidence before posting the review.
Why it matters: Finding an issue is not the same as producing a sound review or having permission to post it. - Modular functions and execution choices: Distinguish the seven functions that describe what Argus does from execution topology, which describes how a function runs; explain why teams can add capabilities incrementally without granting human-like trust.
Why it matters: This separation lets teams choose capabilities and execution effort without confusing sophistication with permission. - Harness constraints and engineering leverage: Explain how the agent harness turns design choices into constraints and budgets, and why engineers focus on those constraints, acceptable behavior, and evaluation as implementation becomes more model-assisted.
Why it matters: Reliable, cost-effective agents depend on deliberately shaped operating conditions, not just capable models. - Specification and running agent: Distinguish the specification from the running agent and explain the roles of durable project specifications and change-specific specifications.
Why it matters: Keeping enduring rules separate from a change plan makes the intended constraints clearer when agents generate code.
Key terms: Perception, Memory, Reasoning, Action, context triage, attention budget, Reflection, Collaboration, Governance, critic
1.4.2 How this book turns design choices into evidence
The section explains why agent design choices must be judged by their operating tradeoffs and by comparable evidence, not by a pattern name or framework alone.
- Operating tradeoffs of design choices: Explain how choices about context, tool permissions, and verification affect an agent’s reliability, latency, cost, or risk. State that a successful design fits those outcomes to the task.
Why it matters: A design improvement in one dimension may impose a cost or risk elsewhere. - Comparable evidence for pattern choices: Explain why patterns serving the same cognitive function should be compared on end-to-end outcomes using a fixed evaluation harness. Describe the limits of such a comparison: it applies to a defined workload and operating point, and no single benchmark settles every architecture question.
Why it matters: Comparable measurements let you test a design choice rather than assume that a pattern will help.
Key terms: reliability, latency, cost, operational risk, fixed evaluation harness, end-to-end outcomes, defined workload, operating point, benchmark
1.5 Summary
1.6 References
This section lists sources cited in the chapter without explaining new concepts or procedures.
Where this is used later
- Design the cognitive engine: The Perception-Reasoning-Action loop (chapter 2) · The Perception-Reasoning-Action loop develops the idea of decisions informed by subsequent observations.
- Set trust boundaries before granting autonomy (chapter 2) · Trust boundaries build on the harness's role in bounding autonomy.
- Use the two-axis map to compare pattern choices (chapter 2) · The two-axis map compares pattern choices using cognitive function and execution topology.
- The context window as a treatment budget (chapter 3) · Context-window limits become a design constraint for perception.
- Pattern: Tool Dispatch (chapter 6) · Tool Dispatch addresses the selection and use of tools.
- What is memory? State, persistence, and knowledge across sessions (chapter 4) · Develops the state, persistence, and memory questions introduced here.
- What is reasoning? From represented state to an inspectable decision (chapter 5) · Develops how an agent decides what to do next.
- Turn capabilities into a system architecture (chapter 2) · The system architecture must account for uncertainty in agent operation.
Concepts explained in this chapter
- cognitive functionA recurring responsibility in an agent architecture, such as perception, memory, reasoning, or action.
- execution topologyA structural arrangement that determines how steps or agents are organized and executed in an agent system.
- agent systemA software system in which an AI model perceives context, reasons, and acts through available capabilities.
- agent design patternA reusable architectural solution for building systems in which an AI model makes decisions at runtime.
- agent harnessA software layer around an agent that manages execution, resources, tools, delegation, context, and verification.
- harness engineeringThe practice of engineering constraints and supporting mechanisms around an AI agent to prevent recurring mistakes and govern its work.
- uncertaintyUncertainty is the lack of complete predictability about a system's state, behavior, or outcome.
- agentAn autonomous software system that performs tasks by perceiving information, reasoning, and taking actions.
- agent architectureThe design of an agent system's model, control, constraints, resources, and execution mechanisms.
- specificationA formal or informal description of required behavior, constraints, and objectives for a system.
- token leverageThe ratio of agent output quality to the token cost required to produce it.
- specification-driven developmentA software-development approach in which structured specifications guide implementation and define intended behavior.
- agent loopAn iterative agent-control pattern in which an agent perceives, reasons, acts, and reflects, with subsequent steps selected dynamically.
- context windowThe bounded sequence of tokens that a language model can attend to during an interaction.
- tool registryA collection of tools available to an agent, together with information needed to identify or invoke them.
- working memoryThe limited information temporarily available to an agent or model while it performs a task.
- semantic routingA routing mechanism that selects a processing path based on the meaning of a request.
- plan-and-executeAn agent pattern in which planning precedes execution of the planned steps.
- verificationThe process of checking whether a system or result satisfies specified requirements or properties.
- actionAn agent capability for executing external operations or producing artifacts in response to reasoning.
- collaborationAn agent capability for coordinating information or activity with other agents or humans.
- governanceThe agent capability and control framework for enforcing policies, constraints, oversight, and accountability.
- memoryAn agent capability for retaining or retrieving information across or within tasks.
- perceptionAn agent capability for identifying relevant information from inputs and loading context for subsequent processing.
- reasoningAn agent capability for evaluating information, forming hypotheses, and selecting conclusions or actions.
- reflectionAn agent capability for inspecting and revising its own intermediate results or proposed actions.
- isolationIsolation is a technique for containing the effects of a failure or operation so they do not propagate across system boundaries.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
