liveBook · Manning

Chapter 5: Reasoning: How your agent decides what to do next

What you will learn in chapter 5 of Designing AI Agents

This introduction defines reasoning as producing an inspectable decision from clearly represented state and evidence, then frames how to choose an appropriate reasoning approach.

After this chapter you will be able to

What it builds on

Section by section

Introduction

This introduction defines reasoning as producing an inspectable decision from clearly represented state and evidence, then frames how to choose an appropriate reasoning approach.

Key terms: semantic protocol, execution facts, current state, control signals, reasoning, inspectable decision artifact, shared world, task, evidence, cost

5.1 What is reasoning? From represented state to an inspectable decision

This section defines the information a reasoning decision uses, what its decision artifact must preserve, and where evidence-gathering ends and action permissions begin.

Key terms: goal, current state, evidence, constraints, decision artifact, uncertainty, next component, bounded reasoning loop, Action, Governance

5.1.1 Private reasoning, decision records, and execution traces

Distinguishes private model reasoning, visible decision records, and action-and-evidence traces, and explains what to retain when reviewing an agent’s decisions.

Key terms: private model reasoning, visible explanation, decision record, action-and-evidence trace, represented input, model and effort configuration, decision artifact, tool results, tests, state transitions

5.1.2 How the reasoning landscape changed

This section traces three shifts in reasoning technology and argues that architects must control both reasoning effort and the state it operates on.

Key terms: prompt-elicited reasoning, trained reasoning models, adaptive, budget-aware reasoning, visible reasoning, reasoning budget, represented state, evidence

5.1.3 What remains an architectural decision

The section explains why agent applications still need architectural reasoning controls even when models reason internally: the application controls the evidence, inspectable records, and orchestration around a decision.

Key terms: represented state, evidence, harness, provenance, reasoning summary, summarized thinking, decision records, evidence traces, portable control, explicit orchestration

5.1.4 The reasoning patterns at a glance

The section explains that reasoning patterns are optional, can be combined within a run, and are not always preferable to a precise external query.

Key terms: reasoning patterns, router, hypothesis loop, chain, deterministic code, external query

5.1.5 Testing and observing reasoning

This section shows how to evaluate reasoning from accepted task outcomes and evidence, use traces to diagnose decisions, and recognize the limits of those metrics.

Key terms: accepted result, evidence coverage, completed-task boundary, routing regret, false-simple outcomes, over-routing, diversity, information gain, refutation rate, baseline

5.2 Pattern: Chain-of-Thought

Introduces Chain-of-Thought as an application-owned sequence of checkable claims and explains when that structure is worth its cost.

Key terms: Chain-of-Thought, intermediate claims, dependency visibility, evidence references, private scratchpad, evidence, invariants, trigger, granularity, verification rule

5.2.1 Making the decision path explicit

This section treats visible Chain-of-Thought steps as inspectable decision records and compares three ways to produce or check them.

Key terms: Chain-of-Thought, structured rationale, decision record, hidden computation, Zero-shot CoT, Few-shot CoT, process supervision, outcome supervision, target workload

5.2.2 In production: Separate the decision record from the action trace

The section distinguishes the evidence and actions an agent retains from the decision record that explains its choice.

Key terms: action-and-evidence trace, decision record, Chain-of-Thought, private token trace

5.2.3 Building it

This section builds an application-visible reasoning record, uses step-level confidence to select a verification target, and handles malformed confidence ratings without guessing their scale.

Key terms: application-visible chain, COT_SYSTEM_PROMPT, one-claim-per-step, parse_chain, ReasoningStep, VERIFY_PROMPT, weakest_step, verify_chain, model-reported confidence, process supervision

5.2.4 Argus integration

This section shows how Argus makes code-review reasoning easier to inspect by decomposing its analysis and flagging a low-rated step.

Key terms: structured reasoning, score, flagged dependency, evidence, verifier

5.2.5 When it breaks

This section explains when an explicit Chain-of-Thought helps, how it can fail, and when to use verification or gather more evidence instead.

Key terms: unfaithful chains, evidence, invariant, chain collapse, chain inflation, few-shot structure, self-consistency, independent chains, stability, correlated chains

5.3 Pattern: Complexity-Based Routing

Introduces Complexity-Based Routing as a way to choose a reasoning policy based on a request’s needs, while keeping difficulty separate from consequence and accounting for routing costs.

Key terms: Complexity-Based Routing, reasoning policy, Reasoning × Route, difficulty, consequence, capacity, controls, risk overrides, classification overhead, misrouting cost

5.3.1 Route on difficulty, override on consequence

This subsection explains how to route reasoning by difficulty while letting consequences override the cheap path, and how to test whether routing actually pays off.

Key terms: difficulty decision, consequence override, governed handling, lightweight classifier, selected policy, safety override, counterfactual, accepted outcomes, rescue, router cost

5.3.2 In production: Route the decision, not only the model

This section explains that routing should place each decision with the mechanism that can handle it reliably and affordably, rather than merely select a model or effort setting.

Key terms: planner-worker systems, deterministic code, capable model, precise query, adaptive thinking, effort controls, max_tokens, harness-level decisions, consequence override, current practice

5.3.3 Building it

This section builds a three-tier complexity router and explains its cost, classification, and policy boundaries.

Key terms: SIMPLE, MODERATE, COMPLEX, classifier prompt, routing table, model configuration, tie-breaking rule, asymmetric recovery, ambiguous label, false simplicity

5.3.4 Argus integration

Shows how Argus routes code reviews by diff complexity while checking consequences separately, and how to evaluate the routed system against a baseline.

Key terms: router, review depth, diff's consequence, fast path, unrouted baseline, accepted defect findings, false-simple rescues, cost per accepted review, latency by class

5.3.5 When it breaks

This section explains when Complexity-Based Routing fails, how to keep difficulty separate from consequence, and when routing is worth using.

Key terms: false simplicity, difficulty, consequence, risk overrides, required evidence, governance, router overhead, drift, classifier, replay

5.4 Pattern: Parallel Exploration

This section introduces Parallel Exploration as a way to keep distinct reasoning candidates open and explains when the extra branch cost is justified.

Key terms: Parallel Exploration, Reasoning × Parallel, candidates, topology, branch cost, single-path baseline, materially different, cheap precise query

5.4.1 A concrete branch decision: Independence before concurrency

This section shows how to explore genuinely independent alternatives, compare their evidence, and decide whether explicit branching is worth its cost.

Key terms: branch, evidence packages, convergence, acceptance rule, branch isolation, genuine independence, separate agent contexts, explicit tree nodes, repeated constrained calls, Parallel Exploration

5.4.2 Branching, scoring, and pruning

This section explains how parallel reasoning preserves alternatives, evaluates them, and prunes or combines branches within a bounded budget.

Key terms: parallel exploration, Tree of Thoughts, pruning, explicit evaluator, Graph of Thoughts, Adaptive Graph of Thoughts, portfolio, disciplined convergence rule, Monte Carlo Tree Search, SWE-Search

5.4.3 Building it

This section shows how a compact Monte Carlo Tree Search implementation expands, scores, and selects LLM reasoning paths while guarding against misleading scores.

Key terms: expand, evaluate, ThoughtNode, branch budget, UCT, visit count, cumulative score, backpropagation, LLM value estimate, _parse_score

5.4.4 When it breaks

Explains when Parallel Exploration is worth its compute cost and how evaluator error and shallow breadth can undermine it.

Key terms: evaluator error, correct minority branch, executable checks, domain rules, separately validated judge, shallow breadth, branches, token multiplication, coverage, Parallel Exploration

5.5 Pattern: Iterative Hypothesis Testing

Introduces Iterative Hypothesis Testing as a bounded reasoning loop in which discriminating observations can change an agent’s explanation of an uncertain external state.

Key terms: Iterative Hypothesis Testing, Reasoning × Loop, discriminating observation, active hypothesis, external state, bounded experiment, deterministic retry policy, budget, stopping rule, GIS toolchain

5.5.1 The hypothesis-experiment loop

This section explains how an agent can investigate with explicit hypotheses and evidence, while avoiding unproductive repetitions and unjustified confidence.

Key terms: Iterative Hypothesis Testing, candidate hypotheses, predictions, evidence updates, ReAct, back-edge, bounded retry, evidence-rich handoff, stopping rules, explicit state

5.5.2 In Production: How coding agents actually debug

Shows how coding agents debug through a hypothesis-and-test loop, while distinguishing observable results from claims about reasoning or overall reliability.

Key terms: observe, root cause, experiment, gather evidence, revise, external result, acceptance condition, SWE-bench, design hypothesis, accepted outcomes

5.5.3 Building it

This section shows how to implement hypothesis testing with explicit hypothesis and experiment records, evidence updates, and a bounded investigation loop.

Key terms: Hypothesis, Experiment, active, supported, refuted, evidence_ratio, provenance, domain-specific evidence rules, initial observation, bounded executable action

5.5.4 Argus integration

Argus uses hypothesis testing to check a suspected fault within a bounded sandbox, without gaining permission to repair it.

Key terms: hypothesis testing, bounded test plan, execute_fn, sandboxed checks, recovery

5.5.5 When it breaks

This section explains how iterative hypothesis testing can fail and when to test, retry, use a simpler approach, or stop.

Key terms: Confirmation bias, predictions, observations, candidates, Confidence drift, evidence, hypothesis set, handoff, Environmental damage, Blast Radius Control

5.6 Composing reasoning patterns around the decision

This section shows how to combine reasoning patterns around a shared decision contract, choose their order from evidence and uncertainty, and judge the complete run rather than treating deeper reasoning as inherently better.

Key terms: reasoning contract, Complexity-Based Routing, reasoning topology, cheap external evidence, deterministic recovery, replay tests, consequence, cost per accepted outcome, time to decisive evidence, false convergence

5.7 Reasoning branches and collaboration

This section explains how to create meaningful reasoning branches and where branching ends and collaboration begins.

Key terms: branch independence, distinct frame, authoritative evidence, convergence rule, Parallel Exploration, Collaboration, Fan-Out/Gather, Adversarial Review

5.8 Argus checkpoint: What the agent can do now

This checkpoint summarizes the inspectable reasoning Argus can perform and the limits on what it can execute.

Key terms: inspectable decisions, appropriate depth, claim-and-dependency chain, bounded sandbox checks, evidence interface, telemetry schema, low self-ratings, actual evidence, teaching system, production state

5.9 Summary

5.10 References

This section lists the sources cited in the chapter on agent reasoning.

Where this is used later

Concepts explained in this chapter

← Chapter 4: Memory: What your agent remembers shapes what it becomes Chapter 6: Action: How your agent acts is where strategy meets consequences →

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.