Antigravity 서브에이전트 튜토리얼: 카드, @ 문법, 브라우저 문제 해결
Reddit에서는 "Antigravity에는 서브에이전트가 없다"고 묻지만, 실제로는 있습니다. 문서에는 research·browser·self가 올라와 있고, v2.16.0에서 모든 호출이 라이브 카드가 되었으며, CLI 1.2.9에서 @로 메시지를 보낼 수 있게 되었습니다. 검증된 12단계와 함께 동작하지 않는 브라우저 서브에이전트의 해결 목록까지 정리했습니다.
요약
- Antigravity 서브에이전트는 이미 존재합니다. research·browser·self가 내장되어 있고, 커스텀도 Markdown 파일 하나면 됩니다. "서브에이전트가 없다"는 글은 오래된 정보이지만, 고통은 실제였습니다. v2.16.0 이전에는 서브에이전트가 보이지 않는 채로 돌고 있었으니까요.
- v2.16.0(2026년 9월 22일)은 모든 서브에이전트 호출을 라이브 카드로 바꿉니다. 실행 중·대기 중·완료 상태, 호버로 정지, 클릭 한 번으로 대화로 이동.
- CLI 1.2.9(2026년 9월 23일)는 @ 문법을 추가했습니다. @를 입력하면 자동완성에 실행 중·완료된 서브에이전트가 뜨고, 메시지가 그 대화로 곧장 들어갑니다. 유휴 상태의 서브에이전트는 맥락을 유지한 채 다시 깨어납니다.
- "브라우저 서브에이전트가 안 돌아간다"는 대개 Browser Tools 토글, 조직의 툴 서버 정책, 또는 잘못 입력된 도구 이름이 실행을 붙잡고 있는 문제입니다. 아래 다섯 가지 점검이 전부 커버합니다.
How to better understand, follow, and collaborate with the agent
영상:Google Antigravity1:32
The Liftoff Series - Developing with parallel agents
영상:Google Antigravity1:17
How to Use Antigravity Subagents Like a Pro (Step-by-Step Guide)
영상:The Next Signal13:59
Antigravity changelog & subagents docs
공식 출처:antigravity.google
두 공식 영상 모두 2.16.0 이전에 촬영되었습니다. 서브에이전트 카드가 없는 초기 UI를 보여주므로, 이 페이지에서는 지금도 같은 방식으로 작동하는 아티팩트 시스템(구현 계획, 작업 목록, 워크스루) 소개에만 사용합니다. 동작 관련 사실은 antigravity.google의 공식 서브에이전트 문서와 체인지로그를 따릅니다. 세 번째 영상에는 얼굴 출연 오버레이가 있어 스틸 컷은 한 장도 가져오지 않았고 사실 확인용으로만 썼습니다.
스틸 컷은 Google Antigravity의 "How to better understand, follow, and collaborate with the agent"와 "The Liftoff Series - Developing with parallel agents", 그리고 WorldofAI의 "Turn Antigravity Into AN AI Autonomous Engineering Team!"(YouTube)에서 가져왔습니다. 사실 확인은 The Next Signal의 "How to Use Antigravity Subagents Like a Pro"와 antigravity.google/changelog와 교차 검증했습니다. 타임스탬프는 출처 영상으로 연결되는 딥링크입니다.
12단계로 Antigravity 서브에이전트 사용하기
서브에이전트 시스템 찾기
- 1
Agent Manager 열기
Antigravity를 실행하고 Agent Manager를 엽니다. 모든 대화와 백그라운드 에이전트가 모이는 미션 컨트롤입니다. IDE에서는 전용 패널이고, 터미널에서는 /agents로 같은 라이브 체크리스트(실행 중·완료·강제 종료·실패)를 확인합니다.
Agent Manager 미리보기 패널: Inbox와 Start conversation 버튼, 두 워크스페이스의 폴더.0:54 보기 - 2
누가 일해 주는지 알기: research·browser·self
Antigravity는 내장 서브에이전트 셋을 싣고 있습니다. 코드베이스 탐색과 파일 탐색을 맡는 research, 샌드박스 Chrome을 운전하는 browser, 호출한 에이전트의 직접 클론인 self. 커스텀 서브에이전트는 YAML 프론트매터가 붙은 Markdown 파일입니다. 부모는 invoke_subagent 도구로 이들을 모두 호출합니다.
- 3
위임 가능한 작업으로 부모에게 지시하기
작업에 맞는 워크스페이스에서 대화를 시작하고, 고칠 파일이 아니라 결과물을 묘사합니다. "이거 조사해서 정리해 줘", "이 기능 만들고 테스트해 줘"처럼요. 여러 파트로 나뉘는 작업이야말로 에이전트가 작업을 서브에이전트에 나누는 계기가 됩니다.
Space Research 워크스페이스에서 새 대화를 시작하며 전송 전에 Planning 모드와 모델 칩을 설정한 장면.0:38 보기 - 4
코드 전에 구현 계획 읽기
부모는 먼저 구현 계획(Implementation Plan) 아티팩트 초안을 작성합니다. 목표, 변경 제안, 검증 계획. 서브에이전트는 부모의 대화 기록을 상속하지 않으므로, 이 계획이 생성된 모든 에이전트를 한 방향으로 묶는 계약서입니다. 이의는 지금 제기하세요. 방향을 바꾸기에 가장 저렴한 순간입니다.
Proposed Changes와 Verification Plan을 갖춘 구현 계획 아티팩트 — 코드가 한 줄도 존재하기 전의 모습.0:22 보기
서브에이전트가 일하는 모습 보기
- 5
실시간 작업 목록 따라가기
작업이 시작되면 계획은 실시간으로 스스로 체크되는 작업 목록이 됩니다. planning, implementation, polish, verification. 서브에이전트가 단계를 끝낼 때마다 갱신되므로, 질문으로 끼어들기 전에 먼저 여기를 보세요. 보통 진행 상황이 답을 줍니다.
실행 중인 작업 목록: planning과 implementation은 체크됐고 polish와 verification은 미완료.0:42 보기 - 6
실행 중인 모든 에이전트를 Inbox에서 추적
v2.16.0(2026년 9월 22일)부터 서브에이전트 호출은 전용 카드로 표시됩니다. 실행 중·대기 중·완료의 실시간 상태, 호버 정지 버튼, 클릭 한 번으로 대화 이동. Inbox는 워크스페이스를 넘나드는 실행을 모아 보여 주고, 병렬 에이전트는 각자의 상태와 함께 나란히 놓입니다.
세 개의 대화가 병렬로 실행 중. 각자의 상태와 워크스페이스를 갖고 있습니다.0:50 보기 - 7
서브에이전트의 대화로 직접 들어가기
모든 서브에이전트는 자신만의 대화를 갖고 있으며, 카드나 매니저 사이드바에서 클릭 한 번으로 열립니다. 열면 서브에이전트의 비공개 스레드를 읽고 바로 답장할 수 있습니다. 유휴 상태의 서브에이전트에 메시지를 보내면 이전 턴의 맥락을 모두 유지한 채 자동으로 다시 깨어납니다.
Agent Manager 사이드바는 대화를 워크스페이스별로 묶어 보여 줍니다. 스피너가 진행 중인 실행을 표시.9:40 보기 - 8
증거와 함께 워크스루 검증하기
작업이 끝나면 에이전트가 무엇을 했는지 보고하는 워크스루 아티팩트를 생성하고, 브라우저 작업에는 증거로 스크린샷이나 화면 녹화가 붙어 옵니다. 수락하기 전에 읽으세요. "끝냈다"와 "제대로 끝냈다" 사이의 간극을 발견하는 가장 빠른 방법입니다.
워크스루에는 완료 항목이 나열되고 완성된 앱의 데모 녹화가 나란히 놓입니다.0:50 보기
조종하고, 병렬화하고, 검증하기
- 9
아티팩트에 댓글 달며 방향 잡기
처음부터 프롬프트를 다시 쓸 필요가 없습니다. 구현 계획, 워크스루, 코드의 특정 줄에 직접 댓글을 남기면 에이전트가 피드백 루프를 읽고 조정합니다. 아티팩트가 당신과 에이전트 사이의 공유된 진실의 원천이 됩니다.
구현 계획의 목표 문단에 바로 댓글을 입력하는 장면.1:06 보기 - 10
스크린샷 드래그 선택으로 픽셀 단위 피드백
시각적 작업에서는 아티팩트 안의 스크린샷 위를 드래그해 선택하고 그 영역에만 댓글을 달 수 있습니다. "이 여백", "이 색 조합 바꿔 줘"처럼요. 서브에이전트에는 애매한 설명 대신 좌표가 전달되어 주고받기 라운드가 통째로 줄어듭니다.
브라우저 스크린샷에서 드래그로 선택한 영역에 인라인 댓글이 달린 모습.1:17 보기 - 11
병렬 작업용 두 번째 워크스페이스 준비하기
컨텍스트 스위칭은 흐름을 죽입니다. Agent Manager에 두 번째 워크스페이스를 미리 띄워 두고, 끼어드는 작업을 그곳의 백그라운드 에이전트에 위임하세요. 내 워크스페이스는 그대로입니다. 에이전트는 검토나 승인이 필요할 때만 돌아옵니다.
워크스페이스 전환기에 Playground, Space Flight Booking, Space Research가 나열됩니다.0:34 보기 - 12
브라우저 서브에이전트에게 UI 테스트 맡기기
브라우저 서브에이전트는 /browser 슬래시 명령으로 호출합니다. 문서가 유일한 문이라고 명시하는 바로 그 출입문입니다. 별도 프로필의 샌드박스 Chrome을 조작하고, 스크린샷과 동작 녹화를 아티팩트로 남기며, QA 엔지니어처럼 앱을 만져 봅니다. /browser가 아무 반응이 없다면 Browser Tools 설정이나 조직의 툴 서버 정책을 의심하세요.
브라우저 서브에이전트의 녹화가 워크스루 안에서 재생됩니다. 실제 페이지에서 다크 모드를 검증한 장면.0:46 보기
서브에이전트의 거처: Agent Manager, CLI, @ 문법
서브에이전트는 두 표면 모두에서 돕니다. IDE에서는 Agent Manager 안의 카드와 아티팩트이고, 터미널에서는 CLI의 /agents가 같은 미션 컨트롤을 라이브 체크리스트로 엽니다. 화살표 키로 실행을 하이라이트, Enter로 세부 보기(비공개 생각, 도구 호출, 출력), Alt+J로 승인 대기 중인 다음 서브에이전트로 점프, k로 하이라이트된 실행 취소.
@ 문법은 CLI 우선 기능으로 CLI 1.2.9(2026년 9월 23일)에 등장했습니다. 프롬프트에서 @를 입력하면 자동완성이 실행 중·완료된 서브에이전트를 나열하고, 메시지는 그 서브에이전트의 대화로 곧장 들어갑니다. 유휴 서브에이전트에 메시지를 보내면 맥락을 유지한 채 다시 깨어납니다. IDE 작성창의 "Ask anything, @ to mention, / for workflows" 힌트는 컨텍스트를 프롬프트로 끌어오는 더 오래된 @ 멘션입니다. 관련은 있지만 같은 메커니즘은 아닙니다.
내부에서는 부모가 역할과 초기 프롬프트, 그리고 워크스페이스 모드를 더해 invoke_subagent를 호출합니다. inherit(같은 워크스페이스), branch(격리된 Git worktree), share(공유 디렉터리) 셋 중 하나. 중첩은 10단계까지이며, v2.6.0부터는 서브에이전트를 정지하면 그것이 낳은 것들도 모두 정지됩니다. 자신만의 전문가를 원한다면 Antigravity 커스텀 에이전트 튜토리얼이 Markdown + YAML 프론트매터 형식을 다룹니다.
브라우저 서브에이전트가 안 돌아가나요? 다섯 가지 점검으로 해결
"브라우저 서브에이전트가 안 돌아간다"는 보고 대부분은 아래 다섯 가지 중 하나로 수렴합니다. 위에서 아래로 차례로 확인하세요.
- 1먼저 업데이트부터. 실행 중/대기 중/완료 상태의 서브에이전트 카드는 v2.16.0(2026년 9월 22일)부터 존재합니다. 구버전 빌드에서는 서브에이전트가 배경에서 보이지 않게 돌았습니다. 무언가 고장났다고 결론 내리기 전에 데스크톱 앱을 최신으로, CLI는 1.2.9 이상으로 올리세요.
- 2Browser Tools 토글 확인. Antigravity의 브라우저 도구는 User Settings의 Browser 섹션에서 완전히 끌 수 있습니다. /browser가 아무것도 하지 않거나 에이전트가 브라우저를 쓸 수 없다고 주장하면 토글이 켜져 있는지 확인하세요. 공식 문서는 이 스위치를 문서화하지만 더 깊은 문제 해결 매트릭스는 공개하지 않습니다.
- 3텅 빈 낯선 Chrome 창은 설계대로입니다. 브라우저 서브에이전트는 개인 데이터를 보호하려고 별도의 Chrome 프로필을 조작하므로, 확장 프로그램·로그인·북마크는 기대하지 마세요. 로그인 세션이 필요한 작업이라면 내 프로필이 나타나기를 기다리지 말고 자격 증명을 어떻게 다룰지 에이전트에게 알려 주세요.
- 4관리되는 머신이라면: v2.6.0은 "조직이 툴 서버 실행을 제한할 때 내장 브라우저 검사 도구가 잘못 차단되는" 문제를 수정했습니다. 회사 관리 기기에서 브라우저 동작이 막힌다면 그 체인지로그 항목이나 정책 예외가 범인일 가능성이 큽니다.
- 5출력 없이 멈춤: 공식 서브에이전트 문서는 알려진 문제로, 서브에이전트의 도구 목록에 매핑되지 않았거나 철자가 틀린 도구 이름이 실행 중 프로세스를 멈추게 할 수 있다고 경고합니다. running 상태에 도구 호출이 0인 서브에이전트는 이 시그니처와 일치합니다. 모든 도구 이름의 철자를 확인하세요(스키마 검증 수정이 약속되어 있습니다).
여전히 멈춰 있나요? 공식 문서는 더 넓은 문제 해결 매트릭스를 공개하지 않습니다. 워크스루 녹화를 첨부해 문제를 재현한 뒤 앱의 Provide Feedback을 사용하세요. 같은 증상의 커뮤니티 스레드가 결국 위의 다섯 가지 원인으로 돌아온다는 점도 덧붙입니다.