Agentic System Architecture: Patterns for Multi-Agent Workflows

By Tyler Cyert

Building an agentic system is not the same as writing a prompt. An agentic system is a set of AI agents with defined roles, scoped tools, and structured communication that collaborate to accomplish work humans used to do manually. The system is designed once and runs repeatedly — each agent knows its job, its boundaries, and who it hands off to.

This guide covers the architecture patterns that actually work in production, based on how teams are building with Claude Code, OpenCode, and similar agent harnesses.

The Three Layers of an Agentic System

Every agentic system has three layers, whether you build them explicitly or let them emerge by accident. Building them explicitly is better. The harness layer — covered in our guide to agent harnesses — manages context, tools, and memory.

Layer 1: Agent Definitions

Each agent is a markdown file with YAML frontmatter that defines:

In Claude Code, these live at .claude/agents/<name>.md:

---
name: code-reviewer
description: Reviews code changes for correctness, security, and style
tools: Read, Glob, Grep
model: sonnet
permissionMode: plan
---

You review code changes. For each file, check:
1. Logic errors and edge cases
2. Security vulnerabilities (injection, auth bypass)
3. Style consistency with the project
4. Test coverage gaps

Output a structured report with severity levels.

The key insight: the agent definition is the contract. Anyone who reads the file knows exactly what the agent does, what it can access, and what it produces. No hidden behavior.

Layer 2: Orchestration

Orchestration is the logic that decides which agent handles which task. In most agentic systems, one agent acts as the orchestrator — it receives requests, breaks them into tasks, and delegates to specialists.

The orchestrator's instructions live in the root instruction file (CLAUDE.md or AGENTS.md). This file should document:

A well-written orchestrator instruction file means the system is self-documenting. Anyone who reads it understands the entire workflow.

Layer 3: Shared State

Agents need to pass information to each other. In file-based agentic systems, the filesystem *is* the shared state layer:

This is simpler and more debuggable than message queues or databases. If something goes wrong, you open the directory and inspect the intermediate output.

Architecture Patterns

Pattern 1: Sequential Pipeline

Orchestrator → Agent A → Agent B → Agent C

Each agent reads from the previous agent's output and produces input for the next. This is the simplest pattern and works for any workflow with clear stages.

Examples: - Content: Research → Write → Edit → Publish - Code: Design → Implement → Test → Review - Data: Ingest → Transform → Validate → Export

When to use: The work has natural stages where each step depends on the previous one.

Pattern 2: Parallel Fan-Out

Orchestrator → Agent A
             → Agent B  → Aggregator
             → Agent C

Multiple agents work on the same input simultaneously, and an aggregator combines their results. This is faster than sequential for work that can be done independently.

Examples: - Review: Security reviewer + Performance reviewer + Style reviewer → Combined report - Research: Multiple researchers investigate different angles → Synthesis - Testing: Unit tests + Integration tests + E2E tests → Coverage report

When to use: Subtasks are independent and can run without waiting on each other. Use worktree isolation so agents don't step on each other's files.

Pattern 3: Hub and Spoke

        ← Agent A (reads + writes)
Source ← Agent B (reads + writes)
        ← Agent C (reads + writes)

A shared source (like a knowledge base or codebase) is read and maintained by multiple agents, each with a different responsibility. There's no strict ordering — agents operate as needed.

Examples: - The Karpathy Wiki pattern: Ingestor, Researcher, and Auditor all maintain a shared wiki - Codebase maintenance: Linter, Documenter, and Dependency Updater each maintain different aspects

When to use: The system is reactive rather than sequential — agents respond to events rather than following a fixed pipeline.

Pattern 4: Hierarchical Delegation

Lead → Team A Lead → Worker A1
                   → Worker A2
     → Team B Lead → Worker B1
                   → Worker B2

The orchestrator delegates to team leads, who delegate to workers. This scales better than flat delegation because each lead manages a smaller scope.

When to use: The system is large enough that one orchestrator can't effectively manage all agents directly.

Configuration as Code

The most important architectural decision is treating your agent system as code:

  1. Version control everything. Agent definitions, instruction files, settings, skills — all committed to git.
  2. Review agent changes like code changes. A PR that modifies an agent definition should get the same scrutiny as a code change.
  3. Test your agents. Run them against known inputs and verify outputs.
  4. Keep definitions portable. Plain markdown and JSON that any compatible harness can read.

Getting Started

The fastest path to a working agentic system:

  1. Identify 2-3 agent roles from your existing workflow. Don't over-engineer — start small.
  2. Write the orchestrator instructions describing the workflow and available agents.
  3. Define each agent with a focused system prompt and scoped tools.
  4. Set up working directories so agents have clear read/write boundaries.
  5. Run it and iterate. The first version won't be perfect. Observe where agents make mistakes and tighten instructions.

DotBox lets you do this visually — draw your agents on a canvas, configure them, and export the complete file structure. Start with one of the built-in templates (Karpathy Wiki, Lead Gen, Blog Writing, Software Dev) and customize from there.

Common Mistakes