한 줄 요약: Antigravity 공식 문서 "Custom subagents". 병렬 빌드, 여러 파일 코드 생성, 조사를 백그라운드 서브에이전트에 맡기는 방법을 다룬다. 부모 에이전트가 invoke_subagent로 띄우는 방식과 작업공간 옵션(inherit·branch·share), 내장 서브에이전트 3개(research, browser, self), Markdown+YAML frontmatter로 정의하는 사용자 서브에이전트의 위치와 필드, 상태(Running·Idle·Killed), 중첩 10단계 한도, 권한 상속, CLI의 /agents 패널과 단축키를 담는다.
원본 정보#
- 제목: Custom subagents
- 발행: Antigravity 공식 문서(antigravity.google). 원문에 발행일·갱신일 표기가 없다(원본 날짜 미상).
- URL: https://antigravity.google/docs/subagents/ (새 창) (받은 주소는 원문 마크다운
https://antigravity.google/docs/subagents.md) - 수집(fetch)일: 2026-10-21. 경로, 필드, 명령, 단축키, 플랜 조건은 이 날짜 기준이다.
- 원본은 "Antigravity App" 절과 "Antigravity CLI" 절로 나뉜다. App 절의 일부 문장(모니터링의
Alt+J, 취소의k, 상태별 설명의 "in the CLI")은 CLI도 함께 말한다.
핵심 주장#
- 부모가
invoke_subagent로 동시 세션을 띄운다. 서브에이전트는 부모와 같은 작업공간을 물려받거나(inherit), 격리된 Git worktree를 만들거나(branch), 디렉터리 저장소를 공유한다(share). 지정된 모델 등급으로 돌지만 부모의 대화 기록(컨텍스트 창)은 물려받지 않고 새로 시작한다. 부모는 여러 서브에이전트를 동시에 띄울 수 있다. → 서브에이전트 - 내장 서브에이전트가 셋 있다.
research(코드베이스 조사·파일 탐색·구조 파악),browser(샌드박스 브라우저로 상호작용 테스트,/browser슬래시 명령으로만 호출),self(부르는 에이전트의 복제, 같은 시스템 지시와 도구). → 서브에이전트 - 사용자 서브에이전트는 Markdown 파일로 정의한다. YAML frontmatter와 본문(시스템 프롬프트)으로 된
.md파일을 워크스페이스.agents/agents/<name>.md또는.agents/agents/<name>/agent.md, 전역~/.gemini/config/agents/<name>.md또는.../agents/<name>/agent.md, 플러그인plugins/<plugin_name>/agents/에 두면 자동으로 찾는다. 세션 중에는define_subagent도구로 임시 서브에이전트를 만들 수 있다. → 서브에이전트, Antigravity CLI, 플러그인 - 서브에이전트는 백그라운드에서 비동기로 돈다. 상태는 Running·Idle·Killed 셋이다. Idle은 결과를 부모에게 보낸 뒤 멈춘 상태로, 다른 에이전트의 메시지를 받으면 이전 맥락을 유지한 채 다시 깨어난다. Killed는 영구 종료이고, 그 서브에이전트용 임시 Git worktree는 자동으로 정리되며 대화 기록은 JSONL 로그로 남는다. 에이전트끼리는 대화 ID로 메시지를 주고받고, 서로의 대화 기록을 읽을 수 있다. → 서브에이전트
- 안전 설정은 부모에게서 물려받는다. 서브에이전트는 부모의 허용된 터미널 명령 접두사, 파일 읽기·쓰기 디렉터리 범위, 샌드박스 설정을 물려받는다. 사용자 승인이 필요한 도구 실행은 메인 화면이나 서브에이전트 패널로 올라온다. 중첩은 메인 에이전트 아래 최대 10단계로 "strictly enforced"된다. → 서브에이전트
원본의 경로·필드·명령 (2026-10-21 기준)#
사용자 서브에이전트 frontmatter(원본 표):
| 속성 | 타입 | 기본값 | 설명 |
|---|---|---|---|
name | string | 고유 식별자 | |
description | string | 플래너가 언제 이 에이전트에게 맡길지 정할 때 쓰는 설명 | |
tools | string[] | [] | 허용 도구 목록view_file, replace_file_content, grep_search, run_command) |
mainAgent | boolean | true | 채팅에서 주 에이전트로 고를 수 있는지 |
subagent | boolean | true | invoke_subagent로 부를 수 있는지 |
model | string | inherit | 모델 등급inherit, flash, pro) |
command | string | sandbox | 셸 명령 자동 실행 정책off, auto, eager, sandbox) |
mcpServers | object[] | [] | 이 서브에이전트용 MCP 서버 |
skills / plugins | string[] | [] | 스킬 경로skills/) 또는 플러그인 의존성 |
- 알려진 문제(원본 표기 "Known issue"):
tools에 없는 이름이나 오타를 쓰면 서브에이전트 프로세스가 실행 중 멈출 수 있다. 스키마 검증 강화와 수정은 다가오는 업데이트로 계획돼 있다고 한다. - 원본 예시
code-auditor.md:tools에view_file·grep_search·run_command,subagent: true,mainAgent: false,model: pro,commandExecutionPolicy: sandbox,skills: [skills/security-checklist], 본문에# System Prompt와# Review Guidelines. - CLI 명령·단축키:
/agents: Agent Manager 패널. 활성·완료·종료·실패한 백그라운드 에이전트의 ID, 역할, 상태(running, done, killed, error), 현재 단계를 보여 준다. ↑/↓로 고르고 Enter로 상세 보기(추론 기록, 도구 호출, 실행 출력), Esc로 돌아간다. 이 패널에서 사용자 에이전트를 주 에이전트로 고르거나 대화를 포크할 수도 있다./tasks:/btw로 시작한 조회나 셸 명령·테스트 같은 에이전트가 아닌 백그라운드 작업 목록. Enter로 stdout 로그, 폭주한 프로세스 종료.Alt+J: 승인을 기다리는 다음 서브에이전트의 상세 보기로 바로 이동.Ctrl+K: 프롬프트 위 알림에 요약된 대기 동작(예:Subagent 12 asks to run "npm test")을 패널을 바꾸지 않고 승인.k: 실행 중인 서브에이전트 취소(App은 Stop Subagent 버튼).
- CLI 절은 사용자 에이전트 위치를 워크스페이스
.agents/agents/<name>.md또는.agents/agents/<name>/agent.md, 전역~/.gemini/config/agents/로 적고,subagent: true인 에이전트를 주 에이전트가invoke_subagent로 부를 수 있다고 말한다.
멀티 에이전트 오케스트레이터 두 가지(플랜 조건은 원본 표기 그대로):
| 명령 | 하는 일 | 원본의 플랜 조건 |
|---|---|---|
/ | 3계층 추론 구조Orchestrator → DeepCoder·DeepInvestigator 조정자 → 격리된 실행 워커)로 어려운 동시성 버그, 알고리즘 문제, 간단하지 않은 리팩터링을 대화형 세션 안에서 | Google One AI Premium |
/ | 큰 소프트웨어 프로젝트, 여러 파일 리팩터링, 복잡한 조사를 위해 전문 에이전트 팀을 조율한다. 마일스톤 분해, 병렬 구현, 독립 검증 | 유료 플랜, App과 CLI |
원본에 없는 것#
- 같은 이름의 서브에이전트가 워크스페이스·전역·플러그인에 함께 있을 때 어느 쪽이 이기는지 말하지 않는다.
- 서브에이전트가 부모의 샌드박스 설정을 물려받는다는 문장과 frontmatter
commandExecutionPolicy(기본sandbox)가 서로 다를 때 어느 쪽이 적용되는지 말하지 않는다. - 원본은 동시에 띄울 수 있는 서브에이전트 수의 한도를 말하지 않는다(중첩 깊이 10단계만 적는다).
/boost·/teamwork-preview의 세부와 요금은 별도 문서(Boost, Teamwork)로 링크만 한다.- Gemini CLI에서 쓰던 에이전트 정의를 옮기는 방법, Claude Code 서브에이전트와의 관계는 다루지 않는다.