플랫폼 아키텍처

Google은 2026년 I/O에서 개발자 에이전트 제품을 4개의 표면(Surface)을 가진 단일 플랫폼으로 통합했습니다.

4개의 제품 표면 #

공유 에이전트 하네스 #

CLI와 2.0은 동일한 에이전트 엔진을 실행합니다. 이는 다음을 의미합니다:

• 설정/권한이 양방향으로 동기화됩니다
• @conversation 드롭다운을 통해 제품 간 대화를 내보낼 수 있습니다
• 핵심 에이전트 개선사항이 모든 표면에 동시에 배포됩니다

제품 비교: Antigravity 2.0 vs IDE vs CLI

Google Antigravity는 동일한 에이전트 하네스를 기반으로 3가지 제품 표면을 제공합니다. 각 제품은 서로 다른 워크플로우에 최적화되어 있으며, 사용 목적에 따라 선택하거나 병행할 수 있습니다.

기능 비교표 #

CLI만의 장점 #

CLI 활용 시나리오 #

시나리오 1: 원격 서버에서 긴급 버그 수정

프로덕션 서버에 SSH로 접속하여 로그를 분석하고 즉시 패치를 적용하는 워크플로우입니다.

# 프로덕션 서버에 SSH 접속
ssh prod-server

# Antigravity CLI 실행 (SSH 인증 자동 감지)
agy

# 에이전트에게 로그 분석 요청
> @/var/log/app/error.log 최근 500 에러의 원인을 분석하고 수정 코드를 제안해주세요

# 수정 후 테스트
> @src/handlers/payment.go 수정된 코드에 대한 유닛 테스트를 작성해주세요

시나리오 2: CI/CD 파이프라인에 AI 코드 리뷰 통합

GitHub Actions에서 PR에 대한 자동 코드 리뷰를 실행합니다.

# .github/workflows/ai-review.yml
- name: AI Code Review
  run: |
    DIFF=$(git diff origin/main...HEAD)
    agy -p "다음 코드 변경사항을 리뷰해주세요. 버그, 보안 취약점,
    성능 문제를 중심으로 분석하세요: $DIFF" --output-format json

시나리오 3: tmux로 멀티 에이전트 병렬 작업

tmux 세션에서 여러 에이전트를 동시에 실행하여 복잡한 프로젝트를 병렬 처리합니다.

# tmux 세션 생성
tmux new-session -s project

# 패널 1: 메인 에이전트 (인터랙티브)
agy

# 패널 2: 백그라운드 테스트 에이전트 (Ctrl+B, %)
agy -p "@src/ 전체 테스트 커버리지를 80% 이상으로 올려주세요"

# 패널 3: 문서 생성 에이전트 (Ctrl+B, %)
agy -p "@src/ 모든 public 함수에 대한 API 문서를 생성해주세요"

시나리오 4: 빠른 일회성 질문 (커맨드 모드)

TUI를 열지 않고 터미널에서 바로 답변을 받습니다.

# 빠른 질문
agy -p "Go에서 context.WithTimeout과 context.WithDeadline의 차이를 설명해주세요"

# 프로젝트 구조 분석
agy -p "@. 이 프로젝트의 아키텍처를 분석하고 개선점을 제안해주세요"

# JSON 출력으로 스크립트 연동
agy -p "package.json의 취약한 의존성을 찾아주세요" --output-format json

시나리오 5: 서브에이전트로 대규모 리팩토링

메인 에이전트가 전체를 조율하면서, 서브에이전트에게 개별 작업을 위임합니다.

# 메인 에이전트 실행
agy

# 서브에이전트에게 병렬 작업 위임
> /agent refactor "콜백 기반 핸들러를 async/await 패턴으로 변환 @src/handlers/"
> /agent test "변환된 핸들러에 대한 통합 테스트 작성 @src/handlers/"
> /agent docs "리팩토링된 API에 대한 마이그레이션 가이드 작성"

# 진행 상황 모니터링
> /agents

어떤 제품을 선택할까? #

설치

macOS / Linux #

curl -fsSL https://antigravity.google/cli/install.sh | bash

Windows (PowerShell) #

irm https://antigravity.google/cli/install.ps1 | iex

Windows (CMD) #

curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd

설치 확인 #

agy --version

업데이트 #

설치된 CLI를 최신 버전으로 업데이트하려면:

agy update

인증

로컬 인증 플로우 #

첫 실행 시 브라우저에서 Google 로그인 창이 열립니다. 인증 후 자격 증명은 시스템 키링에 안전하게 저장됩니다.

SSH 원격 인증 플로우 #

CLI가 SSH 세션을 자동 감지하여 인증 URL을 출력합니다. 로컬 머신에서 이 URL에 접속하여 인증을 완료하면, 토큰이 SSH 세션에 고정됩니다.

API 키 인증 #

export ANTIGRAVITY_API_KEY=your_api_key_here

영구 설정을 위해 ~/.bashrc 또는 ~/.zshrc에 추가합니다.

지원되는 계정 유형 #

• Google AI Pro
• Google AI Ultra
• Gemini Code Assist (Standard / Enterprise)
• Enterprise GCP 프로젝트

로그아웃 #

/logout

첫 번째 실행

CLI 시작 #

agy

대화 창과 상태 바가 있는 TUI(터미널 사용자 인터페이스)가 실행됩니다.

첫 실행 설정 과정 #

1. Google OAuth 또는 GCP 프로젝트 인증 선택
2. 색상 테마 선호도 설정
3. 이용 약관 동의
4. 워크스페이스 신뢰 확인

프로젝트 검사 #

새 프로젝트에서 가장 먼저 실행하면 유용한 명령어:

agy inspect

발견된 설정 파일, 스킬, 플러그인, 훅, MCP 서버를 보여줍니다.

빠른 시작 예제 #

# 인터랙티브 모드
agy

# 프롬프트에서 다음과 같이 입력:
> CSV 파일을 읽고 요약 구조체를 반환하는 Go 함수를 작성해주세요

# @를 사용하여 파일을 참조:
> @src/main.go 이 파일의 에러 핸들링을 개선해주세요

동작 모드

인터랙티브 에이전트 모드 #

대화 창과 상태 바가 있는 전체 TUI를 실행합니다.

agy

커맨드 모드 #

TUI 없이 단일 프롬프트에 대한 빠른 응답을 받습니다.

# 단일 프롬프트 실행
agy -p "GET 요청을 위한 curl 명령어 문법을 알려주세요"

# JSON 형식 출력 (구조화된 출력)
agy -p "프로젝트 구조를 분석해주세요" --output-format json

비동기 서브에이전트 모드 #

TUI 내에서 백그라운드 작업을 디스패치합니다.

/agent refactor "콜백 기반 핸들러를 context.Context를 사용하도록 변환 @internal/api"

셸 모드 #

!을 입력하면 셸 모드로 전환되어 CLI를 종료하지 않고 시스템 명령을 직접 실행할 수 있습니다. 프롬프트가 >에서 !로 변경됩니다.

슬래시 명령어

Antigravity CLI 프롬프트 창에서 직접 입력하여 대화 관리, 설정 구성, 에이전트 기능을 제어할 수 있습니다.

대화 관리 #

설정 & 구성 #

에이전트 기능 #

모델 선택

사용 가능한 모델 #

agy models 서브커맨드로 사용 가능한 모델 목록을 확인할 수 있습니다.

모델 전환 #

# 세션 중 모델 전환
/model gemini-3.1-pro

# 실행 시 모델 지정
agy --model "gemini-3.1-pro"

파일 참조

@ 문법을 사용하여 워크스페이스 파일을 에이전트 대화에 참조할 수 있습니다.

참조 문법 #

사용 예시 #

# 단일 파일 분석
> @src/main.go 이 파일의 에러 핸들링을 개선해주세요

# 디렉토리 전체 리팩토링
> @internal/api/ 모든 핸들러에 로깅을 추가해주세요

# 글로브 패턴으로 테스트 생성
> @**/*.ts 이 파일들에 대한 유닛 테스트를 작성해주세요

서브에이전트

서브에이전트는 병렬 작업을 위한 포커스된 에이전트를 생성하여 메인 터미널 인터랙션을 유지하면서 백그라운드 작업을 처리합니다.

서브에이전트 생성 #

# 백그라운드 리팩토링 에이전트 실행
/agent refactor "콜백 기반 핸들러를 context.Context를 사용하도록 변환 @internal/api"

# 에이전트 상태 모니터링
/agents

설정 파일

설정 파일 위치 #

~/.gemini/antigravity-cli/settings.json

설정 편집 방법 #

CLI 내에서 /config (또는 별칭 /settings)를 입력하면 전체 화면 설정 편집기 오버레이가 열립니다.

설정 예시 #

{
  "colorScheme": "dark",
  "model": "gemini-3.5-flash-high",
  "permissions": {
    "allow": [
      "read_file(*)",
      "command(git)",
      "command(npm test)"
    ],
    "deny": [
      "command(rm -rf)"
    ]
  },
  "trustedWorkspaces": [
    "/home/user/projects"
  ]
}

설정 항목 #

권한 관리

권한 모드 #

4가지 권한 모드가 에이전트의 자율성 수준을 제어합니다:

세분화된 권한 엔진 #

모든 민감한 작업은 action(target) 형식의 권한 리소스로 표현됩니다.

권한 우선순위 #

권한 설정 예시 #

{
  "permissions": {
    "allow": [
      "read_file(/Users/username/Documents)",
      "command(git)",
      "command(npm test)"
    ],
    "deny": [
      "command(rm -rf)"
    ]
  }
}

OS 레벨 샌드박싱 #

• Linux: nsjail 사용
• macOS: 네이티브 sandbox-exec 사용

YOLO 모드

YOLO(You Only Live Once) 모드는 AI가 확인 없이 자율적으로 실행할 수 있는 모드입니다.

레벨 1: 전체 YOLO 모드 #

agy --dangerously-skip-permissions

모든 도구 승인 및 명령 실행 확인 프롬프트를 완전히 건너뜁니다.

레벨 2: 세분화된 권한 제어 #

/permissions 명령어 또는 settings.json을 수정하여 화이트리스트 방식으로 제어합니다:

{
  "permissions": {
    "allow": [
      "read_file(/Users/username/Documents)",
      "command(git)",
      "command(npm test)"
    ],
    "deny": [
      "command(rm -rf)"
    ]
  }
}

Git 및 테스트 자동화를 허용하면서 rm -rf 같은 파괴적 명령은 차단합니다.

테마 & 상태줄

색상 테마 #

어두운 터미널 배경에서 기본 라이트 테마가 텍스트를 보이지 않게 만들 수 있습니다.

{
  "colorScheme": "dark"
}

상태줄 설정 #

/statusline 명령어로 상태줄을 관리합니다:

커스텀 상태줄 #

라이브 에이전트 메타데이터(CWD, 활성 모델, 토큰 사용량, 상태 등의 JSON 형식)를 커스텀 셸 스크립트로 파이프하여 동적 상태 바 또는 터미널 윈도우 제목을 생성할 수 있습니다.

컨텍스트 파일

Antigravity CLI는 Gemini CLI와 동일한 컨텍스트 파일을 읽습니다.

워크스페이스 레벨 #

• GEMINI.md — 프로젝트 루트에 위치
• AGENTS.md — 프로젝트 루트에 위치

글로벌 레벨 #

• ~/.gemini/GEMINI.md — 모든 워크스페이스에서 자동 로드

AGENTS.md 예시 #

프로젝트 루트에 일반 영어(또는 한국어) 지침을 작성합니다:

항상 TypeScript를 사용하세요. 클래스 기반보다 함수형 패턴을 선호합니다.
`any` 타입은 절대 사용하지 마세요.
src/를 변경할 때마다 `pnpm test`를 실행하세요.

에이전트 스킬

에이전트 스킬은 /skills 명령어로 관리되는 재사용 가능한 에이전트 동작 단위입니다.

스킬 디렉토리 위치 #

스킬 생성 #

마크다운 파일을 .agents/skills/에 저장하여 슬래시 명령으로 사용 가능한 스킬을 만듭니다.

# Lint 스킬

프로젝트의 모든 소스 파일에 대해 린트를 실행합니다.
`eslint .` 명령어를 사용하고 발견된 문제를 수정합니다.
수정 후에는 항상 `npm test`로 테스트를 실행하세요.

이후 /lint로 이 스킬을 실행할 수 있습니다.

훅(Hooks)

JSON으로 정의된 라이프사이클 인터셉터로, Antigravity 2.0과 동일한 JSON 형식을 사용합니다.

지원되는 훅 이벤트 #

• 도구 호출 전 (Before tool call) — 도구가 실행되기 전에 인터셉트
• 파일 편집 후 (After file edit) — 파일이 수정된 후 실행
• 세션 시작 시 (On session start) — 새 세션이 시작될 때 실행

사용 사례 #

• 파일 편집 후 자동 린트/포맷팅 실행
• 도구 호출 전 보안 검사
• 세션 시작 시 환경 초기화

MCP 서버

로컬 및 원격 MCP(Model Context Protocol) 서버를 /mcp 명령어로 관리할 수 있습니다.

설정 파일 위치 #

Gemini CLI와 달리 별도의 설정 파일을 사용합니다 (settings.json에 인라인이 아님):

Gemini CLI와의 차이점 #

서버 유형 #

• 로컬 서버 (stdio) — 로컬 프로세스로 실행
• 원격 서버 (HTTP) — HTTP를 통해 원격 서버에 연결

MCP 서버 목록 탐색 #

다양한 MCP 서버를 검색하고 설치할 수 있는 공식 레지스트리와 커뮤니티 디렉토리를 활용하세요.

인기 MCP 서버 예시 #

Antigravity CLI에서 자주 사용되는 대표적인 MCP 서버 5가지를 소개합니다.

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
  }
}

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": { "GITHUB_TOKEN": "ghp_your_token" }
  }
}

{
  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres",
             "postgresql://user:pass@localhost/mydb"]
  }
}

{
  "brave-search": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": { "BRAVE_API_KEY": "your_api_key" }
  }
}

{
  "google-cloud": {
    "serverUrl": "https://mcp.googleapis.com/v1/cloud-tools",
    "headers": {
      "Authorization": "Bearer $(gcloud auth print-access-token)"
    }
  }
}

플러그인

Gemini CLI의 “확장(Extensions)”은 Antigravity CLI에서 “플러그인(Plugins)”으로 이름이 변경되었습니다.

Gemini CLI 플러그인 가져오기 #

agy plugin import gemini

마이그레이션 결과 예시 #

[ok]    conductor
        - skills      : skipped (not found)
        - agents      : skipped (not found)
        ✔ commands    : 6 processed (converted to skills)
        - mcpServers  : skipped (not found)
        - hooks       : skipped (not found)
[ok]    google-workspace
        ✔ skills      : 6 processed
        - agents      : skipped (not found)
        ✔ commands    : 4 processed (converted to skills)
        ✔ mcpServers  : 1 processed
        - hooks       : skipped (not found)

마이그레이션 가능 항목 #

CLI 플래그

주요 플래그 #

사용 예시 #

# 빠른 질문
agy -p "curl GET 요청 문법을 알려주세요"

# 이전 대화 이어하기
agy -c

# 특정 모델로 실행
agy --model "gemini-3.1-pro"

# 추가 디렉토리 포함
agy --add-dir ./libs --add-dir ./configs

# 샌드박스 모드로 실행
agy --sandbox

스케줄링

/schedule 명령어로 반복 또는 일회성 작업을 자동화합니다.

일회성 타이머 #

최대 900초의 커스텀 프롬프트 타이머를 설정할 수 있습니다.

반복 작업 #

크론(Cron) 표현식으로 지정된 간격의 자동화 작업을 설정합니다.

사용 사례 #

• 포모도로 타이머
• 스탠드업 미팅 준비
• 코드 품질 점검
• 의존성 감사

커스텀 모델

설정 파일 #

model = "gemini-3.1-pro"
base_url = "https://api.example.com"
name = "My Custom Model"
env_key = "CUSTOM_API_KEY"

사용 방법 #

agy -m my-custom-model -p "프롬프트를 입력하세요"

Gemini CLI 마이그레이션

마이그레이션 단계 #

1. Antigravity CLI 설치
2. 플러그인 가져오기: agy plugin import gemini
3. 기존 Gemini CLI에서 수행하던 20분 분량의 작업을 테스트
4. 스킬 디렉토리 마이그레이션 (필요한 경우)

호환 항목 #

• 플러그인/확장 (마이그레이션 도구 제공)
• 에이전트 스킬
• MCP 서버
• JSON 훅
• 다이나믹 서브에이전트
• 컨텍스트 파일 (GEMINI.md, AGENTS.md)
• SSH 인증
• Antigravity 2.0과 설정 동기화
• Antigravity 2.0으로 대화 내보내기

영향 범위 #

보안 고려사항

주요 보안 위험 #

• 자율적 코드 실행 — 에이전트가 의도치 않은 명령을 실행할 수 있음
• 데이터 유출 — 민감한 데이터가 외부로 전송될 수 있음
• 프롬프트 인젝션 — 악의적 입력으로 에이전트 동작이 변경될 수 있음
• 공급망 위험 — 신뢰할 수 없는 패키지 설치 위험

데이터 수집 #

• 설정에서 수집 거부(opt-out) 가능
• 소비자 계층에서는 기본 활성화
• Enterprise는 GCP 프로젝트 정책을 따름

보안 모범 사례 #

1. 가능하면 proceed-in-sandbox 권한 모드를 사용
2. 파괴적 명령을 deny 리스트에 추가
3. 에이전트가 생성한 코드를 프로덕션 배포 전에 반드시 검토
4. 신뢰할 수 없는 워크스페이스에서는 strict 모드 사용

모범 사례

Antigravity CLI를 설치해야 하는 경우 #

• Google AI Pro/Ultra에서 Gemini CLI를 사용 중인 경우 (기한 기반)
• 터미널 우선 또는 tmux 워크플로우
• 원격 서버 개발
• 데스크톱 앱과 공유 하네스를 원하는 경우
• 제품 간 이식 가능한 MCP/스킬이 필요한 경우

아직 필요하지 않은 경우 #

• Code Assist Standard/Enterprise 라이선스를 보유한 경우
• 유료 Gemini API 키를 사용하는 경우
• 시각적 diff 검토, 아티팩트 미리보기, 음성 입력에 의존하는 경우
• 아직 이식되지 않은 Gemini CLI 기능이 필요한 경우

효율적인 사용 팁 #

1. AGENTS.md를 활용하세요 — 프로젝트별 지침으로 에이전트를 안내합니다
2. agy inspect로 시작하세요 — 새 프로젝트의 구성 상태를 파악합니다
3. @ 참조를 적극 활용하세요 — 정확한 컨텍스트를 제공합니다
4. 서브에이전트로 병렬 작업하세요 — 복잡한 작업을 분할합니다
5. 권한을 세밀하게 설정하세요 — 보안과 생산성의 균형을 맞춥니다

기술 사양 요약 #