​

서브 에이전트

​

슬래시 명령어

• /subagents list
• /subagents kill <id|#|all>
• /subagents log <id|#> [limit] [tools]
• /subagents info <id|#>
• /subagents send <id|#> <message>

• 메인 실행을 차단하지 않고 “리서치 / 장기 작업 / 느린 도구” 작업을 병렬화
• 기본적으로 서브 에이전트를 격리 유지 (세션 분리 + 선택적 샌드박싱)
• 도구 오남용 방지: 서브 에이전트는 기본적으로 세션 도구를 받지 않음
• 오케스트레이터 패턴을 위한 중첩 깊이 설정 지원

​

도구

• 서브 에이전트 실행 시작 (deliver: false, 글로벌 레인: subagent)
• 이후 announce 단계를 실행하고 announce 응답을 요청자 채팅 채널에 게시
• 기본 모델: 호출자를 상속 (agents.defaults.subagents.model 또는 agents.list[].subagents.model 설정 시 해당 값 사용); 명시적 sessions_spawn.model이 항상 우선
• 기본 thinking: 호출자를 상속 (agents.defaults.subagents.thinking 또는 agents.list[].subagents.thinking 설정 시 해당 값 사용); 명시적 sessions_spawn.thinking이 항상 우선

• task (필수)
• label? (선택)
• agentId? (선택; 허용된 경우 다른 에이전트 id 하위에서 생성)
• model? (선택; 서브 에이전트 모델 재정의; 유효하지 않은 값은 건너뛰며 기본 모델로 실행되고 도구 결과에 경고 표시)
• thinking? (선택; 서브 에이전트 실행의 thinking 수준 재정의)
• runTimeoutSeconds? (기본값 0; 설정 시 N초 후 서브 에이전트 실행 중단)
• cleanup? (delete|keep, 기본값 keep)

• agents.list[].subagents.allowAgents: agentId로 지정 가능한 에이전트 id 목록 (["*"]는 모든 에이전트 허용). 기본값: 요청자 에이전트만 허용.

• agents_list를 사용하여 현재 sessions_spawn에 허용된 에이전트 id 확인.

• 서브 에이전트 세션은 agents.defaults.subagents.archiveAfterMinutes 이후 자동 아카이브됩니다 (기본값: 60).
• 아카이브는 sessions.delete를 사용하며 트랜스크립트 파일을 *.deleted.<timestamp>로 이름 변경합니다 (같은 폴더).
• cleanup: "delete"는 announce 직후 즉시 아카이브합니다 (트랜스크립트는 이름 변경으로 유지).
• 자동 아카이브는 best-effort 방식이며, 게이트웨이 재시작 시 대기 중 타이머는 유실됩니다.
• runTimeoutSeconds는 자동 아카이브를 수행하지 않고 실행만 중단합니다. 세션은 자동 아카이브까지 유지됩니다.
• 자동 아카이브는 depth-1 및 depth-2 세션에 동일하게 적용됩니다.

​

중첩 서브 에이전트

​

활성화 방법

{
  agents: {
    defaults: {
      subagents: {
        maxSpawnDepth: 2, // 서브 에이전트가 자식 생성 허용 (기본값: 1)
        maxChildrenPerAgent: 5, // 에이전트 세션당 최대 활성 자식 수 (기본값: 5)
        maxConcurrent: 8, // 글로벌 동시 실행 레인 제한 (기본값: 8)
      },
    },
  },
}

​

깊이 레벨

​

Announce 체인

1. Depth-2 워커 완료 → 부모(depth-1 오케스트레이터)에게 announce
2. Depth-1 오케스트레이터가 announce 수신 후 결과 종합 → 완료 → 메인에 announce
3. 메인 에이전트가 announce 수신 후 사용자에게 전달

​

깊이별 도구 정책

• Depth 1 (오케스트레이터, maxSpawnDepth >= 2일 때): 자식 관리를 위해 sessions_spawn, subagents, sessions_list, sessions_history 사용 가능. 기타 세션/시스템 도구는 여전히 거부됨.
• Depth 1 (리프, maxSpawnDepth == 1일 때): 세션 도구 없음 (현재 기본 동작).
• Depth 2 (리프 워커): 세션 도구 없음 — depth 2에서는 sessions_spawn이 항상 거부됨. 추가 자식 생성 불가.

​

에이전트별 생성 제한

​

연쇄 중지 (Cascade stop)

• 메인 채팅에서 /stop → 모든 depth-1 에이전트 중지 및 해당 depth-2 자식까지 연쇄 중지
• /subagents kill <id> → 특정 서브 에이전트 및 해당 자식 중지
• /subagents kill all → 요청자의 모든 서브 에이전트 및 자식 중지

​

인증

• 서브 에이전트 세션 키: agent:<agentId>:subagent:<uuid>
• 인증 스토어는 해당 에이전트의 agentDir에서 로드
• 메인 에이전트의 인증 프로필은 폴백으로 병합되며, 충돌 시 에이전트 프로필이 우선

​

Announce

• announce 단계는 요청자 세션이 아닌 서브 에이전트 세션 내부에서 실행됩니다.
• 서브 에이전트가 정확히 ANNOUNCE_SKIP을 반환하면 아무것도 게시되지 않습니다.
• 그렇지 않으면 announce 응답은 후속 agent 호출(deliver=true)을 통해 요청자 채팅 채널에 게시됩니다.
• 가능한 경우 스레드/토픽 라우팅을 유지합니다 (Slack threads, Telegram topics, Matrix threads).
• announce 메시지는 안정적인 템플릿으로 정규화됩니다:
  • Status: 실행 결과(success, error, timeout, unknown) 기반
  • Result: announce 단계의 요약 내용 (없으면 (not available))
  • Notes: 오류 세부 정보 및 기타 유용한 컨텍스트
• Status는 모델 출력이 아니라 런타임 결과 신호에서 파생됩니다.

• Runtime (예: runtime 5m12s)
• Token usage (input/output/total)
• 모델 가격이 설정된 경우 예상 비용 (models.providers.*.models[].cost)
• sessionKey, sessionId, 트랜스크립트 경로 (메인 에이전트가 sessions_history로 조회하거나 파일을 직접 확인 가능)

​

도구 정책 (서브 에이전트 도구)

• sessions_list
• sessions_history
• sessions_send
• sessions_spawn

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1,
      },
    },
  },
  tools: {
    subagents: {
      tools: {
        // deny가 항상 우선
        deny: ["gateway", "cron"],
        // allow가 설정되면 allow-only 모드 (deny가 여전히 우선)
        // allow: ["read", "exec", "process"]
      },
    },
  },
}

​

동시성

• 레인 이름: subagent
• 동시 실행 수: agents.defaults.subagents.maxConcurrent (기본값 8)

​

중지

• 요청자 채팅에서 /stop을 보내면 요청자 세션이 중단되고, 해당 세션에서 생성된 모든 활성 서브 에이전트 실행이 중첩 자식까지 연쇄 중지됩니다.
• /subagents kill <id>는 특정 서브 에이전트를 중지하고 해당 자식까지 연쇄 중지합니다.

​

제한 사항

• 서브 에이전트 announce는 best-effort입니다. 게이트웨이가 재시작되면 대기 중인 “announce back” 작업은 유실됩니다.
• 서브 에이전트는 동일한 게이트웨이 프로세스 리소스를 공유합니다; maxConcurrent를 안전 장치로 사용하세요.
• sessions_spawn은 항상 non-blocking입니다: 즉시 { status: "accepted", runId, childSessionKey }를 반환합니다.
• 서브 에이전트 컨텍스트에는 AGENTS.md + TOOLS.md만 주입됩니다 (SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md는 포함되지 않음).
• 최대 중첩 깊이는 5입니다 (maxSpawnDepth 범위: 1–5). 대부분의 사용 사례에는 depth 2가 권장됩니다.
• maxChildrenPerAgent는 세션당 활성 자식 수를 제한합니다 (기본값: 5, 범위: 1–20).