Sub-Agent Usage Details — Antigravity-Focused
Antigravity CLI (agy) / Antigravity(Desktop)에서 서브에이전트를 정의하고, 호출하고, 병렬·자동화 단위로 확장하는 방법을 Antigravity 계열에 한정해 정리한 상세 문서 | 공통 개념은 4장 §1 레퍼런스에서, Claude 계열은 4장 §1-A Claude 중심에서 다룬다.
agy --version 또는 세션 안에서 /usage · Antigravity Desktop: 앱 내 정보 화면1. 서브에이전트 정의하기
Google 계열(Antigravity Desktop/CLI)은 별도의 정의 파일이 없다 — 오케스트레이터가 주어진 목표를 보고 그때그때 서브에이전트를 만든다.
Antigravity (Desktop) 워크스페이스 단위 — 별도 정의 파일 없음
Antigravity 데스크톱(Desktop)의 Agent Manager는 에이전트를 사전에 정의된 파일 단위가 아니라 Workspace 단위로 다룬다. 사용자가 목표를 주면 그 Workspace를 맡은 에이전트(오케스트레이터)가 스스로 하위 작업을 쪼개고 필요한 서브에이전트를 즉석에서 만든다. 즉 "reviewer.md 같은 파일을 미리 준비한다"는 개념 자체가 없다.
Antigravity CLI (agy) — 오케스트레이터가 동적으로 생성
Antigravity 데스크톱(Desktop)과 마찬가지로 agy도 사전 정의 파일 없이, 목표(goal)를 받으면 오케스트레이터 에이전트가 작업을 어떻게 쪼갤지 스스로 판단해 서브에이전트를 즉석에서 만들어 병렬로 실행한다. 각 서브에이전트는 독립된 컨텍스트 창을 가져 메인 세션의 맥락이 흐려지는 것을 막는다.
reviewer.md와 똑같은 예제를 억지로 만들면 사실과 어긋난다. Antigravity의 "입문 실습"은 파일을 만드는 것이 아니라 목표를 주고 오케스트레이터가 알아서 작업을 쪼개는 과정을 관찰하는 것이다.2. 서브에이전트 호출/위임하기
Antigravity 계열은 Agent Manager UI와 슬래시 커맨드로 에이전트에게 목표를 맡긴다.
Antigravity (Desktop) Agent Manager UI
Antigravity Desktop에서는 Agent Manager 화면에서 Workspace를 고르고, 그 Workspace를 맡을 에이전트를 스폰(Local Mode 또는 New Worktree Mode)한 뒤 자연어로 목표를 준다. 승인·피드백이 필요한 시점에는 Inbox에 메시지가 쌓인다. "서브에이전트를 호출한다"는 개념보다는 "에이전트에게 목표를 맡기고 진행 상황을 지켜본다"에 가깝다.
Antigravity CLI (agy) — /goal, /agent, /agents
Claude Code의 Agent/Task 툴과 같은 "동적으로 필요한 서브에이전트를 스폰한다"는 동작을, agy는 슬래시 커맨드로 부른다는 차이일 뿐이다(§1-A 섹션 2 참조). agy 세션에서 /goal로 목표를 주면 중간 확인 없이 끝까지 실행하고(주지 않으면 주요 단계마다 확인을 위해 멈춘다), /agent로 장기 작업을 백그라운드에 맡긴 채 계속 다른 프롬프트를 이어갈 수 있다. /agents는 실행 중/완료/막힌 서브에이전트 목록을 보여주는 패널이다.
agy # TUI 세션 시작 /goal notes.txt 파일을 검토하고 개선점을 요약해줘 /agents # 실행 중/완료된 서브에이전트 목록
비대화형 자동화가 필요하면 agy -p "프롬프트"로 한 번만 실행하고 종료시킬 수 있다(CI/자동화용). 프로젝트에 어떤 설정·스킬·플러그인·훅이 로드됐는지 확인하려면 agy inspect를 쓴다.
3. 병렬 실행
Antigravity 계열은 Workspace 단위와 세션 단위의 두 층위에서 병렬 실행을 지원한다.
Antigravity (Desktop) Agent Manager로 여러 Workspace에 에이전트 배정
Antigravity 데스크톱(Desktop)의 Agent Manager는 Editor보다 상위 레벨에서 여러 Workspace에 걸쳐 여러 에이전트를 한눈에 관리하는 인터페이스다. 코드를 직접 작성하기보다 에이전트를 통해 코드베이스와 상호작용하는 방식이 기본이다. 각 Workspace에는 원칙적으로 에이전트를 하나씩만 배정하는 것이 권장되지만, 필요하면 한 Workspace를 여러 에이전트가 함께 쓸 수도 있다. 에이전트를 스폰할 때는 활성 폴더에서 바로 작업하는 Local Mode와, 격리된 git worktree에서 작업하는 New Worktree Mode 중 하나를 선택한다.
Antigravity CLI (agy) — 세션 내부 + 세션 간 병렬
agy는 두 층위의 병렬성을 지원한다. 한 세션 안에서는 오케스트레이터가 여러 서브에이전트를 동시에 실행하고, 세션 간에는 터미널을 여러 개 띄워 서로 다른 agy 세션을 독립적으로 병렬 실행할 수 있다 — 서로 다른 파일을 건드리는 한 안전하다. Antigravity 데스크톱(Desktop)의 Agent Manager를 못 쓰는 환경에서 이 세션 간 병렬이 대안이 된다.
| 항목 | Antigravity (Desktop) | Antigravity CLI (agy) |
|---|---|---|
| 병렬 실행 단위 | 워크스페이스별 독립 에이전트 | 세션 내부 + 세션 간(터미널 여러 개) |
4. 자동화/훅
Antigravity 계열에서 자동화는 명령줄 인터페이스(CLI)의 비대화형 모드와 설정 점검 명령으로 담당한다.
Antigravity (Desktop) — 해당 없음, GUI 중심
Antigravity 데스크톱(Desktop)은 GUI로 승인·진행을 관리하는 구조라, Claude Code의 훅에 대응하는 자동 발화 장치가 없다. 자동화가 필요한 반복 작업은 Antigravity CLI 쪽으로 옮기는 것이 현실적이다.
Antigravity CLI (agy) — 비대화형 실행 + 설정 점검
agy -p "프롬프트"는 한 번 실행하고 종료하는 비대화형 모드로, CI 파이프라인 같은 자동화에 적합하다. agy inspect는 프로젝트에 로드된 설정·스킬·플러그인·훅 구성을 보여준다 — Claude Code의 훅 자동 발화에 대응하는 것은 아니지만, "지금 어떤 설정이 실제로 적용돼 있는지" 확인하는 역할은 같다.
agy -p "커밋 메시지 초안 작성" # 비대화형 — 한 번 실행하고 종료 agy inspect # → skills: 3 loaded, plugins: 1 loaded # → hooks: none configured # → config source: ~/.gemini/antigravity-cli/settings.json
실무 팁: Antigravity에는 계산된 작업량(work done)에 기반한, 주기적으로 갱신되는 사용량 쿼터가 있다. 정확한 수치는 계정·플랜마다 다를 수 있으므로 여러 에이전트를 장시간 병렬로 돌리는 작업을 계획할 때는 이 점을 감안하는 편이 안전하다.
참고 링크
- 📖 Antigravity CLI — Getting Started 공식 문서
- 📖 Antigravity CLI — Using AGY CLI 공식 문서
- 📖 Antigravity — Agent Manager 공식 문서
- ⚙️ 4장 §1 공통 레퍼런스 — 04_Practice_Manual.html
- ⚙️ 4장 §1-A Claude 중심 — 04_Practice_Manual_A.html
- ⚙️ 4장 §2 실습 예시 — 04_Practice_Examples_A.html
Antigravity CLI 1.1.0+ · Antigravity 2.0 기준 | 2026년 7월