108 lines
4.3 KiB
Markdown
108 lines
4.3 KiB
Markdown
---
|
|
title: Multi-Agent Design Patterns
|
|
created: '2026-05-25'
|
|
updated: '2026-05-25'
|
|
type: concept
|
|
namespace: work
|
|
tags: [agent, architecture, system]
|
|
confidence: medium
|
|
sources:
|
|
- wiki/concepts/executor-orchestrator.md
|
|
- wiki/concepts/autonomous-agent-safety.md
|
|
- wiki/concepts/agent-memory-architecture.md
|
|
related:
|
|
- "[[concepts/executor-orchestrator]]"
|
|
- "[[concepts/autonomous-agent-safety]]"
|
|
- "[[concepts/agent-memory-architecture]]"
|
|
---
|
|
|
|
# Multi-Agent Design Patterns
|
|
|
|
Synthesis of recurring patterns across the personal-os multi-agent system
|
|
and related agent architectures. Distilled from [[concepts/executor-orchestrator]],
|
|
[[concepts/autonomous-agent-safety]], and [[concepts/agent-memory-architecture]].
|
|
|
|
## Pattern 1 — Orchestrator / Worker Split
|
|
|
|
**What:** One agent owns conversation state and decision authority
|
|
(orchestrator); spawns separate worker agents for discrete tasks.
|
|
|
|
**Why:** Tight coupling between conversational layer and execution layer
|
|
causes mid-task interruptions and breaks user flow. Separate concerns.
|
|
|
|
**In personal-os:** Eagle (orchestrator) → Executor (worker) via Zulip.
|
|
**In psychologist app:** Narrator (orchestrator/mediator) ← Analyst (worker).
|
|
|
|
**Key constraint:** Worker communicates only through structured messages;
|
|
orchestrator has the only escalation path to the human.
|
|
|
|
## Pattern 2 — Scope Boundary + Auto-Approve Table
|
|
|
|
**What:** Predefine which actions a worker may take autonomously and which
|
|
require escalation. Publish the table explicitly.
|
|
|
|
**Why:** Autonomous agents fail catastrophically when they expand scope
|
|
unexpectedly (see [[concepts/executor-security-incident]]). Explicit tables
|
|
make failure modes visible.
|
|
|
|
**Implementation:** Message-type-based approval table. Unknown message types
|
|
default to escalation, never to silent proceed.
|
|
|
|
| Risk Level | Agent Action |
|
|
|---|---|
|
|
| Low (read, build, test) | Auto-approve |
|
|
| Medium (write external, open PR) | Auto-approve with logging |
|
|
| High (comment on others, merge) | Always escalate |
|
|
| Unknown | Always escalate |
|
|
|
|
## Pattern 3 — Memory Layer Separation
|
|
|
|
**What:** Separate in-session state (working memory) from cross-session
|
|
knowledge (semantic memory) from immutable facts (procedural/episodic).
|
|
|
|
**Why:** Agents that blur these layers either hallucinate stable facts or
|
|
fail to retain important session-to-session knowledge.
|
|
|
|
**In personal-os:** status.md (working) / wiki pages (semantic) /
|
|
SCHEMA.md + vault-filling-guide (procedural). See [[concepts/agent-memory-architecture]].
|
|
|
|
**Pattern rule:** Never update semantic memory from within an active session.
|
|
Crystallize post-session. Never trust working memory as a source of truth
|
|
for facts (always re-derive from semantic layer at session start).
|
|
|
|
## Pattern 4 — Role Specialization over Generalization
|
|
|
|
**What:** Instead of one agent with a long system prompt covering all roles,
|
|
split into agents with narrow, non-overlapping responsibilities.
|
|
|
|
**Why:** LLMs produce better outputs when role context is tight. Conflated
|
|
roles lead to persona drift ("is it being analytical or empathetic right now?").
|
|
|
|
**In psychologist app:** Analyst stays in 3rd-person analytical mode;
|
|
Narrator stays in 1st-person user-facing mode. Neither crosses the boundary.
|
|
|
|
**Trade-off:** Coordination overhead (structured message passing between
|
|
agents). Worthwhile when roles genuinely conflict (analysis vs. empathy).
|
|
|
|
## Pattern 5 — Deterministic Algorithm for Predictable Steps
|
|
|
|
**What:** Identify steps that look like LLM tasks but are actually
|
|
deterministic (sequencing, routing, counting) and implement them as code,
|
|
not as LLM calls.
|
|
|
|
**Why:** LLMs are expensive and non-deterministic. Steps like "show next
|
|
question in list" do not benefit from LLM reasoning and introduce failure modes.
|
|
|
|
**Examples:**
|
|
- Question delivery in psychologist app: batch generated by Analyst,
|
|
sequenced by UI algorithm — not an LLM call per question
|
|
- Approval table in Executor: code switch on message type, not LLM judgment
|
|
- Vault namespace routing: rules in tech/vault-namespace, not agent inference
|
|
|
|
## See Also
|
|
|
|
- [[concepts/executor-orchestrator]] — concrete orchestrator/worker implementation
|
|
- [[concepts/autonomous-agent-safety]] — safety checklist derived from incidents
|
|
- [[concepts/agent-memory-architecture]] — memory taxonomy for LLM agents
|
|
- [[entities/psychologist-app]] — dual-agent architecture (patterns 1 and 4)
|