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.
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.
license
MIT
metadata
{"author":"dvy1987","version":"1.2","category":"project-specific","sources":"Azure Architecture Center, arXiv:2601.02577 (Orchestral AI), arXiv:2601.07526 (Megaflow), agentskills.io","resources":{"references":["examples.md"]}}
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:
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-<system-name>-arch.md
Append to docs/skill-outputs/SKILL-OUTPUTS.md:
Agent Definitions (Role, Tools, Prompt Strategy for each).
Wiring Diagram (Mermaid.js flow).
State & Memory Strategy (How agents remember and share).
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
