Gemini CLI 서브에이전트: 허브-앤-스포크로 위임하고 Markdown+YAML로 정의하는 팀 전용 에이전트

2026년 4월, Google은 Gemini CLI에 서브에이전트(Subagent) 기능을 공식 출시하였다. 메인 에이전트가 코드 분석, 리서치, 테스트 같은 복잡한 서브태스크를 전문 에이전트에 위임하고 병렬로 실행하는 구조로, 개발자는 Markdown과 YAML 프론트매터만으로 팀 전용 커스텀 에이전트를 손쉽게 정의할 수 있다.

메인 에이전트가 허브가 되는 위임 구조

Gemini CLI의 서브에이전트 아키텍처는 허브-앤-스포크(Hub-and-Spoke) 모델을 채택한다. 메인 에이전트가 허브 역할을 하며 전체 태스크를 조율하고, 각 서브에이전트는 스포크로서 특정 도메인 작업에 집중한다.

⤢✕

메인 에이전트는 사용자 요청을 수신하면 먼저 태스크를 독립적인 서브태스크로 분해한다. 각 서브태스크가 어떤 전문 에이전트에 위임될지는 등록된 에이전트의 description 필드를 참조하여 결정된다. @에이전트명 구문을 사용하면 개발자가 명시적으로 에이전트를 지정할 수 있으며, 명시하지 않을 경우 메인 에이전트가 자동으로 최적의 에이전트를 선택한다. Google이 기본 제공하는 빌트인 서브에이전트는 일반적인 질의응답과 작업 처리를 담당하는 범용 보조 에이전트 general, 셸 명령어 실행과 시스템 조작에 특화된 커맨드라인 인터페이스 전문 에이전트 cli, 소스코드 검색·의존성 분석·구조 파악을 수행하는 코드베이스 탐색 에이전트 codebase 세 종류다.

서브에이전트는 메인 에이전트와 완전히 분리된 독립적인 컨텍스트 루프 안에서 실행된다. LocalAgentExecutor는 자체적인 ToolRegistry, PromptRegistry, ResourceRegistry를 인스턴스화하여 각 서브에이전트가 서로 다른 에이전트나 메인 컨텍스트에 영향을 주지 않도록 보장한다. 서브에이전트가 작업을 완료하면, 수십 번의 도구 호출과 파일 탐색을 거쳤더라도 그 내역은 모두 정리되고 간결한 요약 결과만 메인 에이전트에 반환된다. 이로 인해 메인 컨텍스트 윈도우가 중간 과정으로 채워지지 않아, 이후 상호작용이 빠르고 비용 효율적으로 유지된다.

Markdown 한 장으로 정의하는 전문 에이전트

Gemini CLI 서브에이전트의 가장 강력한 특징 중 하나는 Markdown 파일 하나로 커스텀 에이전트를 완전히 정의할 수 있다는 점이다. 복잡한 코드나 별도 설정 파일 없이, YAML 프론트매터와 마크다운 본문만으로 전문 에이전트를 선언적으로 명세한다.

커스텀 에이전트 파일은 .md 확장자를 가지며, 두 가지 경로 중 하나에 배치할 수 있다.

경로	적용 범위
`.gemini/agents/*.md`	프로젝트 레벨 (팀 공유용)
`~/.gemini/agents/*.md`	사용자 레벨 (개인 전역 에이전트)

프로젝트 디렉터리의 .gemini/agents/ 폴더에 파일을 두면 팀 전체가 동일한 커스텀 에이전트를 공유할 수 있어, Git 저장소에 커밋하여 버전 관리하는 것이 권장된다.

다음은 커스텀 서브에이전트 정의 파일의 전형적인 구조이다.

---
name: readme-architect
description: |
  Specialized in analyzing project structures and writing
  professional README.md files. Use when a comprehensive
  README is required for a repository.
tools:
  - read_file
  - glob
  - write_file
model: inherit
---
You are an expert Technical Writer with 10 years of experience.
Your goal is to analyze the files in the current directory,
understand the project's purpose, tech stack, and usage patterns,
then draft a professional README.md that includes:
- Project overview and motivation
- Installation instructions
- Usage examples with code snippets
- Contributing guidelines

YAML 프론트매터의 핵심 필드는 다음과 같다. name은 에이전트를 식별하는 고유 식별자로 @name 구문으로 명시적 호출 시 사용된다. description은 메인 에이전트가 이 에이전트를 언제 선택해야 하는지 기술하는 능력 선언문으로, 구체적이고 트리거 조건이 명확할수록 자동 선택 정확도가 높아진다. tools는 이 에이전트가 접근 가능한 도구 목록으로 최소 권한 원칙에 따라 필요한 도구만 명시한다. model은 사용할 모델 식별자로, inherit로 설정하면 메인 에이전트와 동일한 모델을 상속한다.

아래는 MCP 서버를 활용하는 리서치 전문 에이전트 예시이다.

---
name: web-researcher
description: |
  Performs deep web research on technical topics, collects
  information from multiple sources, and produces structured
  research summaries. Use for any fact-finding or competitive
  analysis tasks.
tools:
  - web_search
  - read_file
  - write_file
model: gemini-2.5-pro
---
You are a Research Specialist. When given a research topic:
(1) Break it into 3-5 sub-questions
(2) Search for authoritative sources for each sub-question
(3) Synthesize findings into a structured summary with citations
(4) Flag any conflicting information or knowledge gaps
Always prefer primary sources over secondary summaries.

YAML 프론트매터 이후의 마크다운 본문은 해당 서브에이전트의 시스템 프롬프트가 된다. 효과적인 시스템 프롬프트 작성을 위한 패턴은 에이전트의 전문 정체성을 1문장으로 선언하는 역할 명세(Role Definition), 이 에이전트가 달성해야 할 최종 산출물을 명확히 기술하는 목표 명세(Goal Statement), 번호 매긴 단계별 처리 과정을 제시해 일관된 실행을 유도하는 처리 절차(Process Steps), 반환 결과의 구조(JSON, Markdown, 요약문 등)를 지정하는 출력 형식(Output Format), 하지 말아야 할 행동이나 범위 이탈 방지 규칙을 명시하는 제약 조건(Constraints)이다.

서로 다른 컨텍스트에서 동시에 달리는 서브에이전트

⤢✕

병렬 실행의 핵심은 각 서브에이전트가 완전히 독립된 컨텍스트 윈도우에서 시작한다는 점이다. 서브에이전트는 메인 에이전트가 위임한 특정 태스크와 관련 지시사항만을 초기 컨텍스트로 수신하며, 메인 에이전트의 전체 대화 이력이나 다른 서브에이전트의 중간 상태에는 접근할 수 없다. 동일한 프로젝트의 서로 다른 모듈을 분석하거나, 서로 연관 없는 다섯 가지 주제를 동시에 조사해야 할 때, Gemini CLI는 여러 서브에이전트를 동시에 디스패치하여 총 소요 시간을 대폭 단축한다. @에이전트명 구문을 복수로 사용하면 메인 에이전트는 이를 독립 태스크로 인식하고 병렬 실행을 트리거한다.

격리 실행 구조는 에러 격리(Error Isolation) 면에서도 중요한 이점을 제공한다. 하나의 서브에이전트가 실패하더라도 다른 서브에이전트의 실행은 영향을 받지 않는다. 메인 에이전트는 부분 실패를 감지하면 해당 서브태스크에 대한 대체 전략을 수립하거나, 실패 사실을 사용자에게 투명하게 보고하며 나머지 성공한 결과를 기반으로 최선의 응답을 제공한다. 도구 접근 제어 역시 에러 격리를 강화한다. 서브에이전트는 YAML tools 필드에 명시된 도구만 사용할 수 있으므로, 설령 에이전트 동작이 예상을 벗어나더라도 그 영향 범위가 사전에 제한된다.

무한 루프와 과도한 토큰 사용을 방지하기 위해, 서브에이전트는 다른 서브에이전트를 호출할 수 없다는 원칙이 설계에 내재되어 있다. 도구 와일드카드(*)를 부여하더라도 서브에이전트는 다른 에이전트를 인식하거나 실행할 수 없다. 이는 에이전트 체인이 통제 불가능하게 깊어지는 것을 근본적으로 차단하는 안전 메커니즘이다.

실제로 어떻게 호출하는가

다음은 대규모 코드베이스 리뷰 작업에서 서브에이전트를 활용하는 시나리오이다.

# 터미널에서 명시적 서브에이전트 호출
gemini> @codebase 이 저장소의 인증 모듈 의존성을 분석하고 순환 참조를 찾아줘
gemini> @web-researcher JWT vs Session 기반 인증의 2026년 보안 동향 조사해줘
gemini> @readme-architect 현재 프로젝트 구조를 분석해서 README.md 초안 작성해줘

세 개의 @ 호출을 동시에 입력하면 Gemini CLI는 이를 병렬로 처리한다. 각 서브에이전트는 독립적으로 작업을 수행하고, 완료 순서에 관계없이 결과가 메인 컨텍스트로 수렴된다.

프로젝트 수준의 커스텀 에이전트를 활용하면 팀 전용 워크플로를 코드로 관리할 수 있다.

.gemini/
└── agents/
    ├── security-auditor.md   # 보안 취약점 분석 전문
    ├── api-documenter.md     # OpenAPI 문서 자동 생성
    ├── test-writer.md        # 단위 테스트 자동 작성
    └── performance-profiler.md  # 성능 병목 분석

이처럼 .gemini/agents/ 디렉터리를 Git 저장소에 커밋하면 팀원 전체가 동일한 전문 에이전트 생태계를 공유하게 되며, 에이전트 정의의 버전 관리와 코드 리뷰도 표준 Git 워크플로로 수행할 수 있다.

Gemini CLI의 서브에이전트 지원은 단순한 기능 추가를 넘어, 터미널 기반 AI 워크플로를 멀티에이전트 오케스트레이션 레벨로 끌어올린 설계 전환이다. 허브-앤-스포크 아키텍처, Markdown+YAML 선언적 에이전트 정의, 격리 컨텍스트 기반 병렬 실행이 결합되어 개발자는 복잡한 작업을 분해하고 효율적으로 처리할 수 있다. 특히 .gemini/agents/ 폴더를 통한 팀 단위 에이전트 공유는 AI 기반 개발 워크플로를 표준화하는 강력한 메커니즘이 될 것이다.

메인 에이전트가 허브가 되는 위임 구조

Markdown 한 장으로 정의하는 전문 에이전트

서로 다른 컨텍스트에서 동시에 달리는 서브에이전트

실제로 어떻게 호출하는가

Sources

함께 읽기