Gemini CLI 서브에이전트 — YAML로 정의하고 병렬로 위임하는 오케스트레이터 패턴

메인 에이전트가 오케스트레이터가 됐다

2026년 4월 Google이 Gemini CLI v0.38.1에 서브에이전트 기능을 추가했다. 이제 단일 터미널 세션에서 메인 에이전트가 복잡한 태스크를 분해하여 전문화된 서브에이전트에 병렬로 위임한다. 각 서브에이전트는 Markdown 파일의 YAML 프론트매터로 정의되며, 독립된 컨텍스트 윈도우와 도구 세트를 가지고 격리된 환경에서 실행된다. 서브에이전트의 전체 실행 결과는 단일 응답으로 메인 에이전트에 통합된다.

Google Developers Blog는 "Subagents have arrived in Gemini CLI"라는 제목으로 이를 공식 발표했고, InfoQ는 "태스크 위임과 병렬 에이전트 워크플로우를 가능하게 하는 기능"으로 평가했다. 핵심 가치 제안은 두 가지다. 첫째는 컨텍스트 오염 방지다 — 서브에이전트가 독립된 컨텍스트에서 실행되므로 서브태스크의 상세 내용이 메인 에이전트의 컨텍스트 윈도우를 채우지 않는다. 둘째는 병렬 실행을 통한 속도 향상이다 — 다섯 가지 주제를 동시에 조사하거나 여러 컴포넌트를 동시에 리팩터링할 수 있다.

오케스트레이터와 전문 실행자의 역할 분리

메인 에이전트는 전략적 오케스트레이터 역할을 한다. 사용자로부터 광범위하거나 복잡한 태스크를 받아 분해하고, 가장 적합한 서브에이전트를 선택하고, 병렬 또는 순차적으로 위임한다. 서브에이전트는 전문 실행자다 — 정해진 능력 범위 내에서 위임받은 태스크를 독립적으로 완료하고 결과를 메인 에이전트에 반환한다.

⤢✕

각 서브에이전트는 독립된 실행 루프에서 동작한다. 서브에이전트의 대화 히스토리는 메인 에이전트의 컨텍스트에 직접 누적되지 않고, 전체 실행이 단일 응답으로 통합되어 메인 에이전트에 반환된다. 이 설계는 메인 컨텍스트 윈도우가 서브태스크 세부 사항으로 가득 차는 "컨텍스트 부패(context rot)"를 방지하고 이후 상호작용을 빠르고 비용 효율적으로 유지한다. 도구 접근도 격리된다 — 서브에이전트 A가 파일 쓰기 도구를 가져도 서브에이전트 B는 읽기 도구만 가질 수 있고, MCP 서버도 서브에이전트별로 독립 설정된다.

YAML 프론트매터로 에이전트를 선언한다

커스텀 서브에이전트는 Markdown 파일(.md)로 정의된다. YAML 프론트매터가 메타데이터와 능력을 선언하고, 프론트매터 이하의 Markdown 본문이 서브에이전트의 시스템 프롬프트가 된다. 저장 위치는 두 가지다 — 팀과 공유되며 레포지토리에 버전 관리되는 프로젝트 레벨(.gemini/agents/*.md), 개인 전용이며 모든 프로젝트에서 재사용되는 사용자 레벨(~/.gemini/agents/*.md). @에이전트명 구문으로 호출한다 — 메인 에이전트 세션에서 @security-reviewer 이 PR의 보안 취약점을 분석해줘처럼 사용한다.

---
name: agent-name          # 필수: @호출에 사용되는 식별자
description: >            # 필수: 에이전트의 역할과 전문성 설명
  이 에이전트가 무엇을 하는지,
  언제 사용해야 하는지 설명.
tools:                    # 선택: 허용된 도구 목록 (미지정 시 기본 도구 상속)
  - read_file
  - write_file
  - run_shell_command
mcpServers:               # 선택: 이 에이전트 전용 MCP 서버
  - name: github-mcp
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
---
여기부터 시스템 프롬프트.
에이전트의 행동 방식, 출력 형식, 제약 조건을 상세히 기술한다.

Gemini CLI는 에이전트 파일 로드 시 YAML 스키마를 검증한다. name이 중복되면 경고를 출력하고, 지정된 도구가 지원되지 않으면 에러를 발생시킨다. 에이전트 파일은 일반 텍스트이므로 Git으로 버전 관리하며, 정의 변경 시 일반 코드 변경과 동일하게 PR 리뷰를 거친다.

보안 리뷰 에이전트와 테스트 작성 에이전트의 실전 정의 예시는 다음과 같다.

---
name: security-reviewer
description: >
  코드의 보안 취약점을 분석하는 전문 에이전트.
  OWASP Top 10, 인젝션 취약점, 인증 결함, 민감 데이터 노출을 중점 검토.
  코드 리뷰나 PR 분석 요청 시 사용.
tools:
  - read_file
  - list_directory
---
당신은 시니어 보안 엔지니어입니다.
주어진 코드에서 보안 취약점을 식별하고 심각도(Critical/High/Medium/Low)와
함께 구체적인 수정 방법을 제안하십시오.
OWASP Top 10 기준으로 분류하고, CWE ID를 포함하십시오.

---
name: test-writer
description: >
  주어진 코드에 대한 단위 테스트와 통합 테스트를 작성하는 에이전트.
  프레임워크는 코드베이스의 기존 테스트 패턴을 따름.
  새 기능 구현 후 테스트 생성 요청 시 사용.
tools:
  - read_file
  - write_file
  - run_shell_command
---
당신은 테스트 전문 엔지니어입니다.
코드베이스의 기존 테스트 파일을 먼저 탐색하여 사용 중인 프레임워크,
네이밍 컨벤션, 디렉토리 구조를 파악한 후 일관성 있는 테스트를 작성하십시오.
엣지 케이스와 에러 케이스를 반드시 포함하십시오.

태스크를 쪼개고 결과를 모으는 방식

⤢✕

메인 에이전트가 어떤 서브에이전트에 위임할지 결정하는 라우팅 로직은 각 에이전트의 description 필드를 기반으로 한다. Gemini CLI는 태스크의 의미와 에이전트 description의 의미적 유사도를 분석해 최적 에이전트를 선택하며, 개발자가 @에이전트명을 명시적으로 지정하면 라우팅을 직접 제어할 수 있다. 태스크 분해 전략은 두 가지다 — 선행 에이전트의 출력이 다음 에이전트의 입력이 되는 파이프라인 구조인 직렬 분해(보안 취약점 분석 → 취약점 목록 기반 테스트 작성 → 수정 코드로 문서 업데이트)와, 독립적인 태스크를 동시에 실행하는 병렬 분해(5개 언어 번역, 3개 마이크로서비스 리팩터링, 10개 이슈 트리아지를 동시 수행)다.

병렬로 실행된 서브에이전트의 결과는 메인 에이전트가 집계한다. 두 에이전트가 같은 파일을 다르게 수정하는 등 출력이 충돌하는 경우, 메인 에이전트가 충돌을 탐지하고 사용자에게 중재를 요청한다. 에러 격리도 이 아키텍처의 중요한 장점이다 — 서브에이전트 A가 실패해도 B와 C는 계속 실행되며, 메인 에이전트는 실패한 서브에이전트의 에러를 수집하고 성공한 에이전트의 결과와 함께 사용자에게 보고한다. 전체 파이프라인이 단일 오류로 중단되지 않는다.

도구와 MCP 서버를 개별적으로 잠그기

서브에이전트의 도구 접근은 YAML의 tools 목록으로 명시적으로 제어된다. 지정하지 않으면 기본 도구 세트를 상속하지만, 최소 권한 원칙을 위해 각 에이전트에 필요한 도구만 명시하는 것이 권장된다.

⤢✕

MCP 서버도 서브에이전트별로 격리 설정이 가능하다. GitHub MCP는 PR 분석 에이전트에만, PostgreSQL MCP는 데이터베이스 에이전트에만 연결한다. 불필요한 MCP 서버 접근을 차단하면 에이전트가 오용되거나 의도치 않은 사이드 이펙트를 일으킬 가능성이 줄어든다.

팀 단위로 공유하고 버전 관리하기

.gemini/agents/ 디렉토리를 레포지토리에 포함시키면 팀 전체가 동일한 에이전트 정의를 공유한다. 에이전트 정의 변경은 일반 코드 변경과 동일하게 PR 리뷰 프로세스를 거치므로, 에이전트 행동의 일관성과 품질을 팀 레벨에서 관리할 수 있다. 권장 디렉토리 구조는 다음과 같다.

.gemini/
  agents/
    security-reviewer.md   # 보안 분석 전문 에이전트
    test-writer.md         # 테스트 생성 에이전트
    doc-generator.md       # 문서화 에이전트
    dependency-auditor.md  # 의존성 감사 에이전트
    i18n-translator.md     # 다국어 번역 에이전트

개인 에이전트(~/.gemini/agents/)는 개발자 개인의 작업 방식에 특화된 에이전트를 정의한다 — 특정 코딩 스타일 검토, 개인 노트 정리, 특정 프레임워크 전문가 에이전트 등을 개인 레벨에서 관리한다.

병렬화가 공짜는 아니다

병렬 실행은 속도를 높이지만 두 가지 리스크가 있다. 두 서브에이전트가 같은 파일을 다른 방향으로 수정하면 충돌하는 코드 변경이 발생하는데, 완화 전략은 파일 수준에서 작업 영역을 분리하거나 순차 의존성이 있는 태스크는 직렬로 실행하는 것이다. 병렬 실행은 동시에 여러 API 요청을 발생시켜 사용량 한도 초과 위험도 있다 — 각 서브에이전트가 독립된 컨텍스트 윈도우를 소비하므로 비용이 배수로 증가할 수 있다. 무분별한 병렬화 대신 실제로 독립적인 태스크에만 병렬 실행을 적용해야 한다.

Claude Code 서브에이전트와 비교하면

기준	Gemini CLI 서브에이전트	Claude Code 서브에이전트
정의 방식	YAML 프론트매터 + Markdown	CLAUDE.md 기반 컨텍스트
저장 위치	`.gemini/agents/*.md`	프로젝트 컨텍스트 내
병렬 실행	명시적 지원 (`@agent` 다중 호출)	태스크 레벨 병렬화
도구 격리	YAML `tools` 목록으로 명시	권한 레벨로 관리
MCP 격리	에이전트별 mcpServers 설정	전역 MCP 설정 공유
팀 공유	Git 기반 버전 관리	레포지토리 내 공유
호출 구문	`@에이전트명`	태스크 디스패치

YAML 프론트매터로 전문화된 에이전트를 선언적으로 정의하고, 독립된 컨텍스트와 도구 세트로 격리하며, 병렬 실행으로 복잡한 태스크를 가속화하는 패턴은 AI 에이전트 설계의 새로운 표준이 되어가고 있다. 태스크를 전문화된 에이전트에 위임하고 결과를 집계하는 오케스트레이터 패턴을 이해하고 적용하는 것이 2026년 AI 도구 활용의 핵심 역량이다.