개요

서브 에이전트는 주 에이전트가 생성하는 백그라운드 프로세스이다. 독립된 컨텍스트에서 실행되며, 비동기적으로 작업을 처리하고 결과를 요청 채널에 요약하여 보고한다.

동작 방식

  1. 주 에이전트가 서브 에이전트를 스폰(spawn)
  2. 서브 에이전트가 격리된 컨텍스트에서 작업 수행
  3. 논블로킹(non-blocking) 방식으로 runId 즉시 반환
  4. 작업 완료 시 요약을 요청 채널에 포스팅
[주 에이전트] ──spawn──→ [서브 에이전트 #1] ──(작업 중)──→ [요약 포스트]
            ──spawn──→ [서브 에이전트 #2] ──(작업 중)──→ [요약 포스트]
            ──(계속 다른 작업)──→

/subagents 명령어

명령어설명
/subagents list활성 서브 에이전트 목록
/subagents kill <runId>특정 서브 에이전트 종료
/subagents log <runId>서브 에이전트 실행 로그 확인
/subagents spawn <task>수동으로 서브 에이전트 스폰

서브 에이전트 목록 확인

/subagents list

RunID      | Status   | Task              | Started
-----------|----------|-------------------|------------------
run-abc123 | running  | 웹 리서치          | 2026-04-01 09:15
run-def456 | complete | 데이터 분석         | 2026-04-01 09:10

중첩 (Nesting)

서브 에이전트는 자체적으로 다시 서브 에이전트를 스폰할 수 있다.

설정기본값설명
maxSpawnDepth2최대 중첩 깊이
최대 중첩 에이전트 수5중첩 체인 전체의 최대 수
주 에이전트 (depth 0)
  └─ 서브 에이전트 A (depth 1)
       └─ 서브 에이전트 A-1 (depth 2)  ← 최대 깊이
            └─ 스폰 불가 (depth 3)

동시성 제어

설정기본값설명
maxConcurrent8동시 실행 가능한 최대 서브 에이전트 수
{
  "agents": {
    "subagents": {
      "maxConcurrent": 8,
      "maxSpawnDepth": 2
    }
  }
}

동시 실행 수가 한계에 도달하면 새로운 스폰 요청은 대기열에 추가된다.

격리된 컨텍스트

서브 에이전트는 주 에이전트와 독립된 컨텍스트를 가진다.

  • 별도의 대화 히스토리
  • 독립적인 토큰 사용량 계산
  • 주 에이전트의 세션과 분리
  • 워크스페이스는 공유 (같은 파일 시스템 접근)

토큰 회계

서브 에이전트의 토큰 사용량은 독립적으로 집계된다.

주 에이전트: 10,000 토큰
  서브 에이전트 #1: 3,000 토큰
  서브 에이전트 #2: 5,000 토큰
──────────────────────────────
총 사용량: 18,000 토큰

비용 관리를 위해 서브 에이전트의 최대 토큰을 제한할 수 있다.

{
  "agents": {
    "subagents": {
      "maxTokensPerRun": 50000
    }
  }
}

결과 보고

서브 에이전트가 작업을 완료하면 요약을 요청자 채널에 포스팅한다.

  • DM에서 스폰된 경우 → 해당 DM에 요약 전송
  • 그룹에서 스폰된 경우 → 해당 그룹에 요약 전송
  • 크론에서 스폰된 경우 → 설정된 알림 채널에 전송