2026년 8월 18일 화요일, Gemini CLI 서브에이전트 만들기를 처음부터 끝까지 정리한 기록이다.
먼저 결론부터 적는다.
.gemini/agents/ 폴더에 마크다운 파일 하나를 만들면 끝난다. 파일 맨 위에 ---로 감싼 YAML frontmatter를 넣고 name과 description 두 필드만 채우면 최소 조건은 충족된다."
그다음 /agents 명령으로 확인하고, @에이전트명으로 호출하면 된다.
서브에이전트 기능은 2026년 4월에 들어왔다. Google Developers Blog의 발표 글은 4월 15일자이고, GitHub 릴리스 논의글은 v0.38.1 / 4월 16일로 적고 있다. 하루 차이가 나서 정확한 날짜는 두 출처를 같이 봐야 한다.
한국어로 검색해봤는데 서브에이전트만 다룬 글이 거의 없었다. 대부분 Gemini CLI 설치·사용법 단계에서 멈춰 있어서, 공식 문서를 직접 읽고 정리하게 됐다.
1. Gemini CLI 서브에이전트란 무엇일까?
서브에이전트는 메인 Gemini 에이전트가 특정 작업을 위해 고용하는 "전문가"다. 각 에이전트는 자기만의 시스템 프롬프트와 페르소나, 명시적으로 허용된 도구 세트, 그리고 독립된 컨텍스트 윈도우를 갖는다. 메인 에이전트 하나가 전부 떠안던 일을 쪼개서 맡기는 구조다.
핵심은 컨텍스트가 분리된다는 점이다. 각 에이전트가 조사한 내용을 통째로 메인에 붓는 게 아니라, 요약본이나 형식화된 응답만 돌려준다.
덕분에 메인 에이전트의 컨텍스트가 잡다한 정보로 오염되는 이른바 "context rot"을 피할 수 있다. 여러 개가 동시에 돌아가서 작업 속도도 올라간다.
2. 서브에이전트 파일은 어디에 만들어야 할까?
저장 위치는 딱 두 곳이다. 프로젝트 안에서만 쓸 에이전트는 프로젝트 루트의 .gemini/agents/ 아래에, 계정 전체에서 쓸 개인 에이전트는 홈 디렉터리의 ~/.gemini/agents/ 아래에 둔다. 둘 다 확장자는 .md다.
| 범위 | 경로 | 용도 |
|---|---|---|
| 프로젝트 수준 | .gemini/agents/*.md |
팀 공유용. 레포에 커밋해서 같이 씀 |
| 사용자 수준 | ~/.gemini/agents/*.md |
개인 전용. 어느 프로젝트에서나 씀 |
기준은 단순하게 잡았다. 이 레포의 코드 컨벤션을 아는 에이전트라면 프로젝트 수준, 어디서든 쓰는 범용 도구라면 사용자 수준.
팀에 공유할 거면 .gemini/agents/에 넣고 커밋하면 된다는 게 꽤 편하다. 설정 파일이 아니라 그냥 마크다운이라서 리뷰하기도 쉽다.
3. 서브에이전트 파일은 어떻게 쓸까?
파일은 반드시 --- 세 개로 감싼 YAML frontmatter로 시작해야 한다. 공식 문서가 대문자 MUST로 못박아 둔 부분이다. frontmatter 아래 본문에는 이 에이전트가 어떻게 행동할지를 적는다. 그게 곧 시스템 프롬프트가 된다.
필수 필드는 몇 개일까?
필수는 name과 description 두 개뿐이다. 나머지 여섯 개는 전부 선택이고 기본값이 있다.
| 필드 | 타입 | 필수 | 설명 / 기본값 |
|---|---|---|---|
name |
string | 필수 | 도구명으로 쓰이는 고유 식별자 |
description |
string | 필수 | 이 에이전트가 뭘 하는지 설명 |
kind |
string | 선택 | local(기본값) 또는 remote |
tools |
array | 선택 | 접근 가능한 도구 목록 |
model |
string | 선택 | 특정 모델 지정 |
temperature |
number | 선택 | 0.0~2.0 (기본값 1) |
max_turns |
number | 선택 | 최대 대화 턴 수 (기본값 30) |
timeout_mins |
number | 선택 | 최대 실행 시간, 분 단위 (기본값 10) |
description을 대충 쓰면 안 된다. 뒤에 나올 자동 위임에서 메인 에이전트가 이 설명을 보고 어떤 서브에이전트를 부를지 고르기 때문이다.
max_turns 기본값 30, timeout_mins 기본값 10이라는 숫자는 기억해둘 만하다. 조사 범위가 넓은 에이전트는 이 두 개에 먼저 걸린다.
실제 파일은 어떻게 생겼을까?
구조만 놓고 보면 이런 모양이다.
---
name: code_reviewer
description: 변경된 코드를 읽고 컨벤션 위반과 잠재적 버그를 지적한다
kind: local
temperature: 0.2
max_turns: 20
timeout_mins: 15
---
너는 코드 리뷰 전문가다.
변경된 파일만 읽고, 컨벤션 위반과 잠재적 버그를 항목별로 정리해 보고한다.
코드를 직접 수정하지 않는다. 지적과 근거만 남긴다.
tools 필드는 일부러 비워뒀다. 지정할 수 있는 도구 이름 목록은 이번 정리에서 확인하지 못했다. 실제로 쓸 때는 /agents로 사용 가능한 도구를 먼저 확인하는 편이 안전하다.
temperature를 0.2로 낮춘 건 개인 취향이다. 리뷰처럼 일관성이 중요한 작업은 낮게, 아이디어를 뽑는 작업은 기본값 1 근처로 두는 편이 편했다.
4. 만든 서브에이전트를 어떻게 호출할까?
호출 방법은 두 가지다. 하나는 자동 위임, 다른 하나는 @ 문법을 쓰는 강제 위임이다. 그리고 등록된 서브에이전트를 관리하고 확인하는 건 /agents 명령이 담당한다.
자동 위임과 강제 위임은 뭐가 다를까?
자동 위임은 메인 에이전트가 작업 내용을 보고 알아서 맞는 서브에이전트를 고르는 방식이다. 사용자가 따로 지정하지 않는다.
강제 위임은 @서브에이전트명으로 직접 찍어서 부르는 방식이다. 공식 문서와 발표 글에 이런 예시가 나온다.
@codebase_investigator Map out the relationship between...@codebase_investigator 인증 흐름을 매핑해주세요@frontend-specialist 앱을 검토하고 개선 사항을 지적해주세요@generalist 전체 프로젝트의 라이선스 헤더를 업데이트하세요
보다시피 특별한 문법이 없다. @에 이름 붙이고 평소처럼 시키면 된다.
그리고 /agents create 같은 서브커맨드가 있는지는 이번에 확인하지 못했다. 공식 문서가 상세 문법을 별도 레퍼런스 문서로 넘겨두고 있어서, 파일을 직접 만드는 쪽이 확실하다.
5. 기본으로 딸려오는 서브에이전트는 뭐가 있을까?
설치 직후부터 쓸 수 있는 서브에이전트가 세 개 있다. @cli_help, @codebase_investigator, @generalist다. 이 기능 자체도 기본적으로 활성화되어 있어서, 별도로 켜는 작업은 필요 없다.
처음이라면 파일부터 만들지 말고 @codebase_investigator로 프로젝트를 한 번 훑어보게 시켜보는 게 감을 잡기 좋다.
혹시 서브에이전트를 아예 끄고 싶다면 settings.json에서 "enableAgents": false로 두면 된다.
6. 에이전트 팀을 짤 때 걸리는 제약은 뭘까?
가장 중요한 제약은 이거다. 서브에이전트는 다른 서브에이전트를 호출할 수 없다. 공식 문서에 "subagents cannot call other subagents"로 명시돼 있고, 무한 루프와 토큰 낭비를 막기 위한 설계다. 즉 Gemini CLI의 에이전트 팀은 메인 1 + 서브 N의 2계층 구조로 고정된다.
이걸 모르고 설계하면 헛수고를 한다. "리서처가 라이터를 부르고 라이터가 리뷰어를 부른다" 같은 체인은 만들 수 없다.
대신 메인 에이전트를 오케스트레이터로 두고, 각 결과를 메인이 받아서 다음 에이전트에 넘기는 식으로 짜야 한다. 계층이 아니라 방사형이다.
또 하나. 서브에이전트는 명시적으로 부여한 도구만 쓸 수 있다. 도구 격리가 기본이라 조사용 에이전트에 쓰기 권한을 안 주면 파일을 건드릴 수 없다. 제약처럼 보이지만 사고를 막아주는 안전장치에 가깝다.
| 제약 / 설정 | 내용 |
|---|---|
| 계층 | 메인 1 + 서브 N의 2계층 고정 |
| 서브 → 서브 호출 | 불가 (무한 루프·토큰 낭비 방지) |
| 도구 접근 | 명시적으로 부여한 도구만 |
| 기능 on/off | 기본 활성화, settings.json의 "enableAgents": false로 비활성화 |
원격 서브에이전트(kind: remote)도 있긴 하다. 별도 "Remote Subagents" 문서가 따로 있는데, 상세 동작은 이번에 열어보지 않았다.
7. 시작하기 전에 필요한 준비물은?
Node.js가 깔려 있다면 npm install -g @google/gemini-cli 한 줄이면 설치가 끝난다. 첫 실행 때 구글 계정 로그인 / API Key / Vertex AI 중 하나로 인증하고, /model 명령으로 gemini-3-pro-preview나 gemini-2.5-pro 같은 모델을 고르면 준비 완료다.
여기에 하나 더 챙기면 좋은 게 GEMINI.md다. 프로젝트 컨텍스트와 작업 규칙을 적어두는 파일이다.
로드 순서는 ~/.gemini/GEMINI.md(글로벌) → 프로젝트 루트 → 하위 디렉터리 순이고, 하위 파일이 우선한다. /memory show로 지금 뭐가 로드됐는지 확인하고 /memory refresh로 갱신한다. @로 다른 파일을 import할 수도 있다.
서브에이전트를 만들기 전에 GEMINI.md부터 정리해두는 걸 권한다. 팀 공통 규칙은 여기에, 역할별 세부 지침은 각 에이전트 파일에 나누면 중복이 줄어든다.
8. 정리하면 이렇다
세 가지 기준으로 짧게 정리한다.
설정 난이도 — 낮다. 마크다운 파일 하나에 필수 필드 두 개(name, description)면 동작한다. 별도 설정 UI나 등록 절차가 없다는 게 제일 큰 장점이다.
구조의 명확성 — 좋다. 프로젝트 수준(.gemini/agents/)과 사용자 수준(~/.gemini/agents/) 구분이 단순하고, 필드 8개에 전부 기본값이 정해져 있어 헷갈릴 여지가 적다. 다만 tools에 넣을 도구 이름 목록과 /agents create 문법은 별도 레퍼런스를 봐야 한다.
팀 설계 활용도 — 조건부다. 2계층 제한이 명확해서 복잡한 다단계 파이프라인은 그대로 옮기기 어렵다. 그래도 컨텍스트 격리와 병렬 실행만으로도 얻는 게 크다.
다음엔 실제로 서브에이전트 두세 개를 만들어서 돌려보고 결과를 기록해야겠다. 😊
9. 자주 묻는 질문 (FAQ)
Q1. Gemini CLI 서브에이전트는 언제부터 쓸 수 있나?
2026년 4월부터다. Google Developers Blog의 발표 글은 4월 15일자이고, GitHub 릴리스 논의글은 v0.38.1과 4월 16일을 함께 적고 있다. 두 출처의 날짜가 하루 차이 나고 버전 번호는 GitHub 논의글에만 나온다. 그래서 "2026년 4월, v0.38.1 시점"이라고 폭을 두고 이해하는 편이 안전하다.
Q2. 서브에이전트 파일은 어디에 저장하나?
두 곳 중 하나다. 팀과 공유할 에이전트는 프로젝트 루트의 .gemini/agents/ 아래에, 개인 전용은 홈 디렉터리의 ~/.gemini/agents/ 아래에 .md 파일로 둔다. 형식은 둘 다 같고, 파일 맨 위에 ---로 감싼 YAML frontmatter가 반드시 있어야 한다.
Q3. YAML frontmatter에서 필수 필드는 뭔가?
name과 description 두 개다. name은 도구명으로 쓰이는 고유 식별자이고, description은 에이전트 기능 설명이다. 나머지 kind, tools, model, temperature, max_turns, timeout_mins 여섯 개는 선택이며 각각 기본값이 있다. kind는 local, temperature는 1, max_turns는 30, timeout_mins는 10이 기본값이다.
Q4. 특정 서브에이전트를 콕 집어 부를 수 있나?
가능하다. @서브에이전트명 문법을 쓰면 된다. 예를 들어 @codebase_investigator 인증 흐름을 매핑해주세요처럼 쓴다. 지정하지 않으면 메인 에이전트가 작업 내용에 맞는 서브에이전트를 스스로 골라 위임한다. 등록된 에이전트 목록 확인과 관리는 /agents 명령으로 한다.
Q5. 서브에이전트가 또 다른 서브에이전트를 부를 수 있나?
불가능하다. 공식 문서가 서브에이전트는 다른 서브에이전트를 호출할 수 없다고 명시한다. 무한 루프와 토큰 낭비를 막기 위한 설계다. 결과적으로 Gemini CLI의 에이전트 팀은 메인 1개 + 서브 N개의 2계층 구조로 제한된다. 다단계 흐름이 필요하면 메인 에이전트가 순서를 조율하는 방식으로 짜야 한다.
Q6. 서브에이전트 기능을 끌 수도 있나?
있다. 이 기능은 기본적으로 활성화되어 있고, 끄고 싶으면 settings.json에서 "enableAgents": false로 설정하면 된다. 참고로 기본 제공 서브에이전트는 @cli_help, @codebase_investigator, @generalist 세 개이며, 이 기능을 끄면 이들도 함께 사용할 수 없게 된다.
참고 자료: Gemini CLI 공식 문서(subagents.md), Google Developers Blog 서브에이전트 발표 글, GitHub Discussion #25562, Gemini CLI 한국어 사용법 자료