Chapter 2: Working with ADPs: Building a mortgage advisor tool
This introduction frames a reliable mortgage-advisor agent as a case study and outlines its information-gathering, analysis, reporting, and compliance workflow using agent design patterns.
After this chapter you will be able to
- Mortgage advisor reliability requirements. Explain why a mortgage advisor requires an agent design beyond a general conversational assistant with search. Describe the need to ask targeted questions, use specialized and current knowledge, rely on verified calculation tools, and respect financial-advice regulations.
- Mortgage advisory pipeline. Describe the proposed mortgage-advisor flow: start from the user's requested advice, gather the needed information through follow-up questions, run relevant analyses in parallel, aggregate them into a report, and check the report before showing it to the user.
- Agent Flow Diagram purpose. Explain why Agent Flow Diagrams (AFDs) are used for agents rather than treating them like ordinary flow diagrams. Describe how AFDs show both deterministic components and agent-directed, potentially parallel behavior without focusing on precise timing or internal model complexity.
- AFD visual legend. Describe the main AFD symbols and connections: filled, hollow, and half-filled circles; directional solid arrows; bidirectional dashed lines; and named pattern ovals or containers. Distinguish unintelligent code, a single AI-model invocation, and an AI invocation followed by navigation code.
- Mortgage advisor flow. Trace the mortgage advisor's high-level flow from initial user questioning through parallel analysis by a supervised Team of ReAct agents, report writing, compliance checking, and either user delivery or feedback-driven rewriting. Identify the failed compliance check as the path that creates the refinement loop.
- Runtime responsibilities. Describe what an agent runtime does and where an agent lives. State that the runtime handles message registration, model and tool invocation, response cleanup, logging, state saving, and billing, while its deployment location determines where the agent operates.
- Single stateful orchestrator. Explain the orchestrator’s role as the single component that tracks an agent’s current state and makes it follow its intended process. Distinguish an orchestrator implemented as a prompted or post-trained model from one implemented as stateful code.
- Bounded compliance refinement flow. Trace the mortgage advisor’s orchestration flow: gather initial information, perform specialized analyses, draft a report, check it for compliance and writing feedback, and refine it after failed compliance checks. State that success occurs with a compliant report, while failure occurs after three unsuccessful attempts to cap cost and prevent indefinite refinement.
- Interlocutor proactive information gathering. Explain how an Interlocutor gathers information through a conversation by pursuing its own internal agenda rather than merely responding to the user's questions.
- Conversational shopping-list intake. Describe how an Interlocutor uses shopping lists of required facts to adaptively collect information for a particular mortgage inquiry, including following up on incomplete or ambiguous input.
- Interlocutor completion and state contract. Trace the implementation-facing outputs of the mortgage advisor's Interlocutor: it decides when information gathering is done, returns a done flag and user response from run(), and maintains its incrementally enriched state close to its own logic.
- Single-agent context limits. Explain why putting mortgage knowledge, advice reasoning, user information, and precision tools into one linear agent workflow is impractical. Describe how growing context degrades LM performance and can exceed effective context limits.
- Specialist agent team. Describe the shift from one all-powerful agent to a multi-agent system composed of task-specialist subagents. Explain that specialists can be developed, refined, and tested independently while higher-level orchestration coordinates their work.
- ReAct analyst abstraction. Explain the shared ReAct abstraction for mortgage analysts: an agent continuously reasons about a query and can call tools while working. Describe how the base implementation is initialized with a system prompt, a payload-filled user prompt template, and named callable tools.
- Specialized analyst configuration. Describe how one base ReAct agent can take on different mortgage-analyst personas through its system prompt and user prompt template, then be connected to the tools appropriate to that role. State that an analyst such as RateFairnessAnalyst is called using information gathered by the Interlocutor.
- Supervised analyst team. Describe the supervised team used for the analysis stage: one supervisor coordinates the analyst ReAct agents so they take turns contributing to an aggregate analysis.
- Subagents as supervisor tools. Explain that the supervisor splits the larger analysis task into subtasks and invokes its subagents as tools, using each analyst's specialized expertise.
- Errand pattern definition. Explain what an errand is in this book: a simple LM call or short sequence of LM calls, optionally interleaved with deterministic code for extracting or verifying responses.
- Report-writing errand flow. Describe how the report-writing errand takes analyst outputs and feedback from previous writing attempts, then calls an LM to produce a report according to the system prompt's instructions and feedback.
- Guardrail verdict and feedback. Explain that a guardrail uses one or more AI models to decide whether an input may proceed to a user or another agent component. Describe its usual pass/fail or accept/reject verdict and its optional explanation or feedback for improving a rejected input.
- Compliance feedback routing. Describe how the mortgage advisor's ComplianceGuardrail prevents a noncompliant report from reaching the user by returning a verdict and feedback. Explain that negative feedback is routed back to the report-writing errand for refinement.
- Compliance feedback refinement loop. Explain how the MortgageAdvisor uses the ComplianceGuardrail's feedback and verdict to make a later ReportingErrand attempt improve the report.
- Bounded feedback retries. Describe how the state-machine loop aggregates feedback from subsequent trials and supplies it to the ReportingErrand during the two retrials permitted by a max_compliance_retries limit of 3.
What it builds on
- Why do we design agents? (chapter 1) · The distinction between a general conversational assistant and a deliberately designed agent.
- What can we do with ADPs? (chapter 1) · The idea that agent design patterns can address recurring agent-design problems.
- What is an agent? (chapter 1) · The basic idea of an agent performing work toward a user goal.
Section by section
Introduction
This introduction frames a reliable mortgage-advisor agent as a case study and outlines its information-gathering, analysis, reporting, and compliance workflow using agent design patterns.
- Mortgage advisor reliability requirements: Explain why a mortgage advisor requires an agent design beyond a general conversational assistant with search. Describe the need to ask targeted questions, use specialized and current knowledge, rely on verified calculation tools, and respect financial-advice regulations.
Why it matters: These reliability requirements determine why the mortgage advisor is composed from multiple specialized agent patterns. - Mortgage advisory pipeline: Describe the proposed mortgage-advisor flow: start from the user's requested advice, gather the needed information through follow-up questions, run relevant analyses in parallel, aggregate them into a report, and check the report before showing it to the user.
Why it matters: This end-to-end flow is the architecture that the remaining chapter breaks into individual patterns and components. - Compliance refinement limit: Describe the report-compliance refinement loop: if the report's language fails the mortgage-regulation check, the agent rewrites it using the feedback; after three failed attempts, it tells the user it cannot generate a report.
Why it matters: A bounded rewrite loop prevents noncompliant language from being delivered while ensuring the agent eventually stops instead of retrying indefinitely.
Key terms: mortgage advisor, generalist conversational assistant, specialized knowledge, standardized assessments, verified tools, financial advice regulations, advisory pipeline, kickoff message, analyses in parallel, aggregate
2.1 Agent Flow Diagrams
This section introduces Agent Flow Diagrams as a simple notation for visualizing agent behavior and uses one to outline the mortgage advisor workflow.
- Agent Flow Diagram purpose: Explain why Agent Flow Diagrams (AFDs) are used for agents rather than treating them like ordinary flow diagrams. Describe how AFDs show both deterministic components and agent-directed, potentially parallel behavior without focusing on precise timing or internal model complexity.
Why it matters: AFDs provide the shared visual language used to reason about the mortgage advisor design. - AFD visual legend: Describe the main AFD symbols and connections: filled, hollow, and half-filled circles; directional solid arrows; bidirectional dashed lines; and named pattern ovals or containers. Distinguish unintelligent code, a single AI-model invocation, and an AI invocation followed by navigation code.
Why it matters: Reading the legend lets you interpret the components and control paths in the mortgage advisor diagram. - Mortgage advisor flow: Trace the mortgage advisor's high-level flow from initial user questioning through parallel analysis by a supervised Team of ReAct agents, report writing, compliance checking, and either user delivery or feedback-driven rewriting. Identify the failed compliance check as the path that creates the refinement loop.
Why it matters: This end-to-end flow is the concrete design that the following sections unpack into individual ADPs.
Key terms: agent flow diagrams, AFDs, deterministic behavior, nondeterministic behavior, contexts, filled circle, hollow circle, half-filled circle, solid line with an arrow end, dashed line with circular ends
2.2 Runtime and orchestration
This section defines the runtime and single stateful orchestrator that drive the mortgage advisor’s end-to-end workflow, including bounded report refinement.
- Runtime responsibilities: Describe what an agent runtime does and where an agent lives. State that the runtime handles message registration, model and tool invocation, response cleanup, logging, state saving, and billing, while its deployment location determines where the agent operates.
Why it matters: The runtime supplies the operational loop and services that let an agent run beyond a single model call. - Single stateful orchestrator: Explain the orchestrator’s role as the single component that tracks an agent’s current state and makes it follow its intended process. Distinguish an orchestrator implemented as a prompted or post-trained model from one implemented as stateful code.
Why it matters: A stateful orchestrator allows the mortgage advisor to continue a multi-stage process rather than merely react to each user message. - Bounded compliance refinement flow: Trace the mortgage advisor’s orchestration flow: gather initial information, perform specialized analyses, draft a report, check it for compliance and writing feedback, and refine it after failed compliance checks. State that success occurs with a compliant report, while failure occurs after three unsuccessful attempts to cap cost and prevent indefinite refinement.
Why it matters: The bounded loop turns compliance feedback into a controlled retry process with explicit success and failure outcomes. - State persistence for remote operation: Describe why a remotely deployed, user-facing version of the mortgage advisor would need to serialize orchestrator state and either send it with responses or store it in a session database. Contrast the local console loop with a listener server loop for remote communication.
Why it matters: State persistence is required when a multi-step agent must resume its workflow across remote user interactions.
Key terms: runtime, tool calls, intermediate agent states, orchestrator, stateful, distributed orchestration, current state, refinement feedback, compliance checks, Success
2.3 Gathering information with the Interlocutor
This section introduces the Interlocutor pattern as a proactive conversational agent that gathers and maintains the information needed before mortgage advice can be produced.
- Interlocutor proactive information gathering: Explain how an Interlocutor gathers information through a conversation by pursuing its own internal agenda rather than merely responding to the user's questions.
Why it matters: An advisor needs enough situation-specific information to make advice fit the user rather than offering generic responses. - Conversational shopping-list intake: Describe how an Interlocutor uses shopping lists of required facts to adaptively collect information for a particular mortgage inquiry, including following up on incomplete or ambiguous input.
Why it matters: Shopping lists ensure that the conversation obtains the specific inputs needed for the kind of mortgage assessment being requested. - Interlocutor completion and state contract: Trace the implementation-facing outputs of the mortgage advisor's Interlocutor: it decides when information gathering is done, returns a done flag and user response from run(), and maintains its incrementally enriched state close to its own logic.
Why it matters: This contract lets the orchestrator know when it can advance while keeping collected conversational context managed by the component that gathered it.
Key terms: Interlocutor, interlocutors, internal agenda, due diligence, shopping lists, mortgage advisory inquiry, net income, intended mortgage length, ideal monthly payment range, interest rate
2.4 Dispatching a team of analysts to produce advice
This section motivates replacing a single overloaded mortgage-advice agent with a supervised team of independent specialist agents.
- Single-agent context limits: Explain why putting mortgage knowledge, advice reasoning, user information, and precision tools into one linear agent workflow is impractical. Describe how growing context degrades LM performance and can exceed effective context limits.
Why it matters: Context limits make decomposition necessary rather than merely an organizational preference. - Specialist agent team: Describe the shift from one all-powerful agent to a multi-agent system composed of task-specialist subagents. Explain that specialists can be developed, refined, and tested independently while higher-level orchestration coordinates their work.
Why it matters: Specialization lets the system divide complex advice work into manageable components without requiring every agent to handle every detail. - Supervised mortgage analyst team: State the team topology selected for the mortgage advisor: mortgage analysts with a single supervisor that calls on them as needed to accomplish the user's goal. Distinguish this chosen simple design from other possible centralized, hierarchical, chained, or decentralized agent-team structures.
Why it matters: The selected supervisor-and-analyst structure sets up the bottom-up implementation of the mortgage analyst team.
Key terms: linear agentic workflow, context size, effective context-size limits, LMs, agent teams, multi-agent system, subagents, task specialists, orchestration, divide and conquer
2.4.1 Mortgage analysts as children of the ReAct abstraction
This section defines a reusable ReAct-based analyst agent and shows how specialized mortgage analysts are created by configuring it with prompts, payload information, and tools.
- ReAct analyst abstraction: Explain the shared ReAct abstraction for mortgage analysts: an agent continuously reasons about a query and can call tools while working. Describe how the base implementation is initialized with a system prompt, a payload-filled user prompt template, and named callable tools.
Why it matters: A common ReAct abstraction lets different analyst roles share one execution model while receiving the context and tools their work requires. - Specialized analyst configuration: Describe how one base ReAct agent can take on different mortgage-analyst personas through its system prompt and user prompt template, then be connected to the tools appropriate to that role. State that an analyst such as RateFairnessAnalyst is called using information gathered by the Interlocutor.
Why it matters: Configuring prompts and tools instead of rebuilding the agent makes it practical to assemble a team of focused analysts. - Analyst results and visibility: Distinguish messages or information that may be passed to the user from an analyst's final result, which will likely be returned to the larger component that invoked the subagent. Describe the optional real-world practice of streaming the ReAct loop conversation so inspected team work is visible.
Why it matters: Separating user-facing progress from a subagent result clarifies how an analyst fits inside a larger agent workflow.
Key terms: ReAct agent, system prompt, user prompt template, payload, named callable tools, working loop, analyst persona, RateFairnessAnalyst, Interlocutor, messages
2.4.2 Bundling analysts into a supervised team
This subsection explains how the mortgage advisor combines specialized analyst agents under one supervisor to complete an aggregate analysis.
- Supervised analyst team: Describe the supervised team used for the analysis stage: one supervisor coordinates the analyst ReAct agents so they take turns contributing to an aggregate analysis.
Why it matters: A supervisor provides a way to turn several specialized analyses into one coordinated result. - Subagents as supervisor tools: Explain that the supervisor splits the larger analysis task into subtasks and invokes its subagents as tools, using each analyst's specialized expertise.
Why it matters: Treating subagents as tools gives the supervisor a practical way to delegate parts of a larger task to the right specialist.
Key terms: supervisor, analyst ReAct agents, aggregate analysis, analysis stage, subtasks, subagents, tools, specialized expertise, supervisor agent
2.5 The report-writing errand
This section presents report writing as an Errand: a simple LM-based step that turns analyst outputs and prior feedback into the mortgage advisory report.
- Errand pattern definition: Explain what an errand is in this book: a simple LM call or short sequence of LM calls, optionally interleaved with deterministic code for extracting or verifying responses.
Why it matters: Errands provide a lightweight way to isolate straightforward agent work without adding tools or iterative reasoning. - Report-writing errand flow: Describe how the report-writing errand takes analyst outputs and feedback from previous writing attempts, then calls an LM to produce a report according to the system prompt's instructions and feedback.
Why it matters: This explains how the mortgage advisor converts specialized analysis into the user-facing advice. - Errand quality dependencies: Justify why a simple report-writing errand can still require a powerful writing model and a detailed prompt: errands have no tools or iterative reasoning loops, so outcome quality depends heavily on the chosen prompt and model.
Why it matters: Simple implementation does not guarantee simple quality requirements, especially for a user-facing report. - Structured report extraction: Describe the optional elaboration in which the model thinks first, places its final answer in <report> tags, and deterministic code extracts that tagged report with a regular expression.
Why it matters: Tagged output and deterministic extraction can separate the final report from other model output.
Key terms: errand, LM calls, deterministic code, payloads, response-processing code, report-writing errand, analysts' outputs, feedback, system prompt, report
2.6 Ensuring compliance with guardrails
This section adds a compliance guardrail to the mortgage advisor so that only compliant reports reach users and rejected reports can be refined.
- Guardrail verdict and feedback: Explain that a guardrail uses one or more AI models to decide whether an input may proceed to a user or another agent component. Describe its usual pass/fail or accept/reject verdict and its optional explanation or feedback for improving a rejected input.
Why it matters: A guardrail creates an explicit decision point that can stop unsuitable agent output before it is delivered. - Compliance feedback routing: Describe how the mortgage advisor's ComplianceGuardrail prevents a noncompliant report from reaching the user by returning a verdict and feedback. Explain that negative feedback is routed back to the report-writing errand for refinement.
Why it matters: Routing a rejection back to the writer turns compliance checking into a controlled correction path instead of exposing a noncompliant report. - Overlapping pattern characteristics: Distinguish a component's pattern characteristics from a fixed single-pattern classification. Explain that the ComplianceGuardrail can resemble an errand because it produces feedback for refinement, while not all guardrails are errands, especially in performance-critical or highly sensitive uses.
Why it matters: Recognizing overlapping patterns helps you compose agent components for their behavior instead of forcing each implementation into one rigid category. - Sensitive and performance guardrailing: Describe the two cases in which a guardrail need not act like a conventional refinement errand: performance-critical systems may run multiple guardrailing errands while a response is being sent and withdraw it after rejection, while highly sensitive systems may apply a guardrail repeatedly to rephrasings to prevent harmful misinterpretation or out-of-context use.
Why it matters: The required guardrail arrangement depends on whether response speed or protection against damaging interpretations is the dominant risk.
Key terms: Guardrail pattern, verdict, pass/fail, accept/reject, feedback, ComplianceGuardrail, compliance guardrail, report-writing errand, errand, guardrail
2.7 Spotting the refinement loop
This section shows how a MortgageAdvisor forms a refinement loop by feeding ComplianceGuardrail feedback back to the ReportingErrand for limited report rewrites.
- Compliance feedback refinement loop: Explain how the MortgageAdvisor uses the ComplianceGuardrail's feedback and verdict to make a later ReportingErrand attempt improve the report.
Why it matters: A report can be revised in response to identified compliance problems instead of being accepted as the first draft. - Bounded feedback retries: Describe how the state-machine loop aggregates feedback from subsequent trials and supplies it to the ReportingErrand during the two retrials permitted by a max_compliance_retries limit of 3.
Why it matters: Bounding retries lets the agent improve a report through feedback without retrying indefinitely. - Actor-critic refinement rationale: Explain why refiners are becoming popular and describe the more sophisticated actor-critic version in which a cached report-writing conversation receives critique as a user message requesting a rewrite.
Why it matters: This connects the simple retry loop to a broader approach for improving initially weak AI outputs through reflection and critique.
Key terms: MortgageAdvisor, ComplianceGuardrail, ReportingErrand, feedback, verdict, refinement loop, state machine, max_compliance_retries, retrials, aggregated feedback
2.8 Summary
This summary recaps how agent flow diagrams and composable design patterns structure the Mortgage Advisor agent into isolated, quality-focused components.
Where this is used later
- The pain point: Limits on context length (chapter 3) · The idea that agent systems have runtime and orchestration components.
- How the Errand pattern works (chapter 3) · The distinction between runtime components and orchestration of their execution.
- The pain point: Unsafe or inappropriate output (chapter 4) · The organization of multiple subcomponents into a supervised team.
- Errand pattern variants (chapter 3) · The Errand variants build on the basic definition of an errand.
- (chapter intro) (chapter 3) · The earlier report-writing errand provides an example of an errand within an agent workflow.
- Structured extraction errands (chapter 3) · Structured extraction errands expand on extracting a desired output structure from model responses.
- Regex-powered reasoning reliability resampler (chapter 5) · The regex-powered example later uses regular expressions to improve reasoning-output reliability.
- How the Guardrail pattern works (chapter 4) · The Guardrail pattern section expands the gating mechanism introduced here.
Concepts explained in this chapter
- InterlocutorInterlocutor is an agent design pattern for conversationally gathering required information through an internal agenda, follow-up questions, input correction, and a completion decision.
- guardrailAn agent component that evaluates content against specified requirements and decides whether it may proceed.
- subagentAn agent that operates under the coordination or supervision of another agent.
- context windowA context window is the maximum amount of input information a language model can consider in a single invocation.
- ErrandErrand is an agent design pattern that groups one or a few intelligent elements and procedures into a simple sequential or parallel-then-sequential operation with a final output.
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.
