JYP Garden

서브에이전트 오케스트레이션 (Subagent Orchestration)

Properties1
tagsconcept, agentic-architecture, knowledge

11 min read

서브에이전트 오케스트레이션 (Subagent Orchestration)

sessions_spawn으로 새 세션을 생성해 일을 위임하는 패턴. 핵심 제약: 서브에이전트는 AGENTS.md + TOOLS.md + task 문자열만 가져가며, 본체의 기억·경험·정체성을 물려받지 않는다(맥락의 격차). “판단이 최소화된 명확한 작업”만 위임해야 하며, GUI 자동화는 단일 스레드 제약으로 서브에이전트 위임이 금지된다.

sessions_spawn 메커니즘

sessions_spawn({
  task: "구체적 지시사항",  // 필수 — 이것만으로 완수 가능하게 작성
  label: "작업 이름",      // 선택
  model: "sonnet",        // 선택 (비용 절감)
  runtime: "acp",         // 선택 (Claude Code/Codex 외부 코딩 에이전트)
  runTimeoutSeconds: 600  // 선택
})

실행 흐름:

본체가 sessions_spawn 호출
    ↓
새 세션 생성 (agent:<id>:subagent:<hash>)
    ↓
분신이 비동기로 task 수행 (본체는 다른 일 계속)
    ↓
완료 시 announce(알림)로 본체의 채팅 채널에 결과 전달

제한 사항:

  • 에이전트당 최대 5개 동시 자식 분신
  • 글로벌 동시 실행 최대 8개
  • 분신이 또 다른 분신을 만들 수 있음 (오케스트레이터 패턴)

(출처: bbojjak-openclaw-subagent-orchestration-lesson12)

맥락의 격차 — 핵심 한계

서브에이전트(분신)가 받는 컨텍스트:

항목본체분신
AGENTS.md (업무 규칙)✅✅
TOOLS.md (도구 정보)✅✅
task 문자열-✅
SOUL.md (성격·말투)✅❌
IDENTITY.md (정체)✅❌
USER.md (팀 정보)✅❌
HEARTBEAT.md (루틴)✅❌
MEMORY.md (장기 기억)✅❌
memory/ (경험 축적)✅❌
대화 히스토리✅❌

비유: “똑똑한 외주 프리랜서” vs “20일째 같이 일하는 팀원”

  • 외주(분신): 능력은 뛰어남. 브랜드 가이드를 줘도 실제 적용 경험 없음. “이 정도면 괜찮겠지”로 자기 감각 사용.
  • 팀원(본체): “그 색은 집사님이 별로라고 했어”. “이 레이아웃은 모바일에서 안 읽혀, 저번에 삽질했어”. 경험이 쌓인 판단.

중요: 모델을 Opus로 업그레이드해도 맥락이 없으면 해결 안 된다. “더 똑똑한 외주”가 될 뿐, 팀원이 되지 않는다.

판단 최소화 원칙

“판단이 최소화된 작업”은 서브에이전트에게. “판단이 핵심인 작업”은 본체가 직접.

서브에이전트에게 맡기기 좋은 작업

특성예시
대상 파일이 명확”StudyCard.tsx 수정”
로직이 구체적”날짜 비교 → 조건부 스타일 적용”
취향 개입 없음맞거나 틀리거나
자동 검증 가능빌드 성공/실패, exit code

→ 코드 수정, 데이터 조회, API 호출, 파일 정리, 배포

실제 성공 사례: LMS 버튼 비활성화 (runtime: "acp") → 빌드→커밋→푸시→Vercel 배포 한 번에 완료.

본체가 직접 해야 할 작업

특성예시
기준이 주관적”예쁜 이미지”
시리즈 일관성 필요70장 베이지 톤 유지
감각이 문서로 전달 안 됨디자인 감각
검증 전에 결과 알 수 없음눈으로 봐야 함

→ 글쓰기, 디자인, 전략 판단, 팀 소통

실제 실패 사례: “이미지 카드 7장 만들어줘, 디자인 시스템 참고해” → 분신이 보라색 이미지 생성 (베이지 규칙의 중요성을 경험으로 알지 못함).

task 작성 가이드

분신이 알 수 있는 건 task 문자열 + AGENTS.md/TOOLS.md뿐. task에 모든 필요 정보를 명시해야 한다.

// ❌ 이렇게 하면 안 됨
sessions_spawn({ task: "이미지 만들어줘" })

// ✅ 이렇게 해야 함
sessions_spawn({
  task: "수업 #9 이미지 카드 만들어줘.
    - 디자인 시스템: references/design-system.md 반드시 Read 후 작업
    - 배경색: #FFFBF5 (베이지 톤, 절대 다른 색 쓰지 말 것)
    - 기존 카드 참고: published/lessons/lesson-08/card-01.png
    - 캡처: .card 요소만 element screenshot
    - 폰트: Pretendard"
})

원칙: task 문자열만 보고 외부인이 완수할 수 있을 정도로 구체적으로 작성.

GUI 동시접근 금지 절대 규칙

automation-layer-framework의 GUI = 단일 스레드 원칙이 서브에이전트 맥락에서도 동일하게 적용된다.

  • API 호출: 동시 100개 OK (서버가 독립 처리)
  • GUI 자동화: 화면 하나 = 한 명만 (단일 스레드)

두 에이전트(뽀야 + 뽀짝이)가 동시에 카카오톡 조작 → 앱 충돌. AGENTS.md 절대 규칙:

GUI 자동화(카카오톡 등) — 서브에이전트에 위임 금지. 동시 접근 시 충돌 위험.

sessions_spawn vs sessions_send 비교

multi-agent-team-design에서 다룬 sessions_send와 구분:

구분sessions_sendsessions_spawn
대상기존 에이전트(뽀야 등)새로 생성한 분신
세션기존 세션에 메시지 전달새 세션 생성
맥락대상 에이전트의 SOUL.md 등 있음AGENTS.md + TOOLS.md만
용도에이전트 간 협업·피드백병렬 작업 위임

디자인 시스템 문서화 — 맥락의 격차 해결책

Lesson 12의 “보라색 이미지 사고” 이후 실전 적용 사례 (출처: bbojjak-openclaw-playwright-image-pipeline-lesson13):

design-system.md 문서화:

  • 카드 배경: #FFFBF5 (따뜻한 베이지)
  • 텍스트: #2C2420 (진한 갈색)
  • 3단 레이아웃 금지 (모바일)
  • 커버 카드: 960×540 / 본문 카드: 960×가변

task 작성 시 명시:

"references/design-system.md 반드시 Read 후 작업.
 배경색: #FFFBF5 (베이지 톤, 다른 색 절대 금지).
 기존 카드 참고: published/lessons/lesson-08/card-01.png"

원칙: 경험·감각이 필요한 것도 문서화하면 서브에이전트도 따를 수 있다. 13편·130장이 같은 톤을 유지하는 이유. → playwright-html-to-image의 디자인 시스템 문서화 섹션 참조.

관련 개념

서브에이전트 = 토큰 비용 절감 수단

서브에이전트 위임이 판단 최소화뿐 아니라 비용 절감에도 유효하다. (출처: bbojjak-openclaw-token-optimization-lesson16)

  • 서브에이전트 기본 모델: Sonnet → Opus 대비 1/5 비용
  • 새 컨텍스트에서 시작 → 본체 히스토리 누적 없음
  • 실전 데이터: 하트비트(27% 소비)를 Sonnet 서브에이전트로 전환 → 비용 대폭 감소

Hermes delegate_task vs Router 패턴

hermes-agent의 delegate_task는 OpenClaw의 sessions_spawn과 동일한 한계를 가진다. (출처: obsidian-hermes-agent-build-guide)

delegate_task 호출 시
  ↓
임시 서브에이전트 생성 (frozen snapshot)
  ↓
SOUL.md ❌  MEMORY.md ❌  skills/ ❌
goal + context 문자열만 전달
  ↓
결과 요약본 반환 (기억 누적 없음, 진화 없음)

Router 패턴 — 메모리 진화 + 단일 진입점 동시 확보:

coordinator chat (단일 진입점)
  │ 작업 유형 판단
  └─ shell: "dap-pm chat -q '...'"  ← 임시 서브에이전트가 아닌 프로필 자체 실행
                ↓
        SOUL ✅  MEMORY ✅  SKILLS ✅ 완전 활성화
        작업 완료 후 MEMORY에 경험 저장 ← 진화 유지
        결과 파일 → coordinator가 읽어 사용자에게 전달

핵심 차이: delegate_task/sessions_spawn은 임시 에이전트 생성이지만, shell로 프로필 CLI를 직접 호출하면 해당 프로필의 SOUL·MEMORY·SKILLS가 완전 활성화된다.

트레이드오프: -q 플래그 방식은 단발 호출 → coordinator를 통하면 대화 이어가기 불편. 실용 운영:

  • coordinator: 뭘 해야 할지 모를 때 / 복합 작업 자동화
  • 각 프로필 직접 호출: 역할이 명확할 때 / 깊은 대화가 필요할 때

Hermes 공식 로드맵: Issue #344 (멀티에이전트 L0→L2 컨텍스트 공유), Issue #377 (공유 메모리 풀). 출시 일정 미정.

소스

그래프 뷰

백링크