Contents
- 01The Builder's Starting Line
- 02Your Computer, Explained
- 03How Software Fits Together
- 04Start With the Work
- 05Build Your First Useful Tool
- 06Make Changes Safely
- 07Prompts Are Specifications
- 08Models Are Components
- 09Give Agents Jobs, Not Vibes
- 10Tools, APIs, and the Harness
- 11Truth Before Intelligence
- 12Patterns for Real Systems
- 13Approval Is a Feature
- 14Receipts or It Didn’t Happen
- 15Operate and Debug the Loop
- 16Design Your Own OS
- 17Make It Ready for Real Life
- 18Build and Evolve Your OS
Models Are Components
Choose the engine by the work, then design around its variance and limits.
Capability is multidimensional
Model quality is not a single ladder. A task may depend on instruction following, long-context comprehension, tool selection, structured output, visual understanding, mathematical accuracy, coding, tone, latency, privacy, or cost. A model strong at open-ended reasoning may be wasteful for extraction and inconsistent for a tightly formatted operation.
Define the job profile before comparing providers. Include the hardest judgment, context size, tool behavior, output contract, risk, speed target, and volume. Choose from evidence on that profile rather than general reputation.
“The best model is not the one with the loudest benchmark; it is the cheapest configuration that reliably clears your actual quality bar.”
Variance is part of the contract
The same model and instruction can produce different paths across runs. Temperature and reasoning settings influence behavior, but variance also comes from retrieved context, tool responses, conversation state, provider changes, and ambiguity in the task. A single successful demonstration is therefore weak evidence.
Test repeated runs, boundary cases, and changes over time. Use deterministic validation around identifiers, calculations, permissions, schemas, and state transitions. Reserve model judgment for the part that benefits from interpretation.
Design around limitations
Models can invent facts, lose instructions in long contexts, mishandle exact arithmetic, call the wrong tool, overfit examples, and produce convincing explanations for incorrect actions. Larger models reduce some errors but do not remove the need for architecture.
Use retrieval for current facts, calculators and code for exact computation, schemas for output, policy checks outside the model, approval for consequential action, and verification against the environment. When the system needs a guarantee, encode it in deterministic software rather than a sentence asking the model to be certain.
Case file
choosing models for an invoice exception system
A finance team wants one model to read invoices, match vendors, check policy, explain exceptions, and recommend routing. Early tests with a frontier model look strong but are slow and expensive at volume. A smaller model is fast but occasionally changes identifiers and invents missing fields.
The team decomposes the work. OCR and typed extraction produce source-linked fields. Code performs totals, duplicate checks, and policy thresholds. A fast model classifies ordinary exceptions. A stronger model receives only ambiguous cases with the relevant contract and policy context. Any payment-changing recommendation requires human approval.
The evaluation compares configurations on exact field accuracy, exception recall, unsupported claims, routing quality, latency, total cost, and review burden. Routing becomes an evidence-based policy rather than a permanent allegiance to one provider.
Decisions made
- 01Keep exact calculations and identifiers outside probabilistic generation.
- 02Use task difficulty and consequence to select the model tier.
- 03Measure the total loop, including retries and human review.
- 04Bind model changes to the same golden cases and receipt schema.
The winning architecture did not discover one perfect model. It placed different kinds of uncertainty in the components best equipped to handle them.
Route; do not churn
A multi-model system can route simple classification to a fast inexpensive model, reserve frontier reasoning for ambiguous planning, use a specialist for coding or vision, and invoke a second model as a critic. This helps only when the route has measurable value and a stable interface.
Avoid provider churn disguised as architecture. Every model change can alter tool use, formatting, latency, refusal behavior, and prompt interpretation. Keep model-specific adapters behind a common task and receipt contract, then compare candidates on the same evaluation set.
Cost and latency are product behavior
The economics of an agent include input and output tokens, cached context, tool calls, retries, parallel workers, verification, and human review. The user experiences latency across the whole loop, not the model response alone. A cheaper call that doubles retries or review time is not cheaper.
Measure cost and duration by job class and outcome. Stream when early visibility helps. Parallelize only independent work. Cache stable context when policy allows. Use budgets and stopping conditions. Optimize after correctness is measured, because a fast wrong system creates downstream work that rarely appears on the inference bill.
Evaluate the system configuration
A model evaluation must name the prompt version, context policy, tools, harness, decoding settings, and grader. Otherwise the result cannot explain which change improved or harmed performance. Compare outcome quality, trajectory, safety, latency, cost, and recovery—not one aggregate score.
Run shadow tests before replacing a production route. Examine disagreements by failure category. A smaller model may graduate for a narrow task even when it performs worse overall; a frontier model may remain necessary where rare reasoning failures carry high consequence.
Across the business
What this looks like in other departments
The engineering principle stays the same; the workflow, risk, and proof change with the domain.
Finance
Separate extraction from judgment
Use deterministic parsers or a small model for invoice fields, code for calculations, and a stronger model only for ambiguous exception narratives.
Customer support
Route by case risk
Handle common classification cheaply while reserving deeper reasoning and human review for high-value, policy-sensitive, or emotionally complex cases.
Marketing
Match model to creative stage
Use one configuration for source-grounded research, another for divergent concepts, and deterministic checks for required claims, links, and brand constraints.
Product & analytics
Evaluate insight workflows
Measure whether the model identifies actionable patterns without inventing user behavior, preserves source evidence, and produces decisions faster than the current process.
Technical deep dive
The model routing scorecard
Compare model configurations on the work that matters, then make routing explainable and reversible.
- 01ProfileDefine task complexity, context, modalities, tool needs, output constraints, risk, latency target, and volume.
- 02BenchmarkRun representative cases repeatedly and record outcome, trajectory, format, safety, latency, cost, and review effort.
- 03SegmentGroup cases by difficulty and consequence so aggregate averages do not hide a dangerous failure class.
- 04RouteAssign a default, escalation condition, fallback, timeout, budget, and deterministic validation for each job class.
- 05RevalidateShadow upgrades, detect behavior drift, preserve rollback, and rerun the suite when any system component changes.
Reference schema
job.profile: complexity + context + tools + risk + volume candidate.config: provider + model + settings + harness evaluation: cases + repetitions + outcome + trajectory economics: tokens + tools + retries + latency + review route.policy: default + escalation + fallback + budget validation: schema + rules + environment checks change: shadow result + drift + decision + rollback
Try it yourself
Run a model bake-off
Choose one recurring task and compare two model configurations using the same evidence and quality bar.
- 1Collect ten representative cases, including failures and edge cases.
- 2Define outcome, safety, format, latency, cost, and review measures.
- 3Run repeated trials without changing the specification between candidates.
- 4Write a routing rule and the evidence that would cause it to change.
Reusable artifact
Model decision record
A durable reason for choosing, routing, or replacing a model configuration.
Job class: [task and consequence] Required capabilities: [reasoning, tools, modality, format] Candidates: [model + settings + harness] Evaluation set: [normal, edge, dangerous] Results: [quality, safety, latency, cost, review] Route: [default, escalation, fallback] Revisit when: [drift, price, tool, or workload change]
Before you move on
Receipt checklist
- Model choice is tied to a defined job profile.
- Exact and consequential invariants are enforced outside the model.
- Quality, safety, cost, latency, and review burden are measured together.
- The route has an escalation path, fallback, and rollback.
Primary sources
