Module 7: Multi-Agent Architecture

This is Module 7 of a 12-part curriculum: Build Software Products with AI — From First Principles to Production Pipeline.

Multi-agent systems feel complex. In practice, the core design decisions are straightforward — if you approach them with the right questions.

This module is about system design: how to decide what agents to build, how to specialise them, how they communicate, and how to keep the whole system coherent as it grows.

Why Multiple Agents?

Before designing a multi-agent system, you should be able to answer why you need one.

Legitimate reasons:

Specialisation. Different tasks benefit from different contexts, personas, and tool sets. A content agent and a coding agent have fundamentally different system prompts, different tools, and different operating rhythms. Putting them in the same agent creates context pollution — the coding tools confuse the content work and vice versa.

Parallelism. Independent tasks can be worked on simultaneously. A research agent and a writing agent can operate in parallel on a brief where research feeds into writing — cutting overall time.

Context isolation. Some tasks have sensitive context that shouldn’t be mixed with others. A financial analysis agent shouldn’t have the same context window as a public-facing customer service agent.

Scalability. One agent handling everything becomes a bottleneck. Multiple agents can handle concurrent requests.

Not legitimate reasons:

Adding complexity for its own sake. If a single capable agent with good tools can handle the workload, use that.

Because the architecture diagram looks impressive. Complexity has a cost. Every agent is infrastructure to maintain, debug, and update.

The right question: “Does this task genuinely benefit from a separate agent, or am I just over-engineering?”

Specialised vs Generalist

The spectrum runs from fully specialised (one agent per task type) to fully generalist (one agent handles everything). Neither extreme is usually right.

Fully specialised gets expensive to maintain. Ten agents means ten system prompts to keep updated, ten memory files to manage, ten sets of tools to maintain.

Fully generalist gets overloaded. A single agent handling content, code, email, scheduling, research, and finance either has a bloated system prompt or lacks the focused depth each domain needs.

The sweet spot: a small number of agents, each with a clear and meaningful scope of responsibility.

For a personal AI stack, four to six agents is typical:

• Main orchestrator (cross-cutting intelligence, coordination)
• Coding agent(s) (one per major project or project type)
• Content agent (if content is a meaningful workload)
• Communication agent (email, messages)
• Research agent (optional, if deep research is recurring)

For a product, the roster is shaped by user-facing responsibilities and internal automation needs.

Communication Patterns

How do agents in a multi-agent system communicate with each other?

Centralized (orchestrator → sub-agents). The orchestrator is the hub. All communication flows through it. Sub-agents return results to the orchestrator, never directly to other sub-agents. Simple to reason about; the orchestrator is a single point of coordination (and failure).

Peer-to-peer. Agents can communicate directly with each other without routing through a central orchestrator. More flexible; harder to debug and audit.

Event-driven. Agents subscribe to events (a new file appeared, a message was posted, a task changed state). Any agent can produce an event; any agent can consume one. Highly decoupled; can get complex quickly.

Shared state. Agents communicate via a shared resource — a file, a database, a queue. Agent A writes a task to a JSON file; Agent B picks it up. Simple and inspectable; requires careful concurrency management.

In practice, most personal and small-scale systems use a combination of centralized orchestration and shared state. The orchestrator coordinates; agents read from and write to shared files as needed.

My own setup uses shared state extensively: agents write to the Obsidian vault, read from the backlog JSON, and write to daily memory files. The orchestrator (Ultron) coordinates across agents via sessions and direct spawning.

Context Isolation in Practice

Each agent should have exactly the context it needs — no more.

System prompt: Specific to the agent’s domain and responsibilities. The coding agent’s prompt has nothing about content strategy. The content agent’s prompt has nothing about git.

Memory files: Agents can share some memory (e.g., USER.md — everyone needs to know who they’re helping) but should have their own workspace for domain-specific context.

Tool access: Each agent gets only the tools it needs. The email agent doesn’t need shell access. The coding agent doesn’t need the email API.

This isn’t just best practice — it’s a security principle. Limiting each agent to what it needs reduces the blast radius of mistakes. An agent that can only read emails can’t accidentally delete files. An agent without network access can’t exfiltrate data.

State and Coordination

Multi-agent systems need a shared understanding of “where things are.” Without it, agents duplicate work, step on each other’s changes, or fail to pick up where the previous agent left off.

Practical coordination mechanisms:

Task registry. A JSON file (or database table) tracking tasks: what they are, who owns them, what state they’re in, what the output was. Agents check the registry before starting work and update it when done.

Backlog board. A structured list of work items with states (ideas → ready → in-progress → review → done). Agents pick from the backlog rather than accepting arbitrary instructions — ensures clear ownership and no duplication.

Shared vault. A common location (like an Obsidian vault) where agents write outputs, read context, and exchange information. Human-readable and auditable.

Branch discipline in code. Each coding agent works in its own git branch. This is the code equivalent of context isolation — agents can’t overwrite each other’s work.

Agent Personas

Each agent should have a persona defined in its system prompt or a dedicated SOUL.md. Not for cosmetic reasons — personas shape the agent’s reasoning and communication style.

A coding agent should be precise, sceptical of its own output, and focused on correctness. A content agent should be creative, voice-aware, and audience-focused. A communication agent should be professional, concise, and context-sensitive.

If all your agents have the same “helpful assistant” persona, they’ll all produce the same kind of output regardless of the task. Differentiate the personas and you differentiate the outputs.

The Roster in Production

To make this concrete — here’s my actual agent roster:

┌───────────────────────────────────────────────────────────┐
│                  YOU (the human)                         │
│                                                           │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────────┐ │
│  │  Telegram   │  │    Slack     │  │ Mission Control  │ │
│  │  (mobile)   │  │  (channels)  │  │   (dashboard)    │ │
│  └──────┬──────┘  └──────┬───────┘  └────────┬─────────┘ │
└─────────┼────────────────┼───────────────────┼────────────┘
          │                │                   │
          ▼                ▼                   ▼
┌───────────────────────────────────────────────────────────┐
│                    AGENT LAYER                            │
│                                                           │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌─────────┐ │
│  │ ULTRON    │  │ ALEX      │  │ COACH     │  │ MAILBOX │ │
│  │ orchestr. │  │  content  │  │mgmt coach │  │  email  │ │
│  │           │  │           │  │           │  │         │ │
│  │ Cloud LLM │  │ Local LLM │  │ Local LLM │  │Local LLM│ │
│  │ (Claude)  │  │(qwen 30b) │  │(qwen 30b) │  │(qwen 7b)│ │
│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘  └────┬────┘ │
│        │              │              │              │       │
│        └──────────────┴──────┬───────┴──────────────┘       │
│                              │                               │
└──────────────────────────────┼───────────────────────────────┘
                               │
                               ▼
┌────────────────────────────────────────────────────────────┐
│                   KNOWLEDGE LAYER                         │
│                                                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐ │
│  │   Obsidian   │  │  JSON Files  │  │  Agent Memory    │ │
│  │    Vault     │  │ (projects,   │  │  (per-agent      │ │
│  │    (PARA)    │  │   tasks,     │  │   learning       │ │
│  │              │  │   schedule)  │  │   files)         │ │
│  └──────────────┘  └──────────────┘  └──────────────────┘ │
└────────────────────────────────────────────────────────────┘

Each agent has its own workspace, its own memory files, and its own tool set. They share USER.md and some global context but operate independently.

The model selection is intentional: Ultron gets the best model (it handles the most complex reasoning). Specialist agents with more constrained tasks run on local models — lower cost, better privacy, good enough for the work.

When the System Gets Complex

Multi-agent systems have a tendency to grow. New agents get added. Responsibilities blur. The system that was clean at four agents becomes confusing at eight.

Signs you need to refactor:

• It’s unclear which agent owns a given responsibility
• Agents are duplicating work
• Changing one agent’s behaviour requires changing several others
• Nobody (including you) can describe what each agent does in one sentence

The fix is almost always simplification: merge overlapping agents, clarify responsibility boundaries, and document the system architecture explicitly. Keep a diagram (even a simple text list) of agents, responsibilities, and communication paths. If you can’t draw it clearly, the system isn’t clear.

What’s Next

You have a multi-agent architecture — a roster of specialised agents with clear responsibilities, clean communication patterns, and coordinated state. In Module 8, we get specific about the thing most people want to build: an agentic coding pipeline. How to structure it, how to prevent agents from colliding, and what production discipline actually looks like.

Further Reading

• [Paper] ChatDev: Communicative Agents for Software Development — Qian et al., 2023 — Shows multi-agent systems producing real software. The role specialisation model is instructive.
• [Paper] MetaGPT: Meta Programming for Multi-Agent Framework — Hong et al., 2023 — Multi-agent systems with structured role assignment and workflow. The most ambitious academic multi-agent implementation.
• [Paper] A Survey on LLM-based Autonomous Agents — Wang et al., 2023 — The broadest survey of agent architectures. Section 4 on multi-agent systems is directly relevant.
• [Docs] CrewAI Documentation — The most popular framework for role-based multi-agent systems. Worth reading even if you don’t use it.

Referenced from @nikovijay

“This is my Mission Control: A Squad of 10 autonomous @openclaw agents… The people who thrive next won’t be the deepest specialists.” — @pbteja1998

“We’re opening up a new job role for Firecrawl. This time humans aren’t allowed to apply. AI Agents only.” — @nickscamara_