Sub-agent

Sub-agent는 기존 에이전트 실행에서 생성된 백그라운드 에이전트 실행입니다. 자체 세션 (agent:<agentId>:subagent:<uuid>)에서 실행되며 완료되면 요청자 채팅 채널에 결과를 알립니다.

슬래시 명령

/subagents를 사용하여 현재 세션의 sub-agent 실행을 검사하거나 제어합니다:

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

/subagents info는 실행 메타데이터 (상태, 타임스탬프, 세션 ID, 트랜스크립트 경로, 정리)를 보여줍니다.

주요 목표:

  • 메인 실행을 차단하지 않고 "연구 / 긴 작업 / 느린 도구" 작업을 병렬화합니다.
  • 기본적으로 sub-agent를 격리된 상태로 유지합니다 (세션 분리 + 선택적 샌드박싱).
  • 도구 표면을 오용하기 어렵게 유지합니다: sub-agent는 기본적으로 세션 도구를 얻지 못합니다.
  • 중첩된 팬아웃 방지: sub-agent는 sub-agent를 생성할 수 없습니다.

비용 참고: 각 sub-agent는 자체 컨텍스트 및 토큰 사용량을 가집니다. 무겁거나 반복적인 작업의 경우 sub-agent에 더 저렴한 모델을 설정하고 메인 에이전트는 더 높은 품질의 모델을 유지하세요. agents.defaults.subagents.model 또는 에이전트별 재정의를 통해 구성할 수 있습니다.

도구

sessions_spawn 사용:

  • Sub-agent 실행을 시작합니다 (deliver: false, 전역 레인: subagent)
  • 그런 다음 알림 단계를 실행하고 알림 응답을 요청자 채팅 채널에 게시합니다
  • 기본 모델: agents.defaults.subagents.model (또는 에이전트별 agents.list[].subagents.model)을 설정하지 않는 한 호출자에서 상속합니다; 명시적인 sessions_spawn.model이 여전히 우선합니다.

도구 매개변수:

  • task (필수)
  • label? (선택사항)
  • agentId? (선택사항; 허용되는 경우 다른 에이전트 ID 아래에서 생성)
  • model? (선택사항; sub-agent 모델 재정의; 유효하지 않은 값은 건너뛰고 sub-agent는 도구 결과에 경고와 함께 기본 모델에서 실행됩니다)
  • thinking? (선택사항; sub-agent 실행에 대한 thinking 수준 재정의)
  • runTimeoutSeconds? (기본값 0; 설정 시 N초 후 sub-agent 실행이 중단됩니다)
  • cleanup? (delete|keep, 기본값 keep)

허용 목록:

  • agents.list[].subagents.allowAgents: agentId를 통해 대상이 될 수 있는 에이전트 ID 목록 (모든 것을 허용하려면 ["*"]). 기본값: 요청자 에이전트만.

검색:

  • agents_list를 사용하여 현재 sessions_spawn에 허용되는 에이전트 ID를 확인합니다.

자동 아카이브:

  • Sub-agent 세션은 agents.defaults.subagents.archiveAfterMinutes (기본값: 60) 후 자동으로 아카이브됩니다.
  • 아카이브는 sessions.delete를 사용하고 트랜스크립트를 *.deleted.<timestamp> (같은 폴더)로 이름을 바꿉니다.
  • cleanup: "delete"는 알림 직후 즉시 아카이브합니다 (이름 변경을 통해 트랜스크립트는 여전히 유지합니다).
  • 자동 아카이브는 최선을 다합니다; 게이트웨이가 다시 시작되면 대기 중인 타이머가 손실됩니다.
  • runTimeoutSeconds는 자동 아카이브하지 않습니다; 실행만 중지합니다. 세션은 자동 아카이브까지 남아 있습니다.

인증

Sub-agent 인증은 세션 유형이 아닌 에이전트 ID로 해결됩니다:

  • Sub-agent 세션 키는 agent:<agentId>:subagent:<uuid>입니다.
  • 인증 저장소는 해당 에이전트의 agentDir에서 로드됩니다.
  • 메인 에이전트의 인증 프로필은 폴백으로 병합됩니다; 충돌 시 에이전트 프로필이 메인 프로필을 재정의합니다.

참고: 병합은 추가적이므로 메인 프로필은 항상 폴백으로 사용 가능합니다. 에이전트별로 완전히 격리된 인증은 아직 지원되지 않습니다.

알림

Sub-agent는 알림 단계를 통해 보고합니다:

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

알림 페이로드에는 마지막에 통계 줄이 포함됩니다 (래핑된 경우에도):

  • 런타임 (예: runtime 5m12s)
  • 토큰 사용량 (입력/출력/합계)
  • 모델 가격이 구성된 경우 예상 비용 (models.providers.*.models[].cost)
  • sessionKey, sessionId 및 트랜스크립트 경로 (메인 에이전트가 sessions_history를 통해 히스토리를 가져오거나 디스크의 파일을 검사할 수 있도록)

도구 정책 (sub-agent 도구)

기본적으로 sub-agent는 세션 도구를 제외한 모든 도구를 얻습니다:

  • sessions_list
  • sessions_history
  • sessions_send
  • sessions_spawn

구성을 통해 재정의:

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1
      }
    }
  },
  tools: {
    subagents: {
      tools: {
        // deny가 우선
        deny: ["gateway", "cron"],
        // allow가 설정되면 allow 전용이 됩니다 (deny는 여전히 우선)
        // allow: ["read", "exec", "process"]
      }
    }
  }
}

동시성

Sub-agent는 전용 인프로세스 큐 레인을 사용합니다:

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

중지

  • 요청자 채팅에서 /stop을 보내면 요청자 세션이 중단되고 그로부터 생성된 활성 sub-agent 실행이 중지됩니다.

제한 사항

  • Sub-agent 알림은 최선을 다합니다. 게이트웨이가 다시 시작되면 대기 중인 "알림" 작업이 손실됩니다.
  • Sub-agent는 여전히 동일한 게이트웨이 프로세스 리소스를 공유합니다; maxConcurrent를 안전 밸브로 취급하세요.
  • sessions_spawn은 항상 논블로킹입니다: { status: "accepted", runId, childSessionKey }를 즉시 반환합니다.
  • Sub-agent 컨텍스트는 AGENTS.md + TOOLS.md만 주입합니다 (SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md 또는 BOOTSTRAP.md 없음).
← 문서로 돌아가기