Quartz 4

ADR-0003: Three-Tier Agent Hierarchy

3 min read

ADR-0003: Three-Tier Agent Hierarchy

Status

Accepted (2026-04-14)

Context

Исходная концепция: плоская структура — 30-50 агентов под одним оркестратором (CEO).

Проблемы плоской структуры:

  • Контекст оркестратора раздувается при 30+ ролях в системном промпте
  • Стоимость токенов для routing растёт квадратично (CEO должен знать все роли)
  • Отладка сложна: один уровень, непонятно кто отвечает за что
  • Agent coupling: все зависят от одного CEO промпта

Требования к решению:

  • Узкий контекст для каждого агента
  • Clear ownership: кто за что отвечает
  • Добавление новых агентов без изменения core
  • Аналогия реальной компании (понятно людям)

Decision

3-tier иерархия + cross-cutting agents:

L1: CEO (1)           — единственный с доступом к user
L2: Directors (5-7)    — по департаментам
L3: Executors (15-30)  — узкие исполнители
 X: Cross-cutting (2-3) — Judge, Librarian

Агенты общаются только через task queue. CEO не видит executors — только Directors. Directors не видят друг друга (только через CEO).

Alternatives Considered

Option A: Flat — CEO → 30+ Agents

  • Pros: простая routing логика, один уровень
  • Cons: context bloat (CEO промпт = 30+ ролей), quadratic routing cost (каждое сообщение = выбор из 30), tight coupling (новый агент = изменение CEO промпта), debug nightmare

Option B: 4-tier — CEO → VPs → Directors → Executors

  • Pros: больше decoupling, VP уровень для cross-department coordination
  • Cons: overkill для 30-50 агентов (у нас не 500), больше latency на каждый tier, сложнее понимать и объяснять, VP уровень = overhead без ценности на этом масштабе

Option C: 3-tier + Cross-cutting ← chosen

  • Pros: sweet spot complexity (не слишком плоско, не слишком глубоко), аналогия SMB-компании (CEO → Directors → Employees), легко добавлять executors не затрагивая CEO, clear ownership (Intel Director отвечает за intel), context per agent стабильный
  • Cons: Directors — потенциальный bottleneck при fan-out/fan-in, новый департамент = weight decision (новый Director), cross-department workflows только через CEO
  • Why chosen: оптимальный баланс для масштаба 30-50 агентов. Плоский не масштабируется, 4-tier — overkill. Реальный мир: SMB с 50 сотрудниками работает именно так.

Consequences

Positive

  • CEO context стабильный: 6-7 Directors, не 30+ executors
  • Директора знают только свой домен — узкий, качественный контекст
  • Executors stateless, горизонтально масштабируемы
  • Новый executor = добавить в roles.yaml + inform Director. CEO не трогаем.
  • Понятная ментальная модель: “как компания”

Negative / Trade-offs

  • Новый департамент = новый Director (весомое решение, ADR)
  • Cross-department workflows через CEO-посредник (дополнительный hop)
  • Directors — bottleneck если один домен доминирует (все задачи в Intel)

Mitigations

  • Cross-cutting agents (Judge, Librarian) работают поперёк без CEO
  • Несколько instance одного Director типа для параллелизма (Phase 2)
  • Monitor: какие Directors bottleneck → data-driven решение о restructure

Follow-ups

  • MVP: validate на 5 агентах (CEO + IntelDir + 2 executors + Judge)
  • Phase 2: добавить Sales, Marketing, Ops Directors
  • Monitor: escalation rate и queue depth per Director
  • Evaluate: нужен ли cross-department shortcut (Director → Director без CEO)?

References

Graph View

Backlinks