서브에이전트는 에이전트를 위한 위임입니다. 일 하나를 새 작업자에게 맡기고 답만 돌려받습니다.
작동 방식
메인 에이전트는 “이 함수를 호출하는 곳을 모두 찾아라”나 “테스트 스위트를 실행하고 실패를 보고하라”처럼 독립적인 작업이라고 판단하면, 작업 설명과 함께 서브에이전트를 시작합니다. 서브에이전트는 자체 에이전트 루프를 돌린 뒤 결과를 돌려줍니다.
Claude Code 문서는 이렇게 설명합니다. “Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.”(번역: 각 서브에이전트는 맞춤 시스템 프롬프트, 지정된 도구 접근 권한, 독립적인 권한을 갖고 자체 컨텍스트 윈도우에서 실행됩니다) 서브에이전트는 YAML 프런트매터가 있는 Markdown 파일로 정의하며, 프로젝트 단위라면 .claude/agents/에 둡니다.
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.
문서가 꼽는 장점은 탐색 과정을 메인 대화 밖에 두는 것, 서브에이전트가 쓸 수 있는 도구를 제한하는 것, 작업을 더 저렴한 모델로 보내는 것입니다.
다른 프레임워크에도 비슷한 개념이 있습니다. OpenAI Agents SDK는 “Handoffs allow an agent to delegate tasks to another agent,“(번역: 핸드오프는 에이전트가 다른 에이전트에게 작업을 위임할 수 있게 합니다)라고 설명하며, 각 핸드오프를 모델에 도구로 표현합니다.
Anthropic의 컨텍스트 엔지니어링 글은 이 패턴을 컨텍스트 관점에서 설명합니다. 각 서브에이전트는 깨끗한 컨텍스트 윈도우에서 일하고 “returns only a condensed, distilled summary of its work,“(번역: 작업을 압축하고 정제한 요약만 돌려줍니다), 흔히 1,000~2,000토큰 분량입니다.
왜 중요한가
- 컨텍스트. 테스트 실행 하나가 수만 토큰을 출력할 수 있습니다. 서브에이전트 안에서 실행하면 그 출력은 메인 컨텍스트 윈도우 밖에 머물고 요약만 돌아옵니다. 컨텍스트 엔지니어링의 핵심 도구입니다.
- 비용. 서브에이전트마다 자체 프롬프트와 도구를 불러오므로 전체 토큰은 대개 늘어납니다. 멀티 에이전트 비용 글에서 배수를 추정합니다.
- 병렬성. 동시에 실행되는 서브에이전트는 병렬 요청입니다. 한 번에 몇 개가 실행될지는 제공업체의 동시 처리 한도가 결정합니다.
BroadNet Inference에서는
BroadNet은 모델을 서빙하고, 서브에이전트 로직은 사용하는 에이전트 도구에 있습니다. OpenAI 호환 base URL을 받는 도구라면 메인 에이전트와 서브에이전트를 모두 BroadNet으로 향하게 할 수 있고, 각각 다른 모델을 쓸 수도 있습니다.
종량제에서는 키 하나당 동시 요청 4개가 허용됩니다. DeepSeek V4.1 Flash용 정액 플랜에서는 세션마다 한 번에 요청 하나만 처리하므로, 같은 순간에 동시에 진행될 수 있는 모델 요청 수를 세어 보세요. 서브에이전트 세 개가 동시에 돌면 세션 세 개가 필요하고, 그동안 오케스트레이터도 모델을 호출한다면 네 개가 필요합니다. 정액 API로 코딩 에이전트 병렬 실행하기에서 세션 수를 자세히 다룹니다.