Antigravity 2.0의 내부 구조 이해하기

Antigravity 2.0은 Google이 제공하는 에이전트형 AI 코딩 어시스턴트입니다. 단순한 챗봇이 아니라 파일 조작·명령 실행·Web 검색·서브 에이전트(Sub-agent) 기동 등을 자율적으로 수행하는 "에이전트"로서 동작합니다.

본 기사에서는 다음과 같은 관점에서 그 내부 메커니즘을 해설합니다.

• 사용자 프롬프트가 어떻게 처리되는가
• LLM은 어디서·어떻게 관여하는가
• 사용할 수 있는 도구(Tool)의 종류와 특성
• 규칙 파일(Rule file: GEMINI.md / AGENTS.md / SKILL)의 역할
• 서브 에이전트와 MCP의 위치 선정

블록 다이어그램

전체 아키텍처

Antigravity 2.0은 크게 3개의 레이어로 구성되어 있습니다.

┌─────────────────────────────────────────┐
│ 📜 규칙 파일 레이어 │
│ GEMINI.md / AGENTS.md / SKILL.md │
...

사용자 프롬프트 처리 흐름

1. 시스템에 의한 컨텍스트 구성 (프로그램 처리)

사용자가 프롬프트를 입력하면, 먼저 시스템(프로그램)이 다음을 구성합니다.

• 시스템 프롬프트 (Antigravity의 동작 지시)
• 규칙 파일의 내용 (GEMINI.md / AGENTS.md)
• 대화 이력
• 환경 정보
• 현재 열려 있는 디렉토리·파일 정보

이는 LLM은 관여하지 않는 순수한 프로그램 처리입니다. 템플릿 방식으로 정보를 묶어 LLM으로의 입력을 구성합니다.

2. LLM에 의한 판단 (LLM 처리)

구성된 컨텍스트를 모두 LLM에 전달합니다. LLM은 여기서:

• 다음 액션 (도구 호출(Tool call) 또는 최종 답변 생성)을 결정합니다.

3. 도구 호출 루프 (LLM ⇔ 시스템의 왕복)

LLM이 "도구를 사용한다"라고 판단한 경우, 도구 이름과 인수를 포함한 명령을 출력합니다.

// LLM이 출력하는 도구 호출 명령의 이미지
{
"tool": "grep_search",
...

시스템이 이 명령을 받아 실제로 실행하고, 그 결과를 컨텍스트에 추가하여 다시 LLM에 전달합니다. LLM은 다시 판단하며——이 LLM → 도구 실행 → LLM으로 복귀의 루프가 에이전트의 핵심입니다.

[사용자 입력]
↓
[시스템: 컨텍스트 구성]
...

규칙 파일의 메커니즘

Antigravity 2.0에는 3종류의 규칙 파일이 있습니다.

GEMINI.md — 에이전트의 "헌법"

LLM에 대한 지시를 Markdown으로 기술하는 파일입니다. 항상 컨텍스트에 주입됩니다.

배치 장소	적용 범위
~/.gemini/GEMINI.md	전 프로젝트 공통 (Global)
[프로젝트 Root]/GEMINI.md	해당 프로젝트만
서브 디렉토리 내의 GEMINI.md
해당 폴더에 액세스했을 때 (JIT)

활용 예시:

# ~/.gemini/GEMINI.md 의 예
- 모든 답변은 일본어로 수행할 것
- 코드 주석도 일본어로 작성할 것
...

AGENTS.md — 크로스 툴 공통 설정

Cursor·Claude Code 등 여러 AI 도구에서 공유하고 싶은 규약을 작성하는 파일입니다. Antigravity 전용이 아니라, 어떤 도구에서도 읽을 수 있는 범용적인 포맷입니다.

SKILL.md — 온디맨드(On-demand)로 읽어오는 전문 절차서

SKILL에 대해서는 "Google Antigravity CLI 무료 범위에서 SKILL을 사용해 보았다!"를 참고해 주세요.

필요할 때만 읽히는 전문 태스크용 절차서입니다.

[LLM이 SKILL.md의 description을 단서로 전문 태스크를 감지]
↓
[view_file (IsSkillFile=true)로 SKILL.md의 본문을 읽음]
...

배치 장소	용도
~/.gemini/skills/	글로벌 스킬
.agent/skills/	프로젝트 고유 스킬

GEMINI.md와의 가장 큰 차이점은 **컨텍스트 절약 (Context Saving)**입니다. 항상 로드되지 않기 때문에 복잡한 절차서도 부담 없이 정의할 수 있습니다.

파일	로드 타이밍	적합한 유스케이스
GEMINI.md	항상	언어 설정·필수 제약
SKILL.md	온디맨드 (On-demand)	Git 조작 절차·보안 감사 등
AGENTS.md	항상 (복수 도구 공통)	프로젝트 규약 공유

도구의 전체 모습

빌트인 도구 (Built-in Tools)

Antigravity가 표준으로 제공하는 도구입니다.

📁 파일 조작 계열

도구	설명	LLM
view_file	파일 내용 읽기 (행 범위 지정 가능)	없음
write_to_file	신규 파일 생성	없음
replace_file_content	단일 블록 교체	없음
multi_replace_file_content	여러 곳을 한 번에 교체	없음
list_dir	디렉토리 목록	없음

🔍 검색 계열

도구	설명	LLM
grep_search	파일 내 패턴 검색 (ripgrep)	없음
search_web	웹 검색 (요약 포함)	있음 (Google Grounding API 사용 여부?)
read_url_content	URL 내용을 Markdown으로 가져오기	없음

💻 명령 실행 계열

도구	설명	LLM
run_command	명령 실행 (사용자 승인 후)	없음
manage_task	백그라운드 태스크 관리	없음
schedule	타이머·정기 실행	없음

🎨 크리에이티브 계열

도구	설명	LLM
generate_image	텍스트로부터 이미지 생성	있음 (이미지 생성 AI)

🤖 서브 에이전트 (Sub-agent) 계열

도구	설명
invoke_subagent	서브 에이전트 호출 (병렬 실행 가능)
define_subagent	새로운 서브 에이전트 타입 정의
manage_subagents	서브 에이전트 목록·강제 종료
send_message	다른 에이전트에게 메시지 전송

🔐 기타

도구	설명
ask_permission	파일 액세스·명령 실행 권한 신청
list_permissions	현재 권한 목록 확인
ask_question	여러 선택지로 사용자에게 질문

서브 에이전트의 메커니즘

서브 에이전트는 도구로서 호출되지만, 내부에 LLM 루프를 가진 특수한 존재입니다.

메인 LLM
↓ 「invoke_subagent를 호출함」 (도구 명령)
시스템: invoke_subagent를 실행
...

사용 가능한 서브 에이전트 종류:

Built-In vs. Custom Subagents

종류	권한	용도
research	읽기 전용	코드베이스 조사·웹 검색 등의 무거운 조사를 병렬로 위임
self	풀 권한 (자신의 클론)	격리된 환경에서의 작업·병렬 실행
커스텀 (define_subagent)	자유롭게 정의	특정 태스크 전용 에이전트 생성

병렬 실행이 가능하기 때문에, 메인이 작업을 계속하면서 조사는 research 에이전트에게 맡기는 식의 효율적인 사용이 가능합니다.

MCP (Model Context Protocol)

MCP란

Anthropic이 책정한 「AI와 도구를 연결하는 표준 규격」입니다. 「AI를 위한 USB-C」라고도 표현됩니다.

빌트인 도구 vs MCP 도구

관점	빌트인 도구 (Built-in Tool)	MCP 도구 (MCP Tool)
제공자	Antigravity가 표준 탑재	사용자/서드파티가 설정
추가 방법	설정 불필요	MCP 설정 파일에 추가 필요
대상	범용 조작	전문적·프라이빗한 리소스
포터빌리티 (Portability)	Antigravity 전용	여러 AI 도구에서 작동

MCP 도구의 활용 예시

GitHub MCP ── Pull Request 생성·Issue 관리
Google Workspace MCP ── Drive·Gmail 조작
DB MCP ── 사내 데이터베이스로의 액세스
...

search_web

은 MCP인가?

정답: MCP가 아니라, 빌트인 도구 (Built-in Tool)입니다.

search_web은 Antigravity에 내장된 표준 기능입니다. 다만, 반환되는 「요약」은 Google의 AI(아마도 Google의 Vertex AI Grounding API)가 생성하고 있기 때문에, 도구 내부에 LLM이 숨겨져 있다는 점에서 다른 빌트인 도구와 다릅니다.

요약

요소	포인트
컨텍스트 (Context) 구성	시스템(프로그램)이 수행한다. LLM은 관여하지 않는다
도구 호출 (Tool Call)	LLM이 명령을 출력하고, 시스템이 실행한다. 결과를 LLM으로 되돌리는 루프
GEMINI.md	상시 주입되는 규칙 파일. 간결하게 유지하는 것이 요령
SKILL.md	온디맨드 (On-demand)로 읽어오는 전문 절차서. 컨텍스트 절약에 유효
서브 에이전트 (Sub-agent)	도구로서 호출되지만 내부에 LLM 루프를 가짐
MCP	Anthropic이 책정한 표준 규격. 사용자가 독자적인 도구를 추가할 수 있는 확장 계층
search_web	빌트인 도구. 루트 내부에서 Google AI가 요약을 생성하는 특수한 케이스

개인적으로 AI 에이전트를 능숙하게 다루기 위해서는 컨텍스트 윈도우 (Context Window)가 중요한 개념이라고 생각하기 때문에, Antigravity 2.0의 매력은 컨텍스트 윈도우에 주목하면 알 수 있습니다! + 「서브 에이전트 만드는 법」을 참고해 주세요.

Discussion