Building Reliable AI Agent Architectures

Let me tell you about the version of my SDLC harness that I'm slightly embarrassed by.

When I first built the multi-agent pipeline that drives my orchestration framework, I did the thing everyone does. I had a task — implement a spec with eight files of changes — and I thought: obviously, fan it out. Spin up one agent per file, run them all at once, merge the results. Eight agents working in parallel had to be roughly eight times faster than one agent grinding through sequentially. The math was seductive.

What I got back was a pile of merge conflicts and, worse, silent incompatibilities. One agent renamed a function; another agent, working on a different file at the same moment, called the old name. One agent added a config field; another wrote the validator assuming it didn't exist. Each agent's work was locally correct and globally wrong. I spent more time reconciling the eight outputs than the whole task would have taken with a single agent.

Here's the uncomfortable lesson I took from that: adding agents didn't add capacity, it added entropy. Every agent I bolted on made the system less reliable, not more. And once I started paying attention, I saw the same pattern everywhere — the flashy multi-agent demos almost never survive contact with a real, interconnected task.

This isn't an argument against ever running work in parallel — my harness today runs agents in parallel all the time. It's an argument about when parallelism is safe and what you have to guarantee before you reach for it. By the end, you'll be able to look at a task and predict whether splitting it will speed you up or quietly corrupt your output.

After I tore the parallel version down and rebuilt it, I found that almost every failure I'd hit traced back to violating one of two principles. I didn't invent these — they fall out of the structure of the problem the moment you look closely — but I learned them the expensive way, so let me save you the tuition.

Principle 1: Share Context

Every agent needs the full context of what came before. Not a summary. Not a filtered "here's what's relevant to you." The complete picture.

Think of it like a relay race. The baton isn't just permission to run — it carries the state of the whole race: why you're running, what the earlier legs did, what the strategy is, what went wrong on the last handoff. Take the baton away and you don't have a relay team, you have four people sprinting in vaguely the same direction. That's exactly what my eight parallel agents were.

Principle 2: Actions Carry Implicit Decisions

This is the subtle one. When an agent acts on incomplete information, it doesn't stop and wait — it makes an assumption, and that assumption becomes a decision baked into its output. Those implicit decisions are invisible until they collide.

Here's the architecture that violates both principles at once — the one I started with:

Read line 9. At that moment, three agents are making decisions simultaneously, and none of them can see the other two. combine_results is where the lie comes due: you're asking one function to reconcile three sets of assumptions that were never compatible to begin with.

Let's walk up the ladder, from the architecture that bit me to the one I actually ship.

Architecture 1: Pure Parallel (Fragile)

This is the most tempting shape and the most fragile. Every worker agent (red) runs blind.

graph TD
    A[Task Input] --> B[Main Agent]
    B --> C[Subtask 1]
    B --> D[Subtask 2]
    B --> E[Subtask 3]
    C --> F[Agent 1]
    D --> G[Agent 2]
    E --> H[Agent 3]
    F --> I[Combine]
    G --> I
    H --> I
    style F fill:#ff6b6b
    style G fill:#ff6b6b
    style H fill:#ff6b6b

Architecture 2: Linear with Full Context (Reliable)

Now the version I rebuilt toward. Agents run one after another, and each one inherits everything its predecessors did and decided (green).

graph TD
    A[Task Input] --> B[Main Agent: Plan]
    B --> C[Context: Task + Plan]
    C --> D[Agent 1]
    D --> E[Context: + Agent 1 work]
    E --> F[Agent 2]
    F --> G[Context: + Agent 2 work]
    G --> H[Main Agent: Finalize]
    style D fill:#51cf66
    style F fill:#51cf66

The whole trick is the Context: boxes between agents. Each agent doesn't get a fresh subtask — it gets the accumulated state of everything that happened before. Let's build that. First, the setup: a context object that records not just what each step did but why.

Notice reasoning riding along on line 12. That single field is the difference between an agent that knows what its predecessor did and one that knows why. With the context seeded, each agent in the chain reads the whole history before it acts:

There are no conflicting assumptions here because there are no independent assumptions — by the time agent 2 runs, agent 1's decisions are already part of the world it reasons about.

That agent.execute step is a real model call. Here's the smallest version of one, so the chain above isn't hand-waving — this block runs as written if ANTHROPIC_API_KEY is set:

Architecture 3: Linear with Context Compression (Advanced)

For a task that runs long enough, the history outgrows the context window. The fix is to compress — keep the decisions, drop the noise — without losing the trail.

Everyone obsesses over prompt engineering — the wording of the instruction. The bigger lever, by a wide margin, is context engineering: what information each agent sees, in what shape, in what order.

The difference is concrete. Compare what you could hand an agent:

Thin context — just the facts:

Rich context — the facts and the decisions behind them:

Same task. The second one prevents an entire class of errors — the agent won't reach for a second database, won't break multi-tenancy, won't forget rate limiting — because the reasoning is on the table, not just the outcome. Thin context forces the next agent to re-derive decisions, and re-derived decisions are where conflicts are born.

Mid-Module Checkpoint

Close the examples and answer these from memory before moving on:

1. In one sentence, why did adding agents make my first SDLC harness less reliable?
2. What does the reasoning field carry that a plain result field doesn't — and why does it prevent conflicts?
3. You're tempted to add context compression. What single question should you ask first?

Strip away the branding and the agent systems that actually hold up in production share the same spine, the one my harness converged on after the parallel disaster:

1. They default to linear. Parallelism is the exception you justify, not the default you reach for.
2. They propagate full context. Every step inherits the complete decision trail, not a summary.
3. They preserve reasoning, not just outcomes. The why travels with the what.
4. They earn every bit of complexity. Compression, parallel waves, sub-agents — each one is added only when a real limit forces it, and each one is paid for in reliability.

My harness today does run agents in parallel — but only across tasks I've proven are independent, in dependency-ordered waves, with an ordered merge at the end. That's the whole reconciliation of "parallel is a trap" with "I run parallel agents daily": parallelism is safe exactly when the two principles still hold — when the parallel units share no context they need from each other. The moment they do, you're back to linear, and you'll be glad you are.

Time to feel the difference rather than take my word for it. You'll build a small linear agent system for a content-creation task — outline, then draft, then edit — and watch how context propagation keeps the three steps coherent.

The task: given a topic, an outline agent produces a structure, a draft agent writes from it, and an edit agent tightens the result. The point is that each agent must see what the previous ones decided.

Start here:

Work it in stages. Reveal a hint only after you've tried.

Going further: once it runs, break it on purpose. Rewrite run to call all three steps with only the topic — no shared history — and compare the edit agent's output. The incoherence you'll see is the multi-agent trap, reproduced in fifteen lines.