한눈에 보기
- 이 글에서 안티그래비티 CLI(agy)의 서브에이전트가 무엇인지, /agents 화면으로 보고 끄는 법, agent.md 한 장으로 직접 만드는 법을 공식 문서대로 옮기고 클로드 코드·코덱스와 표로 비교했어요.
- 결론 큰 일은 agy 가 알아서 서브에이전트에게 나눠 맡겨요. 나는 /agents 로 지켜보다가 멈추고(K), 자주 맡기는 일은 .agents/agents/이름/agent.md 로 만들어 두면 돼요.
- 주의 서브에이전트도 부모의 허락 규칙을 물려받고, 허락이 필요하면 내 화면으로 물어 와요. 단축키·이름은 문서 쪽마다 조금씩 달라요.
- 읽는 법 “처음이라면” 두 절이면 보는 법까지, “익숙해졌다면”은 만들기, “더 깊이”는 프론트매터 필드·권한·/boost 예요.
이 글 순서
agy 에게 “이 폴더 전체를 훑어보고 고칠 곳을 찾아 줘” 같은 큰 일을 맡기면, 화면 아래쪽에 낯선 이름의 작업이 몇 개씩 따로 돌아가는 걸 보게 돼요. 그게 서브에이전트예요. 처음 보면 무엇이 도는지, 멈춰도 되는지, 돈(한도)을 더 쓰는지 헷갈리기 쉬워요. 이 글은 그 질문을 처음 보는 분 눈높이에서 차례로 풀었어요.
이 글은 안티그래비티 공식 문서 Custom subagents, Agents command(/agents), Antigravity CLI features, CLI reference, Boost, Teamwork, Plans, FAQ, Changelog 를 2026년 10월 9일에 읽고 옮긴 거예요. 비교하려고 클로드 코드 공식 문서 “사용자 정의 subagent 만들기”와 OpenAI 코덱스 문서 Subagents 도 같은 날 읽었어요. 문서는 모두 영어라 메뉴·명령 이름은 영어 그대로 두었어요. 로그인해야 보이는 agy 화면은 찍지 않았고, 공식 문서 글줄 캡처와 문서 내용으로 그린 정리 그림을 넣었어요. 문서에 없는 것은 “공식 안내 없음”이나 “미확인”으로 적었어요.
하나 먼저 밝혀 둘 게 있어요. Custom subagents 문서는 위쪽에 Antigravity 2.0(데스크톱 앱)·Antigravity CLI 두 탭이 있어요. 띄우는 방식, 내장 셋, 파일 위치 표, 프론트매터 표, 10층 제한, 권한 물려받기는 2.0 탭에 적혀 있고, CLI 탭에는 /agents 화면·/tasks·단축키와 “프론트매터 필드 전체는 Custom subagents 절을 보라”는 안내가 있어요. CLI 탭이 그쪽을 가리키니 이 글은 2.0 탭 내용도 CLI 에 쓰이는 것으로 옮기되, 그림 설명에 어느 탭인지 적었어요. CLI 만 다루는 Agents command·CLI features 문서와 겹치는 것은 그 문서 쪽을 앞에 두었어요.
서브에이전트가 뭔가요
먼저 단어 둘만 풀고 갈게요. 에이전트는 내 요청을 받아 파일을 읽고, 고치고, 명령을 돌리며 일을 끝까지 해 주는 AI 예요. agy 를 켜고 말을 거는 상대가 메인 에이전트(문서 표현으로 parent agent, primary agent)예요. 서브에이전트는 메인 에이전트가 일을 쪼개서 따로 맡기는 작은 에이전트예요. 팀장이 큰 일을 받아 팀원 몇에게 한 조각씩 나눠 주고, 팀원은 끝나면 보고만 올리는 모습과 비슷해요.
왜 굳이 나누는지는 문서 첫 문단에 적혀 있어요. 여러 파일을 한꺼번에 만들거나, 넓게 조사하는 일을 뒤에서 나란히 돌리는 동안 나는 하던 일을 계속하라는 거예요.
그림 속 “Context isolation” 줄이 가장 중요해요. 컨텍스트는 AI 가 지금 대화에서 기억하고 있는 글의 양이에요. 서브에이전트는 메인 대화의 기록을 물려받지 않고 빈 상태로 시작해요. CLI features 문서도 서브에이전트를 “메인 대화와 나란히 도는 따로 떨어진 대화”라고 적었어요. 그래서 메인 대화가 조사 기록으로 꽉 차지 않고, 서브에이전트가 돌려준 결과만 메인 대화에 남아요. 반대로 말하면 서브에이전트는 내가 메인 대화에서 한 말을 모르니, 맡길 때 필요한 것을 프롬프트에 다 적어 줘야 해요.
“Workspace options” 의 셋은 서브에이전트가 일할 폴더를 정하는 방식이에요. inherit 는 메인 에이전트와 같은 폴더, branch 는 깃 워크트리를 새로 만들어 따로 일하는 것, share 는 폴더 저장 공간을 공유하는 것이라고 적혀 있어요. 깃(Git)은 파일을 수정한 기록을 차례로 남겨 두는 프로그램이고, 깃 워크트리(Git worktree)는 같은 프로젝트를 다른 폴더에 한 벌 더 펼쳐 두는 깃 기능이에요. 원본 책상은 그대로 두고 옆 책상에 복사본을 펴 놓고 고치는 것과 같아서, 서로 같은 파일을 동시에 고치다 부딪칠 일이 줄어요.
한국에서, 무료로 되나
| 질문 | 답 |
|---|---|
| 한국에서 되나 | 됨(FAQ 나라 목록에 South Korea) |
| 서브에이전트 요금제 | Plans: 모든 요금제에 CLI 를 포함한 모든 기능 |
| /boost·/teamwork-preview | 유료 요금제(문서끼리 이름이 다름, 아래) |
| 직접 만드는 agent.md | CLI 1.1.6(7월 24일)에 생김 |
출처: 안티그래비티 문서 FAQ·Plans·Custom subagents·Boost·Teamwork·Changelog. 10월 9일 확인. 서브에이전트만 따로 요금제를 가린다는 문장은 찾지 못했어요. 한도는 Plans 문서가 “에이전트가 한 일의 양”에 따라 빠진다고만 적었고, 서브에이전트를 쓰면 얼마나 더 빠지는지 숫자는 없어요(미확인). 토큰은 AI 가 글을 읽고 쓰는 양을 세는 단어 조각 단위예요. 코덱스 문서는 서브에이전트마다 모델 일을 따로 하니 토큰을 더 쓴다고 밝혀 두었는데, 같은 이치라고 보면 무리가 없어요. 남은 양은 agy 안의 /usage 로 봐요.
처음이라면: 내장 셋
아무것도 만들지 않아도 agy 에는 서브에이전트가 처음부터 들어 있어요. 문서가 든 것은 셋이에요.
- research: 폴더 속 파일을 둘러보고 구조를 조사하는 역할이에요.
- browser: 따로 떼어 둔 브라우저를 열어 웹 화면을 눌러 보며 시험해요. /browser 명령으로만 불러요.
- self: 지금 대화하는 에이전트를 그대로 한 벌 더 띄운 것이에요. 같은 지시, 같은 도구를 가져요.
바뀐 점 기록(Changelog)에는 넷째도 있어요. CLI 1.2.16(10월 3일)부터 그림을 만들어 달라는 요청은 image-generator 라는 내장 서브에이전트가 맡는다고 적혀 있어요. 서브에이전트 문서의 내장 목록에는 아직 이 이름이 없어요.
호출하는 법은 따로 없어요. 메인 에이전트가 일의 크기를 보고 알아서 띄워요. 문서의 Best practices 는 큰일이라면 메인 에이전트에게 서브에이전트를 나란히 띄우라고 직접 말하라고 권해요. 이렇게 적으면 돼요.
이 폴더의 CSV 파일 다섯 개를 파일마다 서브에이전트 하나씩 맡겨서 빈칸이 있는 줄을 세어 줘. 다 끝나면 파일별로 한 줄씩 모아 줘.한 번에 통째로 시키는 것과 달리 “어떻게 나눌지”, “다 끝날 때까지 기다릴지”, “무엇을 모아 올지”를 같이 적는 게 요령이에요. 이 세 가지는 코덱스 문서가 좋은 서브에이전트 프롬프트의 조건으로 든 것인데, agy 에도 그대로 통하는 이야기라 옮겨 왔어요.
처음이라면: /agents 화면
서브에이전트가 돌기 시작하면 입력 칸에 /agents 를 치고 Enter 를 눌러요. Agent Manager 라는 화면이 열리고, 도는 서브에이전트가 요청별로 묶여 나와요. 줄마다 상태가 running(일하는 중), done(끝남), error(실패), killed(멈춤) 가운데 하나로 떠요.
| 누르는 것 | 하는 일 |
|---|---|
| ↑ ↓ | 줄 옮기기 |
| Enter | 묶음 펼치기, 서브에이전트 자세히 보기 |
| K | 도는 서브에이전트와 그 아래 것까지 멈춤 |
| Esc | 화면 닫기(자세히 보기에서는 목록으로) |
출처: 안티그래비티 문서 Agents command. 10월 9일 확인. 위 그림의 빨간 테두리가 멈추는 키예요. 자세히 보기에서는 그 서브에이전트가 무슨 생각으로 어떤 도구를 불렀는지, 명령 출력까지 다 보여요. 서브에이전트가 같은 일을 뱅뱅 돌거나 너무 오래 걸리면 그 줄에서 K 를 누르면 돼요. 이미 끝난(done) 줄에서 K 를 누르면 아무 일도 없다고 문서의 흔한 실수 표에 적혀 있어요. 끝난 줄은 Enter 로 기록만 봐요.
서브에이전트가 파일을 고치거나 명령을 돌리려고 허락을 구할 때도 있어요. 이때 고르는 길이 셋이에요.
- Alt+J: 허락을 기다리는 다음 서브에이전트의 자세히 보기로 건너가요. 거기서 승인하거나 거절하고 Esc 로 돌아와요.
- Ctrl+K: 입력 칸 바로 위에 뜬 알림(예: Subagent 12 asks to run “npm test”)을 화면을 열지 않고 바로 승인해요.
- /agents 화면 안: 그 줄에서 A 는 승인, D 는 거절이에요.
제 생각에는 처음 쓰는 동안 Ctrl+K 는 아껴 두는 게 맞아요. 알림 한 줄만 보고 승인하게 되니까요. Alt+J 로 건너가 무엇을 하려는지 한 번 읽고 누르는 쪽이 덜 불안해요. agy 가 묻는 권한 확인 창 자체를 읽는 법은 안티그래비티 CLI 사용법 처음부터에 있어요.
익숙해졌다면: 만들기
“CSV 검사는 늘 이 순서로” 처럼 자주 맡기는 일이 생기면 서브에이전트를 직접 만들어 둬요. 만드는 것은 텍스트 파일 한 장(agent.md)이에요. 문서가 정한 위치는 두 곳이에요.
빨간 테두리가 두 자리예요.
- 이 폴더(프로젝트)에서만: 작업 폴더 안의 .agents\agents\이름\agent.md
- 내 PC 의 모든 폴더에서: C:\Users\사용자이름\.gemini\config\agents\이름\agent.md
~ 는 내 사용자 폴더를 줄여 쓴 표시이고, 윈도우에서는 보통 C:\Users\사용자이름 이에요. 처음에는 연습 폴더 안에만 만들어 보세요. 잘못 만들어도 그 폴더를 지우면 끝이에요. 윈도우 PowerShell(파란 명령 창)에서 연습 폴더로 들어간 뒤 이렇게 쳐요.
mkdir .agents\agents\csv-checker
notepad .agents\agents\csv-checker\agent.md첫 줄은 .agents 폴더와 그 안의 agents·csv-checker 폴더를 한 번에 만드는 명령이에요. 둘째 줄은 메모장으로 agent.md 를 여는 명령인데, 파일이 없으니 새로 만들지 물으면 “예”를 눌러요. 폴더 이름을 에이전트 이름과 같게 맞추는 건 /agents 화면 맨 위에 나오는 예시 자리가 그 형식이라서예요.
메모장에는 아래처럼 적어요. 맨 위 — 두 줄 사이가 프론트매터(frontmatter)이에요. 이 파일이 누구인지 적는 라벨 부분이고, 그 아래가 서브에이전트에게 주는 지시예요.
---
name: csv-checker
description: 폴더 속 CSV 파일을 읽고 빈칸이 있는 줄과 똑같은 줄을 세어 보고하는 담당. 파일은 고치지 않는다.
---
너는 표 파일을 검사하는 도우미야.
1. 파일은 읽기만 하고 고치지 않는다.
2. 파일마다 전체 줄 수, 빈칸 줄, 겹친 줄을 센다.
3. 끝에 파일별로 세 줄 안팎의 보고를 쓴다.
name 과 description 두 필드는 꼭 있어야 해요. 특히 description 이 중요해요. 문서는 이 글을 메인 에이전트가 “이 일을 이 서브에이전트에게 맡길까”를 고를 때 읽는다고 적었어요. “CSV 검사”처럼 짧게 적기보다 무엇을 하고 무엇을 하지 않는지까지 한 문장으로 적어 두면 엉뚱한 일에 불려 나가는 일이 줄어요.
저장하고 agy 에서 /agents 를 다시 열면 Available Agents 목록에 csv-checker 가 보여요. 메인 에이전트가 이 에이전트를 언제 호출하는지는 문서가 “description 을 보고 맡길지 고른다”고만 적었어요. 이름을 콕 집어 호출하는 명령은 문서에 없어서, “csv-checker 서브에이전트에게 이 폴더 검사를 맡겨 줘”처럼 이름을 넣어 요청해 보는 게 지금 할 수 있는 방법이에요. 목록에 안 보이면 맨 아래 “막힐 때”를 보세요.
고르기와 말 걸기
직접 만든 에이전트는 서브에이전트로 불리는 것 말고도 쓰는 길이 둘 더 있어요.
- 메인 에이전트로 바꾸기: /agents 화면의 Available Agents 에서 골라 Enter, Esc 로 닫으면 그 에이전트와 대화하게 돼요. 이미 대화 중이었다면 지금 대화를 갈라(fork) 새 대화로 옮겨 가고, 원래 대화는 그대로 남아요.
- 도는 서브에이전트에게 말 걸기: CLI 1.2.9(9월 23일)부터 입력 칸에 @서브에이전트 이름 을 적고 말을 이으면, 메인 에이전트를 거치지 않고 그 서브에이전트 대화로 바로 보내져요. @ 를 치면 도는 것과 끝난 것이 후보로 떠요.
프론트매터에 subagent: false 를 적으면 서브에이전트로는 안 불리고 메인 에이전트로만 고를 수 있고, mainAgent: false 는 그 반대예요. 둘 다 적지 않으면 둘 다 돼요(기본값 true).
더 깊이: 프론트매터 필드
name·description 말고도 프론트매터에 적을 수 있는 필드가 여럿이에요.
| 필드 | 적는 것 | 안 적으면 |
|---|---|---|
| tools | 쓸 도구 이름 목록(view_file 등) | 빈 목록 |
| model | inherit, flash, pro | inherit(부모 따라감) |
| commandExecutionPolicy | off, auto, eager, sandbox | sandbox |
| skills·plugins | 같이 쓸 스킬·플러그인 자리 | 빈 목록 |
출처: 안티그래비티 문서 Custom subagents 의 Frontmatter configuration. 10월 9일 확인. 셋째 줄은 셸 명령(터미널에 치는 명령)을 묻지 않고 돌리는 정도를 정하는 필드인데, 네 값이 각각 어떻게 다른지는 이 문서에 설명이 없어요(미확인). 둘째 줄의 flash 는 빠르고 가벼운 모델, pro 는 더 깊이 생각하는 모델 쪽이에요. 가벼운 검사 담당은 flash 로 두면 한도를 덜 쓸 것으로 보이지만, 얼마나 덜 쓰는지는 문서에 숫자가 없어요.
tools 필드는 조심해야 해요. 문서 표 아래 “알려진 문제”에 도구 이름을 틀리게 적거나 없는 이름을 넣으면 서브에이전트가 멈춘 채 안 돌아올 수 있다고 적혀 있어요. 문서 예시의 이름(view_file, replace_file_content, grep_search, run_command)을 글자 그대로 옮기세요. 그리고 tools 를 비워 두면 어떤 도구를 쓰게 되는지는 문서에 적혀 있지 않아요. /agents 문서의 예시는 tools 없이 name·description 만 적었으니, 처음에는 그 형식으로 시작해도 돼요.
바뀐 점 기록에는 문서 표에 없는 필드도 나와요. 기본 지시와 기본 도구를 끄는 excludeDefaultComponents, 내 스킬·규칙·서브에이전트·MCP 서버(AI 에 바깥 도구를 붙여 주는 연결 프로그램)를 물려받을지 한 번에 정하는 inheritCustomizations, 이 에이전트가 쓸 서브에이전트를 적는 agents, 훅 파일을 적는 hooks 예요. 표에 없는 필드라 이 글에서는 이름만 적어 둬요.
더 깊이: 권한과 층
- 층 제한: 서브에이전트가 또 서브에이전트를 띄울 수 있고, 메인 에이전트 아래로 10층까지만 돼요. 끝없이 불어나는 것을 막으려는 제한이라고 적혀 있어요.
- 물려받는 것: 부모에게 허락된 명령, 파일을 읽고 쓸 수 있는 폴더 범위, 샌드박스 설정이에요. 샌드박스는 명령이 손댈 수 있는 범위를 정해 두는 장치예요.
- 허락 요청: 서브에이전트가 허락이 필요한 일을 만나면 그 요청이 내 화면이나 /agents 화면으로 올라와요.
- 멈춘(killed) 서브에이전트: 다시 깨울 수 없고, 그 서브에이전트용으로 만든 임시 워크트리는 자동으로 지워져요. 대화 기록은 JSONL 파일(한 줄에 기록 하나씩 적는 텍스트 파일)로 남아 나중에 읽을 수 있어요.
위 네 줄은 Custom subagents 문서의 2.0 탭에 있는 내용이에요. CLI 만 다루는 CLI features 문서는 같은 이야기를 조금 다르게, “서브에이전트가 어떤 도구와 권한을 받을지, MCP 도구를 쓸지, 파일을 쓸 수 있는지는 메인 에이전트가 정한다”고 적었어요. 두 문장을 합쳐 읽으면 서브에이전트는 내가 메인 대화에 허락한 범위 안에서, 메인 에이전트가 나눠 준 만큼만 일한다는 뜻이에요.
여기서 얻는 요령이 하나 있어요. 메인 대화에서 “git 으로 시작하는 명령은 묻지 마”라고 허락해 두면 서브에이전트도 그 허락을 같이 써요. 그러니 서브에이전트를 많이 띄우는 일을 맡기기 전에 허락 규칙(/permissions)부터 좁게 다듬어 두는 게 안전해요. CLI 1.2.15(10월 2일) 바뀐 점에는 승인받지 못한 요청을 서브에이전트가 다른 명령이나 스크립트로 돌아가려 하지 않고 그대로 따르게 고쳤다는 줄도 있어요. 규칙 적는 형식은 안티그래비티 CLI 사용법의 “권한 규칙 적기” 절에 있어요.
서브에이전트 말고 그냥 뒤에서 도는 명령(테스트 돌리기, /btw 로 던진 짧은 질문 같은 것)은 /tasks 에 따로 모여요. 거기서 고르고 Enter 를 누르면 그 명령의 출력이 보이고, 멈추지 않는 명령을 끝낼 수도 있어요.
/boost 와 팀워크
서브에이전트를 여러 층으로 크게 묶어 쓰는 명령이 둘 있어요. /boost 는 까다로운 버그나 여러 파일에 걸친 고치기를 몇 초에서 몇 시간 사이에 깊게 파고드는 명령이고, /teamwork-preview 는 몇 시간에서 며칠 걸리는 큰 일을 여러 역할의 에이전트 팀에게 맡기는 명령이에요.
둘 다 유료 요금제에서만 돼요. 다만 그 이름이 문서마다 달라요. Boost 문서와 Teamwork 문서는 “paid plans(유료 요금제)”, 서브에이전트 문서의 /boost 줄은 “Google One AI Premium(Pro 와 Ultra 등급)과 Enterprise”라고 적었어요. Plans 문서가 요금제를 Google AI Pro·Ultra 로 부르는 것과도 이름이 달라서, 어느 요금제가 정확히 들어가는지는 양쪽 문구를 다 적어 두는 데서 멈출게요. Google AI 요금제 값은 제미나이 AI Plus 7,500원으로 되는 것에 표로 있어요.
제 생각에는 처음 몇 주는 이 둘을 쓰지 않는 쪽이 나아요. 에이전트 여럿이 한꺼번에 오래 돌아 한도가 빨리 빠질 수 있고, 일이 어디까지 됐는지 따라가기도 어려워요. 평소 서브에이전트에 익숙해진 뒤 깃으로 되돌릴 수 있는 폴더에서 시험해 보세요.
문서끼리 다른 곳
안티그래비티 문서는 쪽마다 고친 날이 달라서 같은 것을 다르게 적은 곳이 있어요. 어느 쪽이 맞는지 문서가 밝히지 않은 것은 판단하지 않고 양쪽을 적었어요.
| 무엇 | 한쪽 | 다른 쪽 |
|---|---|---|
| 멈추는 키 | Custom subagents: 소문자 k | Agents command: 대문자 K |
| 허락 기다리는 곳으로 | Custom subagents·CLI reference: Alt+J | CLI features: ctrl+j |
| 파일 위치 | Custom subagents: 이름.md 도 됨 | /agents 예시: 이름/agent.md |
| /boost 요금제 | Boost: 유료 요금제 | Custom subagents: Google One AI Premium |
| 내장 목록 | Custom subagents: research·browser·self | 바뀐 점 1.2.16: image-generator 더함 |
출처: 위에 적은 안티그래비티 문서 쪽들과 문서 Changelog 의 Antigravity CLI 탭. 10월 9일 확인. 키가 헷갈리면 agy 안에서 ? 를 눌러 지금 깔린 버전의 도움말로 확인하세요.
막힐 때
- 만든 에이전트가 /agents 에 안 보여요: 파일이 agents 폴더 바로 아래에 있는지 봐요. 문서의 흔한 실수 표가 “설정 폴더 맨 위에 두면 못 찾는다, .agents/agents/이름/agent.md 로 옮겨라”라고 적었어요. 그다음 /agents 를 닫았다 다시 열어요.
- 서브에이전트가 running 인 채 안 끝나요: /agents 에서 그 줄을 열어 무엇을 하는지 보고, 같은 일을 반복하면 K 로 멈춰요. 직접 만든 에이전트라면 tools 필드의 도구 이름이 틀리지 않았는지 봐요.
- 끝났는데 done 대신 Error 로 떠요: CLI 1.3.1(10월 7일)부터 한도나 모델 용량이 모자라 멈춘 서브에이전트는 Error 와 이유를 보여 줘요. /usage 로 남은 양을 봐요.
- 에이전트를 바꿨더니 대화가 새로 생겼어요: 고장이 아니에요. 대화 중에 에이전트를 바꾸면 기록을 지키려고 대화를 갈라요(fork). 문서는 그래서 하던 내용을 잃지 않는다고 적었고, 갈라진 새 대화에서 이어 가라고 권해요. 지난 대화 목록은 /resume 으로 열어요.
- 허락 알림이 계속 떠요: 서브에이전트가 여럿이면 허락도 여럿 와요. 자주 묻는 명령이 정해져 있다면 /permissions 에 그 명령만 허락해 두세요.
클로드 코드·코덱스와 비교하기
같은 일을 하는 Anthropic 의 클로드 코드, OpenAI 의 코덱스 CLI 에도 서브에이전트가 있어요. 세 도구를 오가는 분이 헷갈리기 쉬운 자리부터 나란히 놓았어요.
| 항목 | 안티그래비티 CLI | 클로드 코드 | 코덱스 CLI |
|---|---|---|---|
| 내장 | research, browser, self | Explore, Plan, general-purpose 등 | default, worker, explorer |
| PC 전체 | ~/.gemini/ |
~/.claude/ |
~/.codex/ |
| 이 폴더 | .agents/ |
.claude/ |
.codex/ |
| 파일 형식 | 프론트매터 달린 .md | 프론트매터 달린 .md | TOML(설정 텍스트 파일) |
| 꼭 적을 필드 | name, description | name, description | name, description, developer_instructions |
| 항목 | 안티그래비티 CLI | 클로드 코드 | 코덱스 CLI |
|---|---|---|---|
| 층 제한 | 10층(문서 2.0 탭) | 기본 3층(바꿀 수 있음) | 공식 안내 없음 |
| 한꺼번에 도는 수 | 공식 안내 없음 | 기본 20개 | 설정값, 안 정하면 코덱스가 정함 |
| 도는 것 보기 | /agents 화면 | 입력 칸 아래 서브에이전트 화면 | /agent |
| 허락 요청 | 내 화면·/agents 로 올라옴 | 본 화면에 이름과 함께 뜸 | 승인 창에 출처 표시, o 로 열기 |
출처: 안티그래비티 문서 Custom subagents·Agents command, 클로드 코드 한국어 문서 “사용자 정의 subagent 만들기”, OpenAI 코덱스 문서 Subagents. 모두 10월 9일 확인. 클로드 코드는 지금 버전에서 /agents 를 치면 화면 대신 “클로드에게 부탁하거나 agents 폴더를 직접 고치라”는 알림이 나온다고 문서에 적혀 있어서, 같은 /agents 라도 하는 일이 달라요. 코덱스는 /agents 가 아니라 끝에 s 가 없는 /agent 예요.
가장 크게 갈리는 곳은 누가 띄우기로 정하느냐예요. agy 와 클로드 코드는 메인 에이전트가 알아서도 띄우지만, 코덱스 문서는 지금 CLI 가 “에이전트 둘을 띄워”처럼 직접 요청하거나 AGENTS.md·스킬에 그렇게 적혀 있을 때 띄운다고 적었어요. 파일 형식도 agy 와 클로드 코드는 거의 같아서 클로드 코드에서 쓰던 .md 를 옮겨 쓰기 쉬워 보이지만, 필드 이름이 달라요(클로드 코드는 permissionMode, agy 는 commandExecutionPolicy). 그대로 복사하지 말고 필드를 하나씩 맞춰 보세요. 클로드 코드 쪽 자세한 것은 클로드 코드 서브에이전트 사용법, 셋을 압축·캐시까지 비교한 것은 클로드 코드·코덱스·제미나이 CLI 비교에 있어요.
누구에게 맞을까
여기서부터는 제 생각이에요. agy 를 이제 막 깔았다면 서브에이전트를 직접 만들 필요는 없어요. 메인 에이전트가 알아서 띄우는 것을 /agents 로 들여다보고, 이상하면 K 로 멈추는 것까지만 익혀도 충분해요. 비개발자라면 “파일마다 하나씩 맡겨서 모아 줘” 같은 요청 한 줄이 가장 쓸모 있어요.
같은 검사를 자주 하는 분, 예를 들어 매주 CSV 를 받아 빈칸을 보거나, 코드를 고칠 때마다 같은 순서로 살피는 분이라면 agent.md 를 하나 만들어 두세요. 읽기만 하는 검사 담당부터 만들면 실수해도 파일이 바뀌지 않아요. 코딩을 배우는 분이라면 “고치기 전에 research 서브에이전트로 이 오류가 어디서 나는지 먼저 찾아 줘”처럼 조사와 고치기를 나눠 시키는 연습이 도움이 돼요. 세 회사의 요금제와 한도는 AI 비교 2026에 한 표로 모아 두었어요.
다시 확인할 날짜
- 10월 23일: 문서끼리 다른 곳(k·K, Alt+J·ctrl+j, /boost 요금제 이름, 내장 목록)이 맞춰졌는지.
- 11월 9일: Plans 문서의 요금제별 한도와 서브에이전트 쪽 요금제 문구.
이 글의 내용은 2026년 10월 9일 기준이에요.
같이 보면 좋은 글: 안티그래비티 CLI 사용법 처음부터: @ 로 파일 가리키기, 되돌리기, GEMINI.md 만들기
같이 보면 좋은 글: 제미나이 CLI 스킬 만들기: 안티그래비티 CLI 에서 SKILL.md 한 장으로 /명령까지
같이 보면 좋은 글: 안티그래비티 CLI MCP 서버 붙이는 법: agy mcp add 부터 mcp_config.json·승인까지
같이 보면 좋은 글: 클로드 코드 서브에이전트 사용법: 컨텍스트 아끼기, 만드는 법, 모델 정하기
같이 보면 좋은 글: AI 비교 2026: 클로드·챗GPT·제미나이 요금제·한도·기능 표
참고한 자료
2026년 10월 9일에 확인했어요.
- Custom subagents (안티그래비티 공식 문서, 띄우는 방식·내장 셋·파일 위치·프론트매터 표·10층·권한 물려받기·CLI 탭의 Alt+J·Ctrl+K)
- Agents command (/agents) (안티그래비티 공식 문서, 화면 쓰는 법·예시 자리·K·A·D·흔한 실수)
- Antigravity CLI features (안티그래비티 공식 문서, Subagents in Antigravity CLI·ctrl+j·ctrl+k)
- CLI reference (안티그래비티 공식 문서, /agents·/tasks·/boost·Alt+J·Ctrl+K)
- Best practices (안티그래비티 공식 문서, 서브에이전트를 나란히 띄우라고 말하기)
- Boost deep reasoning (/boost) (안티그래비티 공식 문서, 세 모드 표·유료 요금제)
- Teamwork agent teams (/teamwork-preview) (안티그래비티 공식 문서, 유료 요금제)
- Plans (안티그래비티 공식 문서, 모든 요금제에 CLI 포함·한도는 일한 양에 따라)
- FAQ (안티그래비티 공식 문서, 쓸 수 있는 나라에 South Korea)
- Changelog (안티그래비티 공식 문서 Antigravity CLI 탭, 1.1.6 마크다운 에이전트·1.2.9 @ 로 말 걸기·1.2.15·1.2.16 image-generator·1.3.1 Error 표시)
- 사용자 정의 subagent 만들기 (클로드 코드 공식 한국어 문서, 내장·위치·필수 필드·3층·20개·/agents 알림)
- Subagents (OpenAI 코덱스 공식 문서, 내장 셋·TOML·필수 세 필드·/agent·승인 창의 o·토큰을 더 씀)
광고 · 쿠팡 추천 상품
이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
