- Gemini CLI가 복잡하고 반복적인 작업을 전문 서브에이전트에게 위임할 수 있는 멀티에이전트 아키텍처를 공식 지원하기 시작
- 각 서브에이전트는 독립된 컨텍스트 윈도우, 커스텀 시스템 인스트럭션, 전용 도구 세트를 갖추고 격리된 환경에서 실행
- 마크다운 파일과 YAML frontmatter로 커스텀 서브에이전트를 정의하며, 글로벌 또는 프로젝트 레벨에서 팀과 공유 가능
- 여러 서브에이전트를 병렬 실행할 수 있어 리서치, 리팩토링 등 다수 작업의 총 소요 시간을 크게 단축
- 기본 내장 에이전트(generalist, cli_help, codebase_investigator)와 함께 @agent 구문으로 명시적 작업 위임이 가능해 CLI 기반 개발 워크플로우의 확장성 확보
서브에이전트 개념과 핵심 이점
- 서브에이전트는 기본 Gemini CLI 세션과 함께 작동하는 전문 에이전트로, 복잡한 작업을 받으면 Gemini CLI가 전략적 오케스트레이터 역할을 하며 가장 적합한 서브에이전트에게 서브태스크를 위임
- 각 서브에이전트는 자체 tools, MCP 서버, 시스템 인스트럭션, 컨텍스트 윈도우를 보유하며 완전히 격리된 상태에서 실행
- 서브에이전트의 전체 실행(수십 번의 도구 호출, 파일 검색, 테스트 실행 포함)이 단일 응답으로 통합되어 메인 에이전트에 반환
- 메인 컨텍스트 윈도우가 채워지는 것을 방지하고 후속 인터랙션의 속도와 비용 효율성 유지
- 주요 이점 세 가지:
- 기본 에이전트가 전체 목표, 의사결정, 최종 응답에 집중 가능
- 리서치, 코드 탐색, 분석, 테스트 등에 전문 서브에이전트를 병렬 실행하여 작업 속도 향상
- 서브에이전트가 요약 또는 포맷된 응답을 반환하므로 기본 세션의 context rot와 context pollution 방지
커스텀 서브에이전트 생성
- 마크다운 파일(
.md)에 YAML frontmatter를 사용해 커스텀 서브에이전트를 정의
~/.gemini/agents에 배치하면 개인 워크플로우용 글로벌 에이전트로 등록되고, 리포지토리의 .gemini/agents에 커밋하면 프로젝트 레벨에서 팀과 공유 가능- Gemini CLI extensions의
agents/ 디렉토리에 에이전트 정의 파일을 포함시켜 확장 기능의 일부로 번들링도 가능
- 예시로 제공된
frontend-specialist 에이전트 구성:
name, description, tools(read_file, grep_search, glob, list_directory, web_fetch, google_web_search), model: inherit 등을 frontmatter에 정의- 시스템 인스트럭션에서 Senior Frontend Specialist 및 UI/UX Architect 역할을 지정
- 핵심 원칙으로 모듈형 아키텍처 설계, Core Web Vitals 기반 성능 최적화, WCAG 2.1+ 접근성 준수를 명시
- 가이드라인으로 브라우저 네이티브 API 우선 활용, Atomic 컴포넌트 설계, 상태별 시각적 피드백(로딩, 스켈레톤, 에러, 빈 상태, 성공), Progressive Enhancement, 유지보수 중심 설계를 포함
- 이 에이전트의 역할은 분석과 개선 제안에 한정되며 직접 코드를 수정하지 않음
- 파일을
.gemini/agents/frontend-specialist.md에 배치하면 Gemini CLI가 즉시 새 전문가로 인식
병렬 실행
- Gemini CLI는 병렬 서브에이전트 실행을 지원하여 여러 서브에이전트 또는 동일 서브에이전트의 다수 인스턴스를 동시에 실행 가능
- 5개의 서로 다른 주제를 리서치하거나 여러 개별 컴포넌트를 리팩토링해야 할 때 복수 에이전트를 동시에 디스패치하여 총 소요 시간을 크게 단축
- 명시적 요청 방법 예시: "Run the frontend-specialist on each package in parallel."
- 주의사항:
- 대규모 코드 편집 작업에 병렬 서브에이전트 사용 시 충돌 발생 및 에이전트 간 코드 덮어쓰기 위험
- 병렬 실행 시 요청이 동시에 전송되므로 사용량 제한(usage limits) 에 더 빠르게 도달
내장 서브에이전트와 사용법
- Gemini CLI에 기본 탑재된 서브에이전트 세 가지:
- generalist: 모든 도구에 접근 가능한 범용 에이전트로, 배치 리팩토링이나 대량 출력 명령 실행 등 턴 집약적 작업에 적합 (일반 Gemini CLI 에이전트의 복사본을 서브에이전트로 사용하는 형태)
- cli_help: Gemini CLI 자체에 대한 전문가 에이전트로, Gemini CLI 문서에 직접 접근하여 기능 관련 질문에 답변
- codebase_investigator: 코드베이스 탐색, 아키텍처 매핑, 버그 근본 원인 분석, 시스템 전반 의존성 파악에 특화
- Gemini CLI는 서브에이전트의 description을 기반으로 자동 라우팅을 수행하지만, @agent 구문을 사용해 명시적으로 특정 에이전트에게 작업 위임 가능
- 예:
@frontend-specialist 앱 리뷰 및 개선점 플래그 요청
- 예:
@generalist 프로젝트 전체 라이선스 헤더 업데이트
- 예:
@codebase_investigator 인증 플로우 매핑
- @ 기호 뒤에 서브에이전트 이름을 붙이면 해당 에이전트의 격리된 컨텍스트 윈도우 내에서 작업 처리
- 현재 설정된 모든 서브에이전트를 확인하려면 Gemini CLI 내에서
/agents 명령 실행