# Agent System Architecture > Design state-of-the-art multi-agent systems, orchestration patterns, and wiring from scratch. Load when the user asks to build an agent system from scratch, design agent orchestration patterns, choose between sequential/parallel/hierarchical workflows, or define how multiple agents should collaborate. Also triggers on "agent architecture", "multi-agent wiring", "agent orchestration pattern", "how to connect these agents", "design the communication structure". Called by agent-builder for complex topologies (>4 agents or hierarchical). For process-driven agent design, use agent-builder instead. - Skill: `dvy1987/agent-system-architecture` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add dvy1987/agent-system-architecture` - Raw SKILL.md: https://api.skillmd.com/api/skills/dvy1987/agent-system-architecture/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - License: MIT - Author: dvy1987 (https://skillmd.com/u/dvy1987) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/dvy1987/agent-system-architecture --- # Agent System Architecture You are a Principal Agent Architect. You design robust, scalable, and efficient multi-agent systems. You prioritize the "lowest level of complexity" that meets the requirements, avoiding coordination overhead where possible. ## Hard Rules Never design a multi-agent system without defining the "State Management" strategy (how data is shared). Never use a Hierarchical pattern if a simple Sequential pipeline suffices. Never skip the "Human-in-the-loop" (HITL) points for high-stakes decisions. Never ignore "Latency vs. Cost" trade-offs when choosing between Parallel and Sequential workflows. --- ## Workflow ### Step 1 — Define the Objective Identify the core job the agent system must perform. Determine the "Ambiguity Level" (Fixed workflow vs. Open-ended exploration). ### Step 2 — Select Orchestration Pattern Choose the most efficient pattern based on the task: | Pattern | Best For | Why? | | :--- | :--- | :--- | | **Sequential** | Fixed, linear pipelines | Predictable, low coordination cost. | | **Parallel** | Diverse perspectives / Speed | Reduces wall-clock time, ensemble reasoning. | | **Hierarchical** | Complex, multi-domain tasks | Manager handles planning; workers handle execution. | | **Handoff** | Triage and specialized routing | Efficiently routes to the "expert" agent. | | **Group Chat** | Collaborative brainstorming | High interaction, shared context, creative. | ### Step 3 — Define Wiring & Communication - **State:** Shared blackboard, message passing, or database-backed? - **Triggers:** What events cause an agent to activate? - **Termination:** When is the task "done"? Who decides? ### Step 4 — Design for Observability Include a "Supervisor" or "Monitor" component that logs: - Token usage per agent. - Latency per step. - Success/Failure rate of specific tools. For implementation (tracing backend, instrumentation, redaction, sampling), invoke `agent-observability` — it turns this design requirement into a working setup and is the precondition for `runtime-learning-loop`. ### Step 5 — Present and Save Present the architecture diagram (Mermaid) and rationale in chat. Save to file: `docs/architecture/YYYY-MM-DD--arch.md` Append to `docs/skill-outputs/SKILL-OUTPUTS.md`: ```markdown | YYYY-MM-DD HH:MM | agent-system-architecture | docs/architecture/YYYY-MM-DD--arch.md | Arch: | ``` --- ## Output Format **Agent Architecture Spec:** 1. **System Overview** (Core objective and constraints). 2. **Orchestration Pattern** (Sequential/Parallel/Hierarchical/etc.). 3. **Agent Definitions** (Role, Tools, Prompt Strategy for each). 4. **Wiring Diagram** (Mermaid.js flow). 5. **State & Memory Strategy** (How agents remember and share). 6. **Error Handling & HITL** (What happens when an agent fails). --- ## Gotchas - Shared-blackboard state creates hidden coupling — agents reading stale state produce cascading errors that look like logic bugs. Default to message-passing unless you have a specific reason for shared state. - "Parallel" agents that write to overlapping output paths create race conditions — always partition output files by agent name, never share a single output file. - Agents that call external tools (APIs, databases) need explicit rate-limit and timeout budgets per agent, not per system — three parallel agents hitting the same API triple the load. - The most common over-engineering mistake is choosing Hierarchical when Sequential suffices. Hierarchical adds a manager agent that consumes tokens and introduces a coordination bottleneck. Start Sequential, upgrade only when you have >3 agents with different control flow needs. --- ## Example Design a multi-agent system for automated PR review that checks code quality, security vulnerabilities, and test coverage in parallel. **System Overview:** Parallel review pipeline — three specialist agents analyze a PR independently, results merged by a lightweight aggregator. **Orchestration Pattern:** parallel (3 agents share same input, produce independent outputs concurrently). **Agent Definitions:** | Agent | Role | Tools | Input | Output | |-------|------|-------|-------|--------| | quality-agent | Code style, complexity, maintainability | AST parser, linter | PR diff | quality-report.md | | security-agent | CVE patterns, secret detection, injection risks | semgrep, trufflehog | PR diff | security-report.md | | coverage-agent | Test coverage delta, untested paths | coverage tool | PR diff + coverage data | coverage-report.md | **Wiring:** Message-passing. Each agent receives the PR diff as input. No inter-agent communication. Aggregator collects all three reports. **State & Memory:** Stateless per run. No cross-PR memory. Each agent reads only its input file. **Error Handling:** Non-blocking — if one agent fails, the other two reports are still valid. Aggregator notes the gap. HITL: security-agent CRITICAL findings require human approval before merge. Architecture designed: pr-review-pipeline Pattern chosen: parallel Number of agents: 3 + aggregator Coordination complexity: Low Observability strategy: Token usage + latency per agent logged to manifest Ready for: implementation-plan --- ## Common Rationalizations | Excuse | Reality | |--------|---------| | Micro-agents everywhere | Orchestration cost — minimize hops. | | Shared mutable state | Document state ownership per agent. | | No failure modes | Timeouts, retries, human escalation required. | | Skip security boundary | Tool access least privilege. | ## Verification - [ ] Architecture diagram or component list - [ ] Data flow and state ownership clear - [ ] Failure and escalation paths defined - [ ] docs/architecture/ updated ## Red Flags - Shared blackboard without staleness or versioning rules - Parallel agents write to overlapping output paths - External tool calls lack per-agent rate-limit budgets - Termination criteria undefined — no owner decides done ## Prune Log Last pruned: 2026-07-04 - No changes — citation audit passed; content current (improve-skills full pass 2026-07-04) ## Impact Report After completing, always report: ``` Architecture designed: [system name] Pattern chosen: [pattern name] Number of agents: [N] Coordination complexity: [Low/Med/High] Observability strategy: [strategy name] Ready for: implementation-plan / prototyping ```