AI Agent Architecture: Foundations

From a Single Prompt to a Designed System — Components, Contracts, Explicit State, Certainty Zones, Configuration, and Decision Records

De: VU TRI CONG MOBILUCK - CODE247.AI

Narrado por: Virtual Voice

A prompt is where behaviour is asked for. An architecture is where it is guaranteed.

Atlas, the customer-operations agent of Meridian Supply Co., began as one prompt: twelve rules, a ticket, "decide and reply." It passed every test. Then finance sent twelve more rules, marketing sent twelve more, three of them contradicted the first twelve, and on a Friday in June Atlas approved a nine-hundred-dollar refund that needed a manager — in a friendly tone, under a hundred and twenty words, without quoting the ticket id. Nothing had broken. The prompt had never been an architecture.

This book takes Atlas from that prompt to a designed system, and you make every move yourself on the companion repository — one dependency, fully offline with a scripted mock, every listing printed from a verified line range, every command paired with its expected output. Each chapter is a lab in five moves: Run the demo, Read the listing, Break it with the chapter's planted failure, Fix it with the chapter's design move, Prove it with a test that turns green. You will:

• 
  
• Reproduce the prompt-blob collapse — 12/12 to 8/12 to 4/12 on the same requirements — and turn it into a number
• 
  
• Sort thirty-six requirement sentences into the six components every agent hides, and generate the diagram from the registry so it cannot drift
• 
  
• Measure latency, cost, reliability, and safety in one trade-off table, and see the cheapest configuration lose on the column that was missing
• 
  
• Separate mind from machinery: the model called through one seam, handed the decision, never asked to decide — and watch a provider change break the blob and not the design
• 
  
• Make run state one explicit object that saves, loads, and replays to an identical digest — then find a hidden global with a diff
• 
  
• Put a contract on every arrow, so malformed data is a typed refusal at the edge rather than a crash three components later
• 
  
• Draw the two-colour map — deterministic and probabilistic zones — and lint business rules out of prompts, by code and by configuration
• 
  
• Move behaviour into validated configuration: three agents from one codebase, a threshold that flips a decision with zero code edits
• 
  
• Write Architecture Decision Records a script can check, and supersede a decision without deleting its lesson
• 
  
• Assemble Atlas v0.1 with a capstone that runs requirements, tests, records, and diagram sync in one command — and break each check on purpose
• 
  

Every chapter carries a research lineage (Parnas, Brooks, Kruchten, the SEI's quality attributes, Dijkstra, Lamport, Meyer, Anderson's reference monitor, the twelve-factor app, Nygard's decision records), a five-item failure catalog, an applied deep-dive, and exercises in three tiers — Starter, Core, Stretch — each naming the artefact it produces and how to check it. Ten figures, forty tests, eight decision records, one running system.

Who it's for: developers and aspiring architects who have built or prompted a first agent and want to design the next one — and engineering leads who need a review checklist for agents that sign for money. Basic Python assumed; no framework, no GPU, no vector database.

The AI Agent Architecture Series is the architect's track: one architectural layer per book, on one running system the reader refactors and grows by hand. This is Book 1, Foundations — the skeleton every later book grows.