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:

json

{
  "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:

text

initial cost + retry frequency × additional-attempt cost
= 0.04 + 0.10 × 0.04
= $0.044 per task

Do 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.