Modular Agent Systems Need Better Boundaries

This article explains how to think about modular AI agents as a set of operational boundaries: what each module owns, what it may touch, and what evidence it must leave behind. The point is not architectural purity. The point is making agent work easier to verify, resume, and trust.

Why “modular” often means “harder to reason about”

People reach for modularity because it sounds safer than one giant prompt or one giant service. That instinct is reasonable. But modularity can also hide responsibility if the boundaries are drawn around implementation details instead of around outcomes.

A system can have many modules and still be opaque if:

no one knows which module owns the final artifact,
state moves through hidden channels,
failures are swallowed between steps,
or the handoff rules are only described in prose.

In agent work, the useful question is not “How many modules do we have?” It is “Where does responsibility begin and end?”

If the answer is fuzzy, the system may be organized in code and disorganized in practice.

Boundaries should map to decisions, not abstractions

A good module boundary usually corresponds to a decision that matters operationally.

Examples:

drafting versus publishing,
planning versus executing,
retrieval versus synthesis,
local file writes versus external side effects,
or proposal generation versus operator approval.

Those are real boundaries because they change risk, verification, and recovery.

By contrast, boundaries that only reflect internal implementation layers are often less useful in agent systems. A neat separation between helper classes may look elegant, but if it does not clarify who can act, who can verify, and who can stop the run, it is mostly cosmetic.

The best modular design makes the next action obvious.

Each module should own one kind of evidence

A practical way to design modular agents is to assign each module a type of evidence it must produce.

For example:

a planning module should produce a task description or queue item,
a drafting module should produce a file on disk,
a verification module should produce a check result or readback,
a publishing module should produce a concrete external outcome,
and a logging module should produce a durable record of what happened.

This is powerful because it forces the system to become inspectable.

If a module says it completed work, the artifact or record should exist somewhere specific. If it cannot leave evidence, then it is not really a module in the operational sense; it is just a thought process.

That distinction matters a lot in agent systems, where fluent output can easily masquerade as completion.

Handoffs are where modular systems succeed or fail

The real difficulty in modular agent design is not the module itself. It is the handoff.

A handoff needs to answer four questions:

1. What is being passed forward?
2. What is now frozen?
3. What is still optional?
4. What proof will the next step accept?

If those questions are not answered, the next module has to guess. Guessing is expensive in agent systems because it creates duplicate work, hidden assumptions, and avoidable retries.

Good handoffs reduce surprise. They tell the next step exactly what is already settled and what still needs attention.

That is why modular systems should prefer explicit artifacts over implicit memory. A file, queue entry, or structured record can be handed off cleanly. A vague instruction buried in context cannot.

The filesystem is the simplest boundary technology

A lot of agent architecture becomes easier when the filesystem is treated as a first-class boundary surface.

Why?

Because files are:

durable,
inspectable,
easy to diff,
easy to resume from,
and easy to verify without special tooling.

If a module writes a draft, that draft can be reviewed later. If a module writes a log, the next module can read it. If a module writes a queue item, the system can pick it up again after interruption.

That makes the filesystem more than storage. It becomes the place where modularity becomes real.

This is especially useful for agent stacks that need to stay calm under interruption. A file boundary lets the system stop and start without losing the shape of the work.

Boundaries should reduce surprise, not maximize decomposition

It is tempting to decompose everything. More modules can feel more professional. But every new boundary also adds coordination cost.

A useful rule is this: split a module only when the split makes one of these better:

verification,
recovery,
permission control,
or operator understanding.

If the split does not improve one of those, it may not be worth it.

That rule keeps modularity tied to the actual job of the system. Agent stacks are not judged by how elegantly they are divided. They are judged by whether they produce the right artifact, at the right time, with the right level of risk.

A compact design pattern for modular agents

A good modular agent workflow often looks like this:

one module decides what should happen,
one module prepares the work product,
one module verifies the result,
and one module records the outcome.

That is enough for many systems.

The modules do not need to be large. They need to be explicit. Each one should have a narrow job, a clear handoff, and a visible artifact.

When that is true, the stack becomes easier to operate because every step can be inspected independently. When it is not true, modularity becomes a way to hide complexity instead of managing it.

Conclusion: draw boundaries where trust changes

The most useful boundaries in modular agent systems are the ones where trust changes.

Draft to publish.

Plan to execute.

Internal reasoning to durable artifact.

Local state to external side effect.

If you design around those transitions, the system becomes easier to verify and easier to resume. If you design around implementation convenience alone, the modules may look tidy while the workflow remains confusing.

The practical next step is simple: identify one agent workflow you already have, mark the places where risk or permission changes, and turn those into explicit boundaries. Then require each boundary to leave behind a file, record, or check that the next step can trust.