Skip to content
Directory
GitHub Star

Agent Architecture: Core Principles and On-Demand Methods ​

These nine principles are not about adding architecture. They are about helping a person actually receive a usable result.

Consider a teaching example: a teammate asks an AI assistant to compare two product documents, answer whether the new version exports PDF, and save a report with references. The answer looks correct and the UI says “done,” but the file-saving operation has no definitive receipt. Was the report delivered?

You do not need to know a dozen internal modules to begin. Ask: Who understands the question? Who knows whether the file was saved? When something fails, which independent results can still reach the user? Principles 1–4 cover interpretation, authorization, and failure scope. Principles 5–7 make future changes easier without accumulating obsolete machinery. Principles 8–9 ask whether the task succeeded and whether an improvement truly helped.

If you are new to Agent architecture, first follow one report through nine design judgments, then return here for the relevant principle. The six-layer overview gives the fuller technical execution path.

These are design questions, not nine mandatory approval gates. A model may propose an action; the program that owns permissions and stored results must confirm what really happened.

OPEN ETF AGENT · READING PATH

01 / IntroductionAgents in 15 MinutesRun a document comparison and understand the smallest Agent loop.Read this step →02 / Input and knowledgePrompt, Context, RAG and MemoryConnect instructions, current inputs, retrieval and lasting preferences.Read this step →03 / IntermediateTen Core ModulesFollow working code through tools, context, memory and sessions.Read this step →04 / Tools and methodsTools, Function Calling, MCP and SkillsFollow one document read through discovery, calls and execution.Read this step →05 / Memory and continuityHistory, Context, Memory and CheckpointsDistinguish retained information, preferences and execution progress.Read this step →06 / Tasks and executionTask, Session, Run, Worker and ScheduleDistinguish continuing a goal, resuming execution and scheduling the next opportunity.Read this step →07 / Deep diveFrom One Report to Durable Execution and SpecialistsConnect evidence, execution and specialist handoffs.Read this step →08 / WorkshopBring Your Own Documents to an AgentImport documents, inspect a report and continue your research.Read this step →09 / Delegation and reviewExpert, Subagent, Review and JudgeSeparate research roles, delegated execution and checks on the result.Read this step →10 / Report review workshopFrom a Saved Report to Review and DeliveryInspect the workshop report, handle review outcomes and verify delivery.Read this step →11 / PanoramaSix-Layer Request LifecycleExpand a familiar task into the six-layer system and its handoffs.Read this step →

Architecture principles · optional reference →

One report and three design questions: understanding, factual confirmation and failure scope

Layer 1 · Nine core judgments ​

One aim to remember: A user receives an accurate report they can inspect and reopen. Clear responsibility, limited failure scope, and retireable mechanisms are means to that end.

How to use this map: ①–④ ask who decides and what may fail; ⑤–⑦ ask whether future changes will become harder; ⑧–⑨ ask whether users get a better result. No request needs to pass nine new checks.

PrincipleCore questionWhat changes in how we thinkRead more
1. The model interprets meaning; the system owns objective facts.Who interprets the request?The model may spot that PDF export was added. The program must confirm which documents were read, which tools were authorized, and whether the report was saved.Model understands, code authorizes · Model/Runtime responsibilities · Six-layer execution guide
2. Complexity belongs with its rightful owner.Who owns the decision?The document reader owns reading; storage owns confirmation of a saved file. Do not add a manager that pretends to certify both.Ownership boundaries · A one-day Runtime refactor
3. Proposal, approval, execution and effect are different facts.What actually happened?“Save the report” is a request, not a saved file. When the outcome is unknown, do not assume nothing happened and blindly retry.Memory effects · Publication
4. A local failure must not become a global veto.How far may a failure propagate?A broken optional chart should not erase valid prose. But content lacking required authorization must still be withheld.Veto and termination
5. Context is a workbench, not a fact database.Where do durable facts live?If the model forgets page three, reread the original document instead of treating its summary as the only copy.Keep results outside context · Main compaction
6. Prefer the smallest sufficient mechanism.What is the smallest sufficient mechanism?Start by reading, comparing, and saving two short documents—not by building a general planner and approval platform.Entry simplification
7. Capabilities should be easy to introduce, replace and retire.Can this capability evolve or retire?When replacing a document reader, check who still depends on the old path and retire obsolete rules and tests.Architecture evolution
8. Internal success is not user-task success.Did the user’s task succeed?Make sure the user can open the report, understand the comparison, and inspect the cited source pages.Task convergence · HTML delivery · The complete delivery path
9. Local improvements are not system progress.Did the whole system improve?Faster search does not necessarily produce a better report. Compare delivery quality, latency, and cost for equivalent tasks.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 situationMethod to consultExisting reading
1. Deciding whether to add a featureSuppose you add optional charts to a report. Do users who never request charts now wait longer or pay for extra tool descriptions? Can the feature later be retired?The five don'ts
2. Reviewing responsibilities and rejectionsWhen upload, citation, or file saving fails, ask who recorded that fact, who may reject the operation, and what other work may still be delivered.Ownership · Subagent refactor retrospective
3. Passing evidence through a research systemWhen a report cites a source page, verify that the page was read and the claim matches it. A link in a summary alone is not evidence.Evidence chain, Chinese original
4. Planning a multi-phase deliveryDesign 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 failureInfer 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 knowledgeRemove 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 evolutionKeep promises such as “the report was saved” stable while allowing retrieval and summary methods to evolve. Choose verification by the concrete user and consequence, not by freezing a whole module.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.

Engineering notes, evidence and boundaries. · Contact: hpoenixf@foxmail.com · WeChat: hpoenixf0510