AI Agent Architecture Guide: Four Parts, One Loop, Many Harnesses

This AI agent architecture guide starts from four parts and one loop. An agent is a model client, a tool table, a message history and a loop that calls the model, runs the tool it asks for and appends the result. Everything else on an architecture diagram is harness, added one decision at a time.

The rest of the page is for the person who has to write the design document. It reduces any proposed diagram to those four parts, lists fifteen AI agent architecture decisions in the order a team is forced to answer them, and ends with a document skeleton to copy. The parts and the trade-offs come from AI Agents, Engineered. The ordering and the stage column are this post’s synthesis, and I say so again where they appear.

What are the four parts of an AI agent architecture?

The four parts are a model client, a set of tools, a message history and a loop. Chapter 3 of AI Agents, Engineered (in the full book) makes the claim without hedging: “An agent has exactly four parts, and you already understand every one of them.”

The same chapter gives the name for everything else: “An agent, in one line, is a model plus a harness.” The harness is the code you build around the model, and the post on what an agent harness is lists its components and what breaks without each. Here I need one property of it. Every harness part answers a question somebody had to decide.

Other counts exist. One vendor’s guide to building agents (PDF created April 2025) names three core components: model, tools and instructions. The loop arrives later in that guide as the “run”. I prefer four, because the history and the loop are the two parts your team writes, owns and debugs.

The book writes the loop in pseudocode, and so does this post: there is no code here in any language or SDK. A reader who wants to type the four parts can follow build an AI agent from scratch.

How do you reduce someone else’s diagram to four parts?

Take each box and ask which of the four parts it is. A box that is none of them is harness, and the useful follow-up is which decision put it there.

Chapter 3 says of its minimal agent that there is “no planning module to install, no reasoning engine to configure, no memory system beyond the list you append to”. Long-term memory, in the same chapter, “arrives with no new machinery: one tool to save a note, another to search past notes.” So a twelve-box slide can hold as few as four parts; the rest are claims about harness.

The explainer pages I fetched while searching for an AI agent architecture guide on 6 October 2026 mostly present layers named perception, reasoning and action, or agent types named reactive and deliberative. Those labels give a builder nothing to choose between, so I leave them out. The book’s version of the same point applies to any framework: “When a framework’s agent misbehaves, there are only four places to look”.

AI agent architecture guide: which fifteen decisions, and in what order?

This AI agent architecture guide puts fifteen decisions in one table, starting with who chooses the next step and ending with what you build or adopt. The table gives each one its options, its trade-off, what to write down, the chapter, and the latest stage at which it can be made.

The provenance matters. Each trade-off is the book’s, quoted or closely paraphrased, with the chapter beside it. The order of the rows and the “decide by” column are this post’s synthesis; the book makes each decision in its own chapter and assigns no stages. Each “what to write in the doc” cell is also mine.

The stages are defined by who is watching:

• Prototype: before the first run on a real task, with the builder reading every transcript.
• Pilot: before anyone other than the builder relies on the output.
• Production: before runs happen that nobody watches as they go, or before more people use it than the builder can sit beside.

When does a row come due earlier than its stage?

A row comes due early when either of two conditions fails; each stage is the latest safe moment only while both hold. First, every irreversible or externally visible tool is stubbed, confined or pointed at a test account. Second, every run finishes while a caller waits for it, the caller being the person or program that asked. A scheduled run has no caller, so it fails the second condition from its first night.

When either condition fails, rows 9 and 12 are due before that tool goes live or that run starts. A run that no caller waits for also needs the serving half of row 14 at that moment. Those conditions are Chapter 18’s two questions turned into a rule: “what here is irreversible, and how long does the run live?”

With JavaScript on, buttons above the table narrow it to the rows due at one stage; the earlier stages’ rows are assumed done. Chapter 1 is free to read online; the other chapters cited are in the full book.

The nearest published neighbor I know is 12-Factor Agents (repository created March 2025). It is twelve principles with no build order and no “what to write down” column, and several of its factors map onto rows 7, 9 and 12.

What do you decide before the prototype runs?

Five things: the rung, the stop rule, the ceilings, the tool table, and where anything dangerous runs. Each takes minutes for a small system, and each is expensive to discover from an incident.

Row 1 comes first because it can shrink the list. A workflow whose steps you can draw in advance has no loop to shape (row 6) and no agent count to settle (row 8); it still needs a success check, ceilings, a context policy, authority and evidence. Schluntz and Zhang’s 2024 essay Building effective agents says the same from a vendor’s side: “we recommend finding the simplest solution possible, and only increasing complexity when needed.” The should this be an agent? tool turns Chapters 1 and 14 into ten questions, and the post on the agents versus workflows decision rule covers the ladder.

Rows 2 and 3 are the stop condition and the budget. A check a program can run matters for the same reason covered in why AI agents hallucinate: the model’s report of success is generated the way everything else it says is generated. Where no program can check, as with a research summary, write the reviewer’s name in that cell.

For the ceiling, Chapter 3 mentions ten or twenty passes for a focused task and labels the figure as illustration. The cap on records changed per run is my addition to the chapter’s four, for agents that write. What an agent loop is ranks the exits, and run the loop lets you practice them.

Which tools exist, and where does risky code run?

Rows 4 and 5 fix the action space: the tool table, and the boundary around anything the model writes. The tool table doubles as the inventory for row 9, which is why I ask for the read-or-write and reversible columns this early. How to design tools for LLM agents covers the contract, and the tool contract linter checks one definition at a time.

Row 5 is a prototype decision because a builder’s laptop holds credentials. An agent that runs no code answers it in one line. A model-written database query is code for this purpose: row 5 says where it executes and what that process can reach, and row 9 says what its credential may do.

What do you decide before anyone else relies on it?

Six things: the loop’s shape, the context policy, one agent or several, authority, the failure path, and evidence. All six can be deferred while one person reads every transcript, and none can once a second person trusts the output.

Shape (row 6). The default free loop is the ReAct agent pattern: reason, act, observe, repeat. Named states suit a run that must pause for an approval, since the current state is small and honest to save. The catalog of orchestration shapes belongs on an AI agent design patterns cheat sheet; this table gives them one row.

Context (row 7). Write down what enters the window and what leaves it first. The context window budget planner prices one pass. A dated first-hand report shows why this row needs a reopening signal. The author of one agent product’s 2025 account writes, “we’ve rebuilt our agent framework four times, each time after discovering a better way to shape context.”

One or several (row 8). Two vendor architecture guides, read as examples of the category, agree with the book’s default. The Google Cloud guide (last reviewed 28 May 2026) says “we recommend that you start with a single agent”, and the OpenAI guide cited earlier says to “maximize a single agent’s capabilities first”. One vendor’s 2025 write-up of its own research system prices the alternative: “multi-agent systems use about 15× more tokens than chats”. Single agent vs multi-agent has the full verdict.

Who signs, what fails, and how will you know?

Rows 9, 10 and 11 answer those three questions, and each has a home in code that the prompt cannot replace.

Authority (row 9). The approval gate sits in code, in Chapter 12’s words “after the model has chosen, before anything runs”. The chapter attaches one of four gates to each tier: none, a log, a review queue or a signature. An agent that runs while nobody is present still gets an answer: its externally visible and irreversible writes land in a queue, as a proposed change that a person applies or approves later.

The consequence tier classifier grades each tool. The lethal trifecta audit counts the three legs the doc cell asks about.

Failure and evidence (rows 10 and 11). Row 10 carries a clause that keeps the table consistent with itself: a write without a key halts on a timeout, because nobody knows whether it happened. Row 11 needs a trace and a regression gate before the pilot, since the first complaint from a user will be about a run nobody watched.

What do you decide before runs go unwatched?

Three things: where the run lives, what happens when a dependency is gone, and how the feature is priced and served. They can wait because a short, watched, read-only run loses little when it dies. A system that a person always watches, such as an assistant that only drafts, reaches this stage by headcount.

Row 12 is the one most often answered by accident. A checkpoint tells a resumed run where it was. Whether the email went out or the card was charged is a separate fact, which is what idempotency keys and receipts record; idempotent tools and safe retries covers the mechanics. Chapter 18 supplies the test to write into the doc: “a checkpoint you have never restored from is a guess”.

Adopted machinery leaves this row open. In September 2026 a user on the issue tracker of a widely used agent framework asked: “When a tool call times out or the worker dies mid-tool, what is the intended recovery contract?” That question is row 12, asked after the framework was chosen. The 2025 write-up cited above says of its own system that “we built systems that can resume from where the agent was when the errors occurred.”

“None” is a legitimate answer here. Chapter 18 says of checkpoint cadence that “for a task that finishes in one sitting the honest cadence is none at all”.

What happens when a dependency fails, and what does a run cost?

Row 13 separates advice from action. A stale answer with a warning label is an acceptable fallback for a read; a refund has no acceptable weaker version, so it stops and goes to a person.

Row 14 sets the economics, and the agent cost-per-task estimator shows the term that grows with step count. Chapter 20 adds the serving rule: once a run outlasts the connection, the caller gets a task id, and the run’s identity lives in a database row that no process owns. A scheduled run has no caller, so its entry names who reads the result and when.

Should you build the loop or adopt a framework?

Decide it last at each stage, after the rows above have named what the system needs, and adopt when the need is one you would otherwise have to build. Row 15 is the only row marked for all three stages, because each stage names new needs. The post on what an agent harness is has the table of what a framework supplies and what each part costs; this section adds the evidence and the entry to write.

Readers usually ask this first. An Ask HN post from October 2025 puts it plainly: “I am curious if people here roll their own agents from scratch or use frameworks.” Replies in that thread run both ways. One reads “We used frameworks in the past […] Now we roll our own, generally a much better and cleaner experience.” Another comes from someone content with a framework who had rolled their own before. Of the hand-written version: “it worked well for very simple tasks”, and “I would be concerned about complexity if there were more steps, tool calls, or the need to compose multiple agents”.

Has anyone measured a framework against a hand-written loop?

I looked for a public measurement that compares a framework with a hand-written loop on the same task and the same model, and as of October 2026 found none.

The nearest thing is a demo paper by Milev and Kanagala at ACM CAIS, 29 May 2026, of which I read the abstract only. It holds one model and one tool server fixed across six frameworks and SDKs and scores three scenarios. The abstract reports “empirical evidence that scenario-specific orchestration adds no measurable benefit over generic agentic loops driven by prompts.” It compares frameworks with one another, includes no hand-written baseline, and is one team’s result on one model.

Two older papers measure neighboring things. Kapoor et al. (2024) argue in their abstract that “SOTA agents are needlessly complex and costly, and the community has reached mistaken conclusions about the sources of accuracy gains”, which concerns agent designs on benchmarks.

Cemri et al. (2025) annotate 1600+ traces across 7 multi-agent frameworks into 14 failure modes; the study does not isolate the framework as a cause.

So the rule has to work without that evidence, and the book’s does. Chapter 3 states the trade as symmetrical: “minimal code gives you total visibility and no magic, at the price of writing your own plumbing; a framework supplies the plumbing, at the price of opacity, lock-in, and abstraction layers to debug through.”

What does a fair reading of both sides say?

Both sides agree on the list of plumbing and disagree only about who writes it. A framework vendor’s own essay (Harrison Chase, April 2025) says agentic systems “all benefit from the same set of helpful features, which can be provided by a framework, or built from scratch.” Chapter 3 gives the list: persistence, retries, tracing, memory management and orchestration. All five change how dependable a run is, and none changes what the model does on a single pass.

Adopting early is reasonable when the team already knows the framework, can point to the four parts inside it, and can name the row it serves. Building is reasonable while one loop is being learned or prototyped. Either choice is safe on one condition, which Schluntz and Zhang’s essay also sets: the team understands the code underneath.

Durable-execution runtimes show what adoption does and does not settle. Two examples of the category are Temporal, whose 2025 explainer defines the term, and Restate. Restate’s documentation (read October 2026) says the runtime “replays the journal, skipping completed steps and resuming from exactly where it left off.” Either meets the need in row 12 for long runs. Which writes carry a key is still your entry to make.

How much harness is enough?

Enough to match how long the system lives, how many people trust it and how unattended it runs. That is Chapter 18’s scaling law: “harness investment should scale with how long the codebase must live, how many people must trust the agent’s output, and how unattended the agent runs.”

The chapter endorses one audit for every team, which goes in row 15’s cell: “on every model change, reread your standing machinery and delete what the new model has made redundant”. The harness grid builder lays your controls out so the empty cells show, and the harness post linked above covers the debate behind the law.

Worked example: a support agent that issues refunds

Here is one system walked through all fifteen rows. The system is hypothetical: an agent for an online store that reads a ticket, looks up the order and may issue a refund. Every number in it is illustrative.

Three entries moved. The pilot issues real refunds and waits hours for a signature, so both conditions fail: row 9 was settled before the first live refund, and row 12 and the serving half of row 14 came forward from production. During the prototype the refund tool pointed at test mode, so a refund that timed out cost nothing.

I walked four other systems through the table. A read-only research assistant answers rows 5, 8 and 12 in one line each and puts a named reviewer in row 2. A coding agent that runs commands spends most of its effort on rows 2, 5 and 9: a test suite as the check, a container with the network denied, and a gate on anything that leaves the sandbox.

The last two came from this post’s reviewer and changed the table. A nightly data-cleanup agent with write access has no caller and nobody present, which is why row 3 caps records changed, row 9 names the queue and row 14 lists a scheduled run. An assistant that only drafts replies is watched forever, which is why production has a second trigger.

What goes in an architecture document for an agent?

One section per decision, each stating what you will do, the alternative you rejected, the consequence you accept and the signal that would prove you wrong. The skeleton below is original to this post; As of October 2026 I found no published template specific to agents.

Its form borrows from two well-known sources on the genre. Michael Nygard’s 2011 decision records state each decision in full sentences that begin “We will”. Malte Ubl’s 2020 account of design docs calls the alternatives section “one of the most important ones”.

ARCHITECTURE: <agent name>     Status: proposed | accepted     Date:

The four parts
  Model client:    <the one place every model call passes through>
  Tools:           <count; the table is in section 4>
  Message history: <what is appended; where it is stored>
  Loop:            <where it lives; shape is in section 6>

Each section below uses the same four lines.
  We will:   <the decision, in a full sentence>
  Rejected:  <the alternative, and why>
  Accepted:  <the consequence we take on>
  Wrong if:  <the signal that reopens this decision>
A deferred section reads: "Deferred until <signal>. Until then: <default>."
The stage headings hold under two conditions: every irreversible or externally visible tool is
stubbed, confined or on a test account, and every run finishes while a caller
waits for it. If either fails, sections 9 and 12 are due now, and so is the
serving line of section 14 for a run that no caller waits for.

BEFORE THE PROTOTYPE RUNS
 1. Who chooses the next step
    We will:   <code / one call / workflow / agent / agent proposing to a person>
    Rejected:  <the rung below, with the evidence that it fails>
    Accepted:  <the cost and unpredictability this rung adds>
    Wrong if:  <e.g. every run takes the same path>
 2. Stop rule and success check
    We will:   <the check a program runs, or the named reviewer>
    Rejected:  Accepted:  Wrong if:
 3. Ceilings (starting values)
    We will:   passes __  tokens __  wall-clock __  money __
               records or actions changed per run __   (if it writes)
               When one fires we return: transcript, partial work, "stopped".
    Rejected:  Accepted:  Wrong if:  <e.g. a cap fires on most runs>
 4. Tool table
    We will:   name | read or write | reversible? and what makes it so
               Irreversible tools stay stubbed, confined or on a test account
               until sections 9 and 12 are decided.
    Rejected:  Accepted:  Wrong if:
 5. Isolation
    We will:   <boundary; network rule; what is mounted or reachable>
               or <no code runs>. Model-written queries execute: <where>
               Untrusted inputs: <list>
    Rejected:  Accepted:  Wrong if:

BEFORE ANYONE ELSE RELIES ON IT
 6. Loop shape
    We will:   <free loop / plan then execute / named states: ...>
    Rejected:  Accepted:  Wrong if:
 7. Context policy
    We will:   <what enters each pass, in order; soft ceiling; trimmed first>
               Knowledge: <carried / retrieved / trained>
    Rejected:  Accepted:  Wrong if:
 8. One agent or several
    We will:   <one / orchestrator and workers, with the brief format>
    Rejected:  Accepted:  Wrong if:
 9. Authority
    We will:   per tool: tier | gate (none / log / review queue / signature)
               Who clears the queue when nobody is present: <...>
               Credentials: <scope and lifetime>
               Private data, untrusted content, outbound channel: __ of 3
    Rejected:  Accepted:  Wrong if:
10. Failure path
    We will:   Error shape: code | message | retryable | hint
               Retried: <list>   Surfaced: <list>   Halts the run: <list>
               Retry budget per run: __
    Rejected:  Accepted:  Wrong if:
11. Evidence
    We will:   Trace fields: <...>   Cases from: <...>   Gate: <...>
               Rollout rungs: <...>
    Rejected:  Accepted:  Wrong if:

BEFORE RUNS GO UNWATCHED
12. State and recovery
    We will:   Durable: <...>   Ephemeral: <...>   Cadence: <... or none>
               Writes that carry a key: <list>
               Crash test on <date>: killed after ___; resumed run did ___.
    Rejected:  Accepted:  Wrong if:
13. Fallback
    We will:   <per critical dependency: the ladder, ending in a person,
               at once or through a ticket read later>
               The escalation hands over: <goal, attempts, failure, next step, trace>
    Rejected:  Accepted:  Wrong if:
14. Cost and serving
    We will:   <the two of accuracy, cost, latency, per feature>
               Cost per task: __   Grows with: __
               Served: <sync / queued with a task id / scheduled>
               If scheduled: who reads the result, and when
    Rejected:  Accepted:  Wrong if:

AT EVERY STAGE, LAST
15. Built, adopted, and how much harness
    We will:   adopted part | the section whose need it meets | what stays ours
               On each model change we reread and delete: <...>
    Rejected:  Accepted:  Wrong if:

Once the sections are filled, the agent verifiability scorecard is a useful second read. It asks twelve questions about the signals the system exposes.

What can you write as “deferred until X”?

Any row whose stage has not arrived, provided the entry names the signal that reopens it and the default in force until then. A deferred entry with no signal is an undecided one.

Three examples, all in the form the skeleton gives:

• Row 8: “Deferred until one task’s reading overflows a single window on more than a few runs. Until then: one agent.”
• Row 12: “Deferred until a run has no caller waiting or a write goes live. Until then: process memory, and a failed run is rerun.”
• Row 15: “Deferred until a section names a need we would spend more than a sprint building. Until then: our own loop.”

The rows that resist deferral are 1 through 5. A prototype without them still has a rung, a stop rule, a ceiling, a tool set and a place where code runs. It has them by default, and nobody chose the defaults.

Where does this order not hold?

It fails wherever the two conditions fail, and it has four further limits that the table cannot show.

Irreversibility and run length reorder it. A team whose first tool charges cards meets rows 9 and 12 on day one. The stage column describes the common case.

Many systems leave rows empty. Chapter 18’s own example is that “the thirty-second read-only summary needs none of it”, speaking of the recovery apparatus. Filling every section at full depth for a watched prototype is the over-building the scaling law warns about.

The stages and the skeleton are untested as a method. In this AI agent architecture guide they are a synthesis of the book’s chapters and two documentation formats. Nobody has measured whether teams that fill this document ship better agents.

A thin seam protects code and leaves behavior exposed. Chapter 27 recommends one place through which all model calls pass. A commenter on a June 2025 thread, arguing against frameworks, wrote that “the ability to swap out APIs just isn’t the bottleneck.. like ever.” Both points stand: the seam absorbs an interface change, and row 11’s gate is what catches a change in behavior.

The harness depreciates. Some of what you write in rows 6 and 7 compensates for the current model’s weaknesses, and the audit in row 15 exists to remove it.

The review to hold this week

Take the proposal on your desk and sort its boxes into the four parts and the harness. Then open the skeleton, fill rows 1 through 5, and write “deferred until” on every other row with a signal beside it. A review that argues about those entries is arguing about the architecture, and that argument is what an AI agent architecture guide is for. Appendix A (in the full book) closes on the same thought about the minimal agent: “what separates your afternoon from their operation is harness, applied one named need at a time.”

The four parts and the stop rules are in Chapter 3, The Agent Loop (in the full book), the action space is in Chapter 5, Tools and the Action Space (in the full book), and failure, state and harness sizing are in Chapter 18, Reliability, State, and the Harness (in the full book). Chapter 1, What Is an Agent? is free to read online and covers row 1. The agent fundamentals guide collects the related posts and tools, and you can see the formats.