부모 에이전트가 delegate_task를 호출하면 core/agent/sub_agent.py의 SubAgentManager가 격리된 서브에이전트를 띄웁니다. 실행은 core/orchestration/isolated_execution.py의 IsolatedRunner가 맡고, 작업 간 의존성은 TaskGraph (core/orchestration/task_system.py)가 추적합니다. 스폰과 종료마다 SUBAGENT_STARTED / SUBAGENT_COMPLETED / SUBAGENT_FAILED 훅이 발화하고, 부모 세션 키가 있으면 Spawn+Announce로 진행 상황을 알립니다.
한도
| 노브 | 기본값 | 비고 |
|---|---|---|
max_depth | 1 | 서브에이전트는 다시 서브에이전트를 띄울 수 없습니다. 깊이 가드가 오류 결과를 반환합니다 |
max_total_subagents | 15 | 세션당 상한 (core/config/_settings.py) |
timeout_s | 600초 | GEODE_SUBAGENT_TIMEOUT_S env로 조절, [10, 3600]으로 clamp |
time_budget_s | 0 (꺼짐) | 선택적 wall-clock 예산 |
denied_tools / working_dirs | 비어 있음 | 도구 차단 목록과 샌드박스 작업 디렉터리 추가 |
레인: 동시성의 단위
모든 실행 경로는 core/orchestration/lane_queue.py의 레인을 통과합니다. SessionLane이 같은 세션 키를 직렬화하고(다른 키는 병렬), 그 다음 글로벌 레인이 전체 동시성을 잡습니다.
| 레인 | 동시성 | 비고 |
|---|---|---|
global | max_concurrent=50 | 프로덕션 기본값 (core/wiring/container.py) |
gateway | 설정값 | 메신저 인바운드 |
claude-cli-subagent / codex-cli-subagent | 레인별 설정 | CLI 구독 레인 보호 |
seed-generation | 레인별 설정 | 시드 파이프라인 |
SessionLane은 세션 키 256개까지 유지하고 유휴 키를 정리합니다.
격리의 실제 경계
격리는 프로세스와 산출물 수준에서 일어납니다. 서브에이전트는 별도 워커 프로세스로 돌고, 산출물은 <run_dir>/sub_agents/<task_id>/ 아래에 쌓이며, 부모는 반환된 요약만 받습니다 (core/orchestration/isolated_execution.py).
메모리 쓰기 격리는 별도 버퍼가 아니라 툴킷 구성으로 통제합니다. 기본 _default 툴킷은 읽기 전용이라 서브에이전트는 공유 메모리에 쓸 수 없습니다. 단, memory_save가 포함된 툴킷(예: general_purpose)을 명시하면 공유 ProjectMemory에 직접 기록됩니다. 동시 쓰기를 피하려면 쓰기 도구가 없는 툴킷을 주는 것이 통제 수단입니다.
도구와 능력의 상속
서브에이전트가 받는 것은 선언된 툴킷으로 해석된 네이티브 도구 핸들러입니다. frontmatter의 toolkit: 이름이 먼저, 레거시 tools: 목록이 다음, 둘 다 없으면 읽기 전용 _default입니다. 부모의 MCP 연결과 스킬 레지스트리는 워커 프로세스로 전달되지 않습니다 (core/agent/worker.py는 네이티브 핸들러만 구성). 자세한 해석 규칙은 도구와 툴셋을 참고합니다.
결과와 오류 분류
SubAgentResult.status는 ok / error / timeout / partial 중 하나입니다. 사용량 롤업(prompt_tokens, completion_tokens, usd_spent)이 결과에 실리며, 구독이나 CLI 레인으로 라우팅된 호출은 0으로 기록됩니다.
실패 모드
| 증상 | 원인 | 해법 |
|---|---|---|
| 서브에이전트가 또 위임하려다 실패 | max_depth=1 가드 | 의도된 동작입니다. 위임 구조를 부모에서 평탄화합니다 |
| 10분쯤에서 timeout 상태로 종료 | 기본 timeout_s=600 | GEODE_SUBAGENT_TIMEOUT_S를 올립니다 (상한 3600) |
| 서브에이전트의 메모와 기록이 부모에 안 보임 | 요약만 병합하는 격리 규칙 | 남겨야 할 내용은 서브에이전트의 최종 요약에 포함시킵니다 |
다음
- 도구와 툴셋. 툴킷 매니페스트와 해석 순서.
- 안쪽 agentic 루프. 위임을 시작하는 쪽.
- serve와 게이트웨이. 레인이 보호하는 데몬.