Agent Architecture: Core Principles and On-Demand Methods
This is a reference and reading map, not another published essay or a new approval process. Core principles should be rare, durable and broadly useful. Engineering methods should be consulted when the relevant design problem arises. Actual security, authorization and effect requirements remain with their owning components.
How to use this map: Follow a core judgment or engineering method into a selected essay. The relevant passages of those essays link back to this page's stable numbered anchors, explaining the actual design connection. Other essays do not need a forced principle assignment; their footers still provide a route back to the full map.
This decision map pairs with the complete six-layer architecture guide. The guide explains how one research request moves through the system; the principles explain why the owners and constraints are designed this way.
ESSENTIAL READING · START HERE
Layer 1 · Nine core judgments
Guiding aim: An agent architecture should reliably complete real user tasks. That requires separating semantic interpretation from facts, keeping authority with the rightful owner, and distinguishing a proposed action from a verified effect. Use the smallest sufficient, recoverable, replaceable mechanisms, then check whether local changes improve the whole task.
Reading order: ①–④ trustworthy execution (interpretation, ownership, effects, local failures); ⑤–⑦ sustainable evolution (context, minimal mechanisms, replacement); ⑧–⑨ effectiveness (task success and system progress). This is a way to reason about design, not an additional runtime pipeline, approval step, or universal evaluation gate.
| Principle | Core question | What changes in how we think | Read more |
|---|---|---|---|
| 1. The model interprets meaning; the system owns objective facts. | Who interprets the request? | A model can research and explain; a Host/Runtime records permissions, execution and receipts. A deterministic rule is not automatically a semantic judge. | Model understands, code authorizes · Model/Runtime boundaries, Chinese original · Six-layer execution guide |
| 2. Complexity belongs with its rightful owner. | Who owns the decision? | Encapsulation consolidates decisions and knowledge, not merely files. A child agent or plugin must not invent a duplicate authority system. | Ownership boundaries · A one-day Runtime refactor |
| 3. Proposal, approval, execution and effect are different facts. | What actually happened? | A tool call is not permission; a returned result is not proof of durable effect. Unknown outcomes cannot silently become “not executed.” | Memory effects · Publication, Chinese original |
| 4. A local failure must not become a global veto. | How far may a failure propagate? | A module may reject its own protected effect, but not erase unrelated valid work or independently decide the entire run's fate. | Veto and termination, Chinese original |
| 5. Context is a workbench, not a fact database. | Where do durable facts live? | The current model view is bounded and lossy; persistent evidence, memory, tool receipts and history need independent custodians. | Keep results outside context · Main compaction |
| 6. Prefer the smallest sufficient mechanism. | What is the smallest sufficient mechanism? | Do not automatically replace the model's flexible research decisions with more planners, validators, hooks or state machines. | Entry simplification, Chinese original |
| 7. Capabilities should be easy to introduce, replace and retire. | Can this capability evolve or retire? | A true upgrade lets a new structure replace an old one, without permanently spreading private contracts. This does not require hot-pluggable everything. | Architecture evolution, Chinese original |
| 8. Internal success is not user-task success. | Did the user’s task succeed? | Executing tools, generating text and saving files do not on their own prove that the user received a correct, useful result. | Task convergence · HTML delivery · The complete delivery path |
| 9. Local improvements are not system progress. | Did the whole system improve? | A better projection, trace or evaluation score needs to be followed through actual model inputs, durable outputs and user tasks. Separate local repairs, measurement corrections and end-to-end benefits; account for normal-path tool-definition costs and quality, cost and latency trade-offs. | Local versus end-to-end improvement |
Why keep principles eight and nine separate? The eighth asks whether the user actually succeeded; the ninth asks whether a change demonstrably improved end-to-end outcomes after costs and trade-offs. A local green check is not system progress.
Do not add a tenth principle merely because a bug was fixed. A new core idea should genuinely change decisions across multiple systems and resist being explained by an existing principle.
Layer 2 · Seven on-demand methods
| Design situation | Method to consult | Existing reading |
|---|---|---|
| 1. Deciding whether to add a feature | The “five don'ts”: don't add mechanisms simply because you can; don't spread complexity; don't give local modules global vetoes; don't impose a normal-path tax; don't build abilities with no exit. | The five don'ts, Chinese original |
| 2. Reviewing responsibilities and rejections | Ask about facts, authority, failure, and value. For a rejection, check ownership, effect scope and duplicate arbitration. | Ownership · Subagent refactor retrospective |
| 3. Passing evidence through a research system | Distinguish stored results, model-visible projections, executed inputs, conservative lineage, and exact claim support. No transform magically upgrades authority. | Evidence chain, Chinese original |
| 4. Planning a multi-phase delivery | Design broadly when needed, but implement along the shortest necessary path to a first usable deliverable; do not make optional infrastructure a hidden prerequisite. | Weekly review staged delivery · Spec and Evidence · Task convergence |
| 5. Choosing verification and diagnosing failure | Infer deterministic invariants with focused contract checks; study uncertain model/user outcomes using proportionate empirical evidence. Locate the actual owner of a failure first. | Test and evaluation fidelity |
| 6. Retiring mechanisms and retaining knowledge | Remove obsolete assumptions from code, specs, prompts, skills and tests without rewriting historical evidence; load long-term knowledge on demand. | Engineering context, memory and knowledge retirement |
| 7. Differentiate interface stability and evolution | Do not rank whole modules or directories. Separate protected effects, durable outcomes, evolving research behavior, and replaceable adapters at concrete interfaces: Child handoffs and forgetting must stay correct, while prompts and retrieval methods can evolve. Verify the actual consumers without adding a parent owner. | Differentiated evolution contracts · The Runtime refactor that prompted them |
These methods are not seven new runtime gates. They help select questions and evidence without requiring every change to run the same experiment.
Further reading and forthcoming work
The weekly-review staged-delivery retrospective remains a separate case study. Knowledge retirement is now part of the engineering context and history article. Further topics still need distinct evidence before becoming standalone essays. See the writing roadmap.