Architecture decisions — patterns, boundaries and acceptance
Use this reference after attempting the lectures and quizzes. It organizes the six Solution Architecture objectives into decisions you can defend from a task's requirements. The worked cases and criteria are house-authored.
Choose capabilities and control separately
| Concept | Design question | Synthetic example |
|---|---|---|
| Augmented LLM | Which evidence or capabilities does a model need? | Retrieve a policy passage before answering |
| Fixed workflow | Which known stages and gates must always occur? | Extract → validate → compare → decide |
| Routing | Which input category selects specialized processing? | Send a billing question to its policy path |
| Parallel work | Which branches can proceed without each other's unfinished output? | Two checks after a shared validated record |
| Agentic planning | Which next steps become clear only during execution? | Follow newly discovered product relationships |
| Multi-agent delegation | Which bounded tasks benefit from separate contexts or independent execution? | Investigate disjoint entities and return sources to a lead |
Retrieval, tools and memory can augment calls inside a workflow or agent. Adding a tool does not by itself choose the control structure. Retained instructions provide context; they do not automatically enforce an action boundary.
Worked choice: a manual-backed FAQ already meets its criteria with retrieved passages and answers. Keep that as the baseline. A new task that checks account state and proposes an allowed update adds state inspection and a consequence boundary. Evaluate a workflow with explicit checks before adopting open-ended planning. A research task whose next relevant question depends on newly discovered evidence offers a stronger reason to evaluate a planner.
Trace ownership, including failed paths
| Boundary | Evidence to retain | Decision enabled |
|---|---|---|
| Input → extraction | Relevant input and extracted fields | Is the required information available? |
| Model → tool | Requested operation and its result | Was selection, execution or interpretation wrong? |
| Output → consumer | Result, check outcome and failed fields | May the dependent action proceed? |
| Failed check → repair | Error evidence and remaining repair allowance | Repair once, revalidate or stop |
| Worker → lead | Entity, period, sources, finding and gaps | Can the lead reconcile and synthesize? |
| Execution → outcome | Reviewed completion and operating measurements | Did the user task meet its criteria? |
A log becomes feedback when an identified failure changes the next bounded action. In the project, the first invalid record receives one repair using the field errors. Revalidation uses the same remaining allowance. Another failure escalates; it does not silently begin a fresh unlimited loop. A passed local field check still has to be followed by policy and outcome checks.
Loop ownership is a separate choice: the Client SDK leaves implementation of the tool loop to your code; the Agent SDK runs a loop in your process; Managed Agents runs the agent and sandbox as a hosted product. A library can supply execution while the application retains business-rule validation.
Design a delegation contract
The house supplier investigation uses this return shape:
{
"entity": "Product C",
"period": "current support at the exercise cutoff",
"question": "Which support policy applies?",
"finding": "Unresolved: sources disagree about the successor",
"sources": ["synthetic-policy-C", "synthetic-transition-notice"],
"unresolved": ["Whether the transition applies to this version"]
}This is an exercise schema, not a required SDK response format. Give each worker explicit scope and access. The lead aligns entity and period before combining findings. A one-word verdict cannot carry the evidence needed to resolve a scope conflict.
For the project, the lead admits no more than two active workers, twelve tool calls across the entire run and no new work after ninety seconds. A follow-up spends the same remaining budget. On exhaustion, stop new admissions, request cancellation where supported, and preserve the supported partial findings and unresolved question. In-flight work can still finish; an admission deadline is not a promise of immediate cancellation.
Replanning example: A and B turn out to be aliases, C is still unresolved and successor D is newly relevant. Merge A/B, retain C, and add D within the remaining budget. If both remaining investigations cannot fit, disclose the shortfall. Replacing C with D without a scope decision would hide missing coverage.
Apply the joint acceptance gate
For a house pilot, require success ≥97%, end-to-end p95 ≤1.5 seconds and mean execution cost ≤$0.05 per task. A hybrid with 97% success, 1.4 seconds and $0.044 mean cost passes all three supplied limits. A chaining candidate with 98% success and 1.7 seconds fails the latency limit despite having better success.
If the hybrid costs $0.04 initially and 10% of tasks need one further $0.04 attempt, the mean is:
initial cost + retry frequency × additional-attempt cost
= 0.04 + 0.10 × 0.04
= $0.044 per taskDo not claim a measured p95 from an average or from absent raw timings. State the workload, denominator and retry inclusion. A changed workload can invalidate an accepted design, so the decision record needs a reevaluation trigger.
Review record
- State the customer outcome and all required operating limits.
- List the baseline and plausible alternatives under the same cases.
- Draw dependencies, ownership, validation, feedback and stop paths.
- Specify worker scope, evidence returns and the shared work budget.
- Record measured results, calculation assumptions and rejected alternatives.
- Name who decides acceptance and who responds when a limit is missed.
Sources
Agent SDK overview, tool use overview, search results for RAG, Claude Code memory, prompting best practices, subagents, and success criteria and evaluations.
