BroadRouter
시작하기

서브에이전트(subagent)

업데이트

서브에이전트(subagent)는 메인 에이전트가 집중된 작업 하나를 처리하려고 시작하는 별도의 에이전트입니다. 자체 컨텍스트 윈도우, 시스템 프롬프트, 도구 접근 권한으로 작업을 수행하고, 결과나 요약만 메인 에이전트에 돌려주므로 메인 대화가 작게 유지됩니다.

다른 이름: 서브 에이전트, 하위 에이전트, 자식 에이전트, Claude Code 서브에이전트, subagent, sub-agent, child agent

서브에이전트는 에이전트를 위한 위임입니다. 일 하나를 새 작업자에게 맡기고 답만 돌려받습니다.

작동 방식

메인 에이전트는 “이 함수를 호출하는 곳을 모두 찾아라”나 “테스트 스위트를 실행하고 실패를 보고하라”처럼 독립적인 작업이라고 판단하면, 작업 설명과 함께 서브에이전트를 시작합니다. 서브에이전트는 자체 에이전트 루프를 돌린 뒤 결과를 돌려줍니다.

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로 코딩 에이전트 병렬 실행하기에서 세션 수를 자세히 다룹니다.

자주 묻는 질문

서브에이전트를 쓰면 토큰이 절약되나요?

메인 대화의 컨텍스트는 절약되지만 전체 토큰은 아닙니다. 서브에이전트의 요청도 토큰을 씁니다. Claude Code 문서는 서브에이전트 요청도 사용량에 포함된다고 밝히며, 간단한 서브에이전트 작업에는 더 작은 모델을 쓰라고 제안합니다.

서브에이전트가 또 서브에이전트를 시작할 수 있나요?

도구에 따라 다릅니다. Claude Code 문서에 따르면 서브에이전트는 기본적으로 자체 서브에이전트를 메인 대화 아래 최대 세 단계까지 띄울 수 있으며, 이를 제한할 수도 있습니다.

서브에이전트와 핸드오프는 무엇이 다른가요?

서브에이전트는 작업을 수행한 뒤 자신을 호출한 에이전트에 결과를 보고합니다. OpenAI Agents SDK의 핸드오프는 한 에이전트가 다른 에이전트에 작업을 위임하게 하며, handoff() 헬퍼가 제어권을 그 에이전트로 넘깁니다.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기