서브에이전트, 컨텍스트를 나누는 단위
Claude Agent SDK의 서브에이전트는 매번 빈 컨텍스트에서 시작해 자신이 호출한 중간 툴콜과 결과를 자기 세션 안에만 남기고, 부모에게는 최종 메시지 하나만 돌려줍니다. 예를 들어 코드베이스 수십 개 파일을 뒤지는 리서치 서브에이전트를 붙여도, 부모 대화창에는 요약 한 단락만 쌓입니다. 툴 접근도 같은 원리로 좁힐 수 있어, 문서만 검토하는 서브에이전트에는 Read·Grep·Glob만 남기고 Edit·Bash를 아예 세션에서 빼면 됩니다.
턴 단위 위임에서 스크립트 오케스트레이션으로
서브에이전트는 Claude가 매 턴 얼마나 부를지 스스로 판단하는 방식이라 한 턴에 위임하는 몇 개 작업에는 잘 맞지만, 수십에서 수백 개 에이전트를 조율하는 일에는 부족합니다. 이 규모에서는 오케스트레이션 자체를 스크립트로 옮겨 별도 런타임이 실행하게 하는 동적 워크플로우가 필요합니다. 중간 결과는 대화 컨텍스트가 아니라 스크립트 변수에 머무르므로, 부모 세션은 최종 결과만 받습니다.
구축 로드맵과 함정: 서브에이전트 워크플로우 예산·재개 설계
목표 수치부터 코드보다 먼저 선언합니다. 워크플로우 런타임은 동시 실행 16개, 런당 총 1,000개 에이전트가 하드 상한이고, 예상 25개 이상 또는 토큰 150만 개를 넘기면 진행 화면에 대형 워크플로우 경고가 뜹니다. 여기에 맞춰 크기 가이드라인을 small(5개 미만)·medium(15개 미만)·large(50개 미만) 중 작업 범위에 맞게 고르고, USD 예산 상한을 쿼리 옵션으로 코드에 박아 둡니다.
턴 단위 서브에이전트는 별도 상한 체계를 씁니다. 하위 서브에이전트가 다시 서브에이전트를 부르는 깊이는 기본 3계층이고, 동시 실행 서브에이전트는 기본 20개까지입니다. 워크플로우의 16·1,000과 이 두 값을 같은 숫자로 혼동하면 운영 대시보드의 상한 경보가 엉뚱한 임계값을 가리키게 됩니다.
재개 규칙이 가장 잘 놓치는 실패 지점입니다. 실행 중이던 워크플로우를 멈췄다 다시 돌리면 이미 끝난 에이전트도 실행 시작 순서 기준으로 재생되는데, 멈춘 시점에 아직 안 끝난 에이전트보다 늦게 시작한 에이전트는 그새 완료했더라도 처음부터 다시 돕니다. 그래서 하나의 긴 에이전트보다 여러 개로 넓게 팬아웃한 워크플로우가 재개 시 더 많은 진행분을 그대로 보존합니다.
동시성 상한에 걸리면 세션이 죽지 않고 "Concurrent subagent limit reached"라는 tool_result 한 줄로 돌아오므로, 이를 오류가 아니라 백오프 신호로 처리해야 합니다. 예산 상한은 신규 스폰 거부·실행 중이던 백그라운드 서브에이전트 강제 종료·error_max_budget_usd 결과로 쿼리 종료 세 갈래로 동시에 작동하므로, 이 서브타입을 다른 실패와 구분해 별도 코드 경로로 받아야 합니다. 레이트리밋 같은 API 오류로 서브에이전트가 중간에 끊기면 그 결과는 아예 반환되지 않으니, 정상 종료와 오류 종료를 하나의 null 체크로 뭉뚱그리면 안 됩니다.
운영 체크리스트에는 최소 권한 툴 스코프를 넣습니다. tools 필드를 비우면 서브에이전트가 쓸 수 있는 모든 툴을 그대로 물려받으므로, 읽기 전용 리뷰어에도 Edit·Bash가 남아 있을 수 있습니다. 배포 전 시나리오 테스트에는 동시성 상한 강제 도달, 예산 상한 강제 소진, 병렬 호출 중 하나만 API 오류 세 가지를 반드시 포함합니다. v2.1.210부터는 부모가 서브에이전트의 최종 메시지를 받기 전에 제어 태그 모사·권한 설정 언급·턴 마커 패턴을 스캔해 하네스 전용 태그를 무력화하고 [harness: ...] 마커를 남기므로, 이 마커 발생 여부를 로그 필드에 남겨 두면 외부 페이지를 읽은 서브에이전트가 프롬프트 인젝션을 실어 돌아오는 사고를 세션 단위로 추적할 수 있습니다.
매주 워크플로우 진행 화면의 에이전트 수·토큰 총량을 집계해, 대형 워크플로우 경고가 반복되는 작업은 크기 가이드라인을 좁히거나 단계를 쪼갭니다. 정지 후 재개가 발생한 런에서는 재실행된 에이전트 비율을 남겨, 비용이 낮은 에이전트를 팬아웃 앞쪽에 배치하는 근거로 씁니다. 조직의 모델 허용 목록이 요청한 모델을 막아 다른 모델로 자동 치환되는 경우도 있으므로, 이 치환 경고를 주간 비용 검토 항목에 넣어 둡니다.
한눈에 보는 적용 포인트
서브에이전트 워크플로우 운영의 핵심은 동시 16개·총 1,000개라는 하드 상한과 크기 가이드라인·USD 예산을 코드로 먼저 고정하고, 정지-재개 시 늦게 시작한 완료 에이전트까지 재실행된다는 재생 규칙을 팬아웃 순서 설계에 반영하며, 동시성 상한 응답과 예산 상한 종료 서브타입을 서로 다른 코드 경로로 처리하는 데 있습니다. 여기에 서브에이전트 출력 스캐닝 로그까지 갖추면 대형 팬아웃도 예산과 보안 두 축에서 동시에 통제할 수 있습니다.
참고 링크
Subagents in the SDK — Claude Docs
Orchestrate subagents at scale with dynamic workflows — Claude Docs