Antigravity CLI & agents-cli
소개 가이드

GE 라이선스로 쓰는 터미널 AI 에이전트와 에이전트 개발 도구.
설치부터 첫 실습, 비용이 생기는 지점까지 한 번에 확인하세요.

Antigravity CLI 시작하기 →agents-cli 알아보기비용 발생 지점
v0.5 (초안) · 2026.09.29아주헬스케어그룹 임직원용 · 초급 엔지니어agy v1.2.12 · agents-cli v1.7.0 · Windows 11원문 작성 · 유클릭스 ADC

화면 이미지는 Windows 11 (PowerShell) 실제 실행 화면이며 계정 정보는 흐리게 처리했습니다. 버전·가격은 2026-09-29 공식 문서 기준입니다.

처음이라면 여기부터

한눈에 보기 · 두 도구 비교

Gemini Enterprise(GE) 업무에서 쓰는 터미널 도구 2가지가 무엇인지, 어떻게 설치하는지, 어디에 쓰는지 소개합니다.

도구 비교
도구한 줄 정의GE 라이선스로 사용추천 대상
Antigravity CLI (agy)터미널에서 AI 에이전트에게 파일 읽기·작성, 명령 실행을 시키는 프로그램가능 (GE에 포함된 유일한 CLI)GE 라이선스를 쓰는 개발자·엔지니어
agents-cli코딩 에이전트가 Google Cloud용 AI 에이전트를 만들고, 배포하고, GE에 등록하도록 돕는 명령어 도구와 작업 지침(Skills) 묶음해당 없음 (무료 도구. 모델 호출·배포 비용은 별도)GE에 올릴 AI 에이전트를 개발하는 엔지니어
사용자 요청→Antigravity CLI
코딩 에이전트＋agents-cli
도구 · Skills→ADK 에이전트 작성 · 평가 · 배포→GE에 등록
TIP · 두 도구의 관계Antigravity CLI는 사용자의 요청을 받아 직접 작업하는 AI 프로그램입니다. 이런 프로그램을 ‘코딩 에이전트’라고 부릅니다. agents-cli는 코딩 에이전트가 아닙니다. Antigravity 같은 코딩 에이전트에 설치하는 도구와 작업 지침 묶음이며, 코딩 에이전트가 Google Cloud용 AI 에이전트를 만들 수 있게 해 줍니다.
라이선스별 제공량과 초과 비용GE 라이선스별 제공량과 초과 비용은 「Antigravity 업무 활용 가이드」의 GE 라이선스 제공 사용량과 비용 항목을 참고합니다.
↑ 목차로 돌아가기
기본 개념

용어 정리

터미널 작업이 처음이라면 아래 용어부터 확인하세요.

용어뜻
CLICommand Line Interface. 마우스 대신 터미널에 명령어를 입력해 쓰는 프로그램
터미널 / PowerShell명령어를 입력하는 창. Windows에서는 시작 메뉴에서 ‘PowerShell’을 검색해 엽니다.
코딩 에이전트요청을 받아 파일 작성·수정, 명령 실행을 직접 하는 AI 프로그램 (Antigravity, Claude Code 등)
GEGemini Enterprise. 회사용 Google AI 서비스. Standard, Plus 등 에디션에 Antigravity가 포함됨
ADKAgent Development Kit. Google이 만든 AI 에이전트 개발용 Python 라이브러리
Skills(스킬)특정 작업을 하는 방법을 적어 둔 지침 파일. 코딩 에이전트가 필요할 때 읽고 따라 합니다.
API Key프로그램이 AI 모델을 호출할 때 쓰는 비밀 인증 문자열. 사용량만큼 요금이 청구되며, 비밀번호처럼 관리해야 함
uv / uvxPython 프로그램 설치 도구 / 설치하지 않고 한 번 실행하는 명령
npxNode.js 프로그램을 설치하지 않고 한 번 실행하는 명령
↑ 목차로 돌아가기
Antigravity CLI

Antigravity CLI란? · 설치

Antigravity CLI(명령어 agy)는 Antigravity를 터미널에서 쓰는 프로그램입니다. 데스크톱 앱과 같은 AI 에이전트를 쓰고, 로그인 정보와 설정도 공유합니다.

GE 라이선스에 포함되어 있으므로, 회사 계정으로 로그인하면 추가 라이선스나 API Key 없이 GE 제공량 안에서 사용할 수 있습니다.

설치

PowerShell을 열고 아래 명령 한 줄을 실행합니다. 별도로 준비할 프로그램은 없습니다.

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

설치 스크립트는 Google 서버에서 agy.exe를 내려받아 파일이 변조되지 않았는지(SHA-512 값) 확인한 뒤, 사용자 폴더(%LOCALAPPDATA%\agy\bin)에 설치하고 PATH(명령어 검색 경로)에 등록합니다. 관리자 권한은 필요하지 않습니다.

[그림 1] 설치 결과 — 'Antigravity CLI binary placed successfully'가 나오면 설치 완료
실제 실행 화면
참고 · 설치 화면의 ‘ERROR: logging before google.Init’ 문구설치 과정을 기록하는 로그 문구이며 오류가 아닙니다. 마지막 줄에 설치 완료 메시지(체크 표시)가 나오면 정상입니다. 설치 직후에는 현재 PowerShell 창에서 agy 명령을 찾지 못할 수 있습니다. PowerShell 창을 닫고 새로 연 뒤 사용합니다.
↑ 목차로 돌아가기
Antigravity CLI

첫 실행

새 PowerShell 창에서 작업할 폴더로 이동한 뒤 agy를 실행합니다. 방향키(↑/↓)로 고르고 Enter로 확정합니다.

PowerShell
cd C:\Users\<내 Windows 사용자 이름>\weekly-report
agy
1

화면 색상 선택

기본값(terminal)을 그대로 두고 Enter를 누릅니다.

2

로그인

Antigravity 2.0 데스크톱 앱에 회사 계정으로 로그인되어 있으면 이 단계는 자동으로 넘어갑니다. 로그인되어 있지 않으면 브라우저가 열리며, Business account → Continue with Google Cloud를 선택하고 회사 계정으로 로그인한 뒤 GE 라이선스를 선택합니다.

3

약관 확인 (Terms of Service & Data Use)

AI 에이전트의 보안 위험 안내와 Google Cloud 약관 링크를 확인하고 Done에서 Enter를 누릅니다.

4

폴더 신뢰 확인

이 폴더의 파일을 에이전트가 읽고, 수정하고, 실행해도 되는지 묻습니다. 직접 만든 업무 폴더면 Yes, I trust this folder를 선택합니다. 출처를 모르는 폴더는 No, exit를 선택합니다.

[그림 2] 약관 확인 화면 — 내용 확인 후 Done 선택
[그림 3] 폴더 신뢰 확인 — 직접 만든 업무 폴더만 Yes 선택
경로 일부 흐림 처리

설정이 끝나면 메인 화면이 나옵니다. 상단에 버전, 로그인한 회사 계정과 라이선스 종류, GE 프로젝트, 사용 모델, 작업 폴더가 표시되고, 가운데 > 줄에 요청을 입력합니다.

[그림 4] 메인 화면 — 위: 계정·라이선스·모델·작업 폴더 정보 / 아래: 요청 입력줄
계정 정보 흐림 처리
↑ 목차로 돌아가기
Antigravity CLI · 실습

실습 · 메모 파일 요약하기

가장 간단한 기능인 파일 읽고 요약하기를 실습합니다. memo.txt는 「Antigravity 업무 활용 가이드」 실습에서 만든 메모 파일입니다.

1

요청 입력

> 입력줄에 아래 문장을 입력하고 Enter를 누릅니다.

2

결과 확인

에이전트가 memo.txt를 읽고(Read) 요약 결과를 화면에 보여 줍니다. 파일은 수정하지 않습니다.

요청 문장
memo.txt를 읽고 이번 주 업무를 3줄로 요약해줘
[그림 5] 실습 결과 — 요청(위 빨간 상자)과 3줄 요약 결과(아래 빨간 상자)
실제 실행 화면
결과 화면 읽는 법
화면 표시의미
Thought for 3s, 95 tokens에이전트가 작업 방법을 생각한 시간과 사용한 토큰(처리량) 수
Read(~/weekly-report/memo.txt)에이전트가 memo.txt 파일을 읽었다는 기록. Ctrl+O를 누르면 자세히 볼 수 있음
1. / 2. / 3.요청한 3줄 요약 결과
TIP · 종료와 도움말종료: 입력줄에 /exit를 입력하거나 Ctrl+D를 누릅니다.
도움말: 입력줄에 ?를 입력하면 명령어와 단축키 목록이 나옵니다.
주의 · API Key로 실행하는 방법은 사용하지 않습니다Antigravity CLI는 Gemini API Key로도 실행할 수 있지만, 이 경우 GE 라이선스가 아니라 API Key 요금으로 사용됩니다. 업무에는 회사 계정 로그인을 사용하고, API Key가 꼭 필요하면 사용 시 주의사항의 협의 절차를 따릅니다.
↑ 목차로 돌아가기
agents-cli

agents-cli란?

agents-cli(정식 이름 Agents CLI in Agent Platform)는 Google Cloud용 AI 에이전트를 만들 때 쓰는 명령어 도구와 작업 지침(Skills) 묶음입니다. 무료 오픈소스이며, GE 라이선스와는 관계가 없습니다.

Antigravity 같은 코딩 에이전트에 설치하면, 코딩 에이전트가 다음 과정을 직접 수행할 수 있게 됩니다. GE 공식 문서도 ADK 에이전트를 GE에 등록하는 방법으로 agents-cli 명령을 안내합니다.

ADK로 에이전트 코드 작성→품질 평가→Google Cloud에 배포→GE에 등록
[그림 6] agents-cli GitHub 페이지 (github.com/google/agents-cli)
agents-cli 구성
구성내용
명령어create(프로젝트 생성), run(실행), eval(평가), deploy(배포), publish(GE 등록) 등
Skills 7종
  • workflow: 개발 순서와 규칙
  • adk-code: ADK 코드 작성법
  • scaffold: 프로젝트 생성·배포 설정 추가
  • eval: 품질 평가 방법
  • deploy: 배포 방법
  • publish: GE 등록 방법
  • observability: 운영 중 로그·추적 확인 방법
함께 쓰는 코딩 에이전트Antigravity CLI, Antigravity 2.0, Claude Code, Codex, Cursor 등
↑ 목차로 돌아가기
agents-cli

사전 준비와 설치

Python·uv·Node.js를 준비한 뒤 명령 한 줄로 설치합니다. 회사 PC에서 설치가 막혀 있으면 IT 담당자(디지털혁신팀)에게 요청하세요.

사전 준비

필요한 프로그램설치 여부 확인 명령설치 방법
Python 3.11 이상python --versionpython.org/downloads ↗ (설치 화면에서 ‘Add python.exe to PATH’ 체크)
uvuv --versionPowerShell에서 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Node.jsnode -vnodejs.org ↗에서 LTS 버전 설치
[그림 7] 사전 준비 확인
실제 실행 결과

설치

아래 명령은 다음 3가지를 차례로 실행합니다.

1

agents-cli 설치

agents-cli 명령어 프로그램을 설치합니다.

2

Skills 설치

PC에 설치된 코딩 에이전트(Antigravity, Claude Code 등)를 찾아 Skills를 설치합니다.

3

로그인 설정

Google Cloud 또는 AI Studio 로그인 설정을 진행합니다.

PowerShell
# 먼저 무엇이 설치될지 확인 (PC에 아무것도 설치하지 않음)
uvx google-agents-cli setup --dry-run --skip-auth

# 실제 설치
uvx google-agents-cli setup
[그림 8] setup --dry-run 결과 — 설치될 항목 미리보기
실제 실행 결과
setup 주요 옵션
옵션의미
--dry-run설치하지 않고, 설치할 항목만 화면에 보여 줌
--agent <이름>지정한 코딩 에이전트에만 Skills 설치 (예: --agent claude-code)
--workspacePC 전체가 아니라 현재 폴더(프로젝트)에서만 Skills 사용
--skip-auth로그인 설정을 건너뜀. 나중에 agents-cli login -i로 로그인
↑ 목차로 돌아가기
agents-cli · 비용 주의

로그인 방식

agents-cli로 만든 에이전트가 모델을 호출하거나 Google Cloud에 배포되면 비용이 발생합니다. 이 비용은 GE 라이선스 제공량과 별도로 청구됩니다.

agents-cli 로그인 방식
로그인 방식사용 단계비용·권한
Google Cloud 프로젝트
(agents-cli login -i에서 선택)		PC 테스트, 배포, GE 등록 모두 가능
  • 회사 GCP 프로젝트에 모델 사용량·배포 리소스 요금 청구
  • 프로젝트의 API 활성화·배포 권한 필요
AI Studio API KeyPC에서 만들고 테스트하는 단계(create, run, eval)만 가능
  • API Key를 발급한 프로젝트에 사용량만큼 청구
  • 키 발급 권한 필요
중요 · API Key·프로젝트 과금 방식 주의API Key 방식으로 모델을 호출하면 사용량이 GE 라이선스 제공량에서 차감되지 않고, 키를 발급한 Google Cloud 프로젝트에 사용량만큼 별도로 청구됩니다. API Key를 발급하려면 해당 프로젝트에서 API 활성화 권한과 키 생성 권한이 필요합니다. 따라서 API Key를 쓰기 전에 회사 관리자(디지털혁신팀)와 반드시 협의합니다. 과금할 프로젝트, 키 발급·보관·폐기 담당자, 월 예산 한도를 먼저 정합니다.

배포(deploy)와 GE 등록(publish)은 회사 GCP 프로젝트에 리소스를 만들므로, 작업 전에 대상 프로젝트와 권한(GE 등록에는 Gemini Enterprise Admin 역할 필요)을 회사 관리자와 확인합니다.
↑ 목차로 돌아가기
agents-cli · 비용 주의

GCP 비용이 발생하는 지점

agents-cli 도구 자체는 무료입니다. 하지만 에이전트를 만들고 운영하면 아래 단계에서 GCP 비용이 별도로 발생하며, 로그인에 사용한 GCP 프로젝트(또는 API Key를 발급한 프로젝트)에 청구됩니다.

agents-cli 사용 시 GCP 비용 발생 지점
단계비용이 생기는 이유청구 기준 (2026-09-29 공식 가격표)
PC 테스트
run, playground		만든 에이전트가 Gemini 모델을 호출모델 토큰 요금 (예: Gemini 3.8 Flash 100만 토큰당 입력 $0.75 / 출력 $3.75, 2026년 말까지 특가)
평가
eval run		에이전트 답변 생성 + 채점 모델(LLM)이 답변을 채점두 번의 모델 호출 모두 모델 토큰 요금
배포 — Agent Runtime
deploy		에이전트를 실행하는 컴퓨팅 자원 사용
  • vCPU 1시간당 $0.085, 메모리 1GiB·시간당 $0.009
  • 계정당 매월 vCPU 50시간·메모리 100GiB·시간까지 무료
  • 대화 사이 대기 시간은 청구하지 않음
  • 세션(대화 기록)·Memory Bank 저장과 읽기·쓰기는 2026-09-01부터 별도 청구
배포 — Cloud Run / GKE
deploy		선택한 실행 환경의 자원 사용Cloud Run, GKE 각 서비스 요금. 컨테이너 빌드(Cloud Build)와 이미지 보관(Artifact Registry) 요금이 함께 발생할 수 있음
모니터링추적 기록이 Cloud Trace로 자동 전송 (기본 켜짐)Cloud Trace·Cloud Logging 무료 사용량을 넘으면 청구
인프라 구성
infra single-project, infra cicd		로그 저장용 Cloud Storage 버킷, BigQuery 데이터 세트, 서비스 계정, 자동 배포(CI/CD) 환경 생성Cloud Storage·BigQuery 저장·조회 요금, Cloud Build 요금
GE 등록 후 운영
publish		직원이 GE에서 에이전트를 쓸 때마다 모델 호출과 에이전트 실행위 모델 토큰 요금 + 실행 환경 요금이 계속 발생
참고 · 근거 (공식 문서)
  • agents-cli README: 에이전트를 배포하면 사용자의 GCP 프로젝트에 리소스가 만들어지며, 그 리소스에 대한 책임은 사용자에게 있다고 안내합니다.
  • agents-cli 인증 문서: 배포에는 결제가 활성화된 GCP 프로젝트와 IAM 권한이 필요합니다.
  • agents-cli 관측 문서: 모든 프로젝트는 Cloud Trace로 추적 기록을 자동 전송합니다.
  • Agent Platform 가격표: Agent Runtime은 vCPU·메모리 사용 시간으로 청구합니다.
↑ 목차로 돌아가기
agents-cli

주요 명령어

개발 단계별로 쓰는 명령입니다. 직접 입력해도 되지만, 보통은 코딩 에이전트가 대신 실행합니다.

[그림 9] agents-cli --help 결과 (v1.7.0)
개발 단계별 명령
단계명령하는 일
로그인agents-cli login -iGoogle Cloud 또는 AI Studio 로그인. agents-cli login --status로 로그인 상태 확인
생성agents-cli create my-agent기본 코드와 폴더 구조를 갖춘 새 에이전트 프로젝트 생성. --prototype을 붙이면 배포·자동화 설정 없이 최소 구성으로 생성
실행agents-cli run "질문"만든 에이전트에게 질문을 한 번 보내 답변 확인
화면 테스트agents-cli playgroundPC에서 웹 브라우저 채팅 화면을 열어 에이전트와 대화 테스트
평가agents-cli eval run미리 만든 ‘질문과 기대 답변 목록’으로 에이전트 답변 품질을 채점
배포agents-cli deploy에이전트를 Google Cloud(Agent Runtime, Cloud Run, GKE 중 선택)에 올려 인터넷으로 호출할 수 있게 함
등록agents-cli publish gemini-enterprise배포한 에이전트를 GE에 등록해 직원들이 GE 화면에서 쓰게 함
↑ 목차로 돌아가기
agents-cli · 활용

사용 방법 — 코딩 에이전트에게 요청하기

agents-cli는 주로 코딩 에이전트에게 말로 요청하는 방식으로 씁니다. Skills가 설치된 Antigravity에 아래처럼 요청하면, 코딩 에이전트가 필요한 agents-cli 명령을 대신 실행합니다.

에이전트 만들기

요청 예시
agents-cli로 사내 규정 질문에 답하는 간단한 에이전트를 만들어줘
  • 사용자에게 요구사항을 질문하고 정리
  • agents-cli create <이름> --prototype으로 프로젝트 생성
  • app/agent.py 파일에 에이전트 코드 작성
  • agents-cli run으로 동작 확인

평가하기

요청 예시
평가 데이터를 만들고 평가를 실행해줘
  • 질문과 기대 답변 목록 파일 작성
  • agents-cli eval run으로 채점하고, 점수가 낮은 항목은 에이전트 지침을 고쳐 다시 채점

배포하기

요청 예시
Agent Runtime 에 배포해줘
  • agents-cli scaffold enhance로 배포 설정 파일 추가
  • agents-cli deploy로 배포

GE에 등록하기

요청 예시
Gemini Enterprise 에 등록해줘
  • agents-cli publish gemini-enterprise로 회사 GE에 에이전트 등록
배포·등록 요청은 실행 전에 반드시 사람이 확인합니다“배포해줘”라고 요청하면 코딩 에이전트가 agents-cli deploy를 직접 실행하고, 회사 GCP 프로젝트에 비용이 발생합니다. 대상 프로젝트와 비용을 확인한 뒤 허용하세요.

에이전트 코드 예시

코딩 에이전트가 작성하는 에이전트 코드(app/agent.py)는 아래와 비슷한 형태입니다.

app/agent.py (예시)
# app/agent.py
from google.adk.agents import Agent

root_agent = Agent(
    # 에이전트 이름
    name="faq_agent",
    # 사용할 모델
    model="gemini-3.8-flash",
    # 에이전트가 따를 지침
    instruction="당신은 사내 규정 안내 담당입니다. "
                "모르는 내용은 담당 부서를 안내하세요.",
)
↑ 목차로 돌아가기
안전하게 쓰기

사용 시 주의사항

API Key, GCP 비용, 리소스 정리, 권한 설정은 반드시 지켜야 할 항목입니다.

구분지켜야 할 것
API KeyAPI Key 방식으로 모델을 호출하면 사용량이 GE 라이선스 제공량에서 차감되지 않고, 키를 발급한 Google Cloud 프로젝트에 사용량만큼 별도로 청구됩니다. API Key를 발급하려면 해당 프로젝트에서 API 활성화 권한과 키 생성 권한이 필요합니다. API Key를 쓰기 전에 회사 관리자(디지털혁신팀)와 반드시 협의하고, 과금할 프로젝트, 키 발급·보관·폐기 담당자, 월 예산 한도를 먼저 정합니다.
GCP 비용
  • agents-cli 도구는 무료지만, 에이전트를 개발·평가·배포하면 GCP 프로젝트에 별도 요금이 청구되며 GE 라이선스 제공량에서 차감되지 않습니다 (비용 발생 지점 참고).
  • 작업 전에 회사 관리자와 과금할 GCP 프로젝트를 협의하고, Cloud Billing에 예산 알림을 설정합니다.
  • eval run은 답변 생성과 채점 모델 호출이 함께 일어나므로, 평가 데이터가 많을수록 모델 요금이 늘어납니다.
  • 배포한 에이전트는 GE에서 직원이 사용할 때마다 모델 호출·실행 요금이 계속 청구됩니다.
  • 배포·인프라 명령(deploy, infra)은 실행 전에 반드시 사람이 확인합니다.
리소스 정리실습이 끝나면 만든 리소스를 직접 삭제합니다. agents-cli에는 정리(삭제) 명령이 없으므로 Google Cloud 콘솔이나 gcloud로 삭제합니다.
  • Agent Runtime 에이전트 또는 Cloud Run 서비스·GKE 클러스터
  • 로그 저장용 Cloud Storage 버킷, BigQuery 데이터 세트
  • 컨테이너 이미지(Artifact Registry)
  • GE에 등록한 에이전트
폴더 신뢰Antigravity CLI 첫 실행 시 폴더 신뢰 확인에서, 인터넷에서 받은 코드처럼 출처를 모르는 폴더는 No, exit를 선택합니다. 폴더 안의 설정 파일이 명령을 실행할 수 있습니다.
권한모든 권한 요청을 자동으로 허용하는 옵션(--dangerously-skip-permissions)은 사용하지 않습니다.
키 보관API Key는 코드 파일, 문서, Git 저장소에 적지 않습니다. 환경변수나 Google Cloud Secret Manager(비밀값 저장 서비스)에 보관하고, 사용이 끝나면 폐기합니다.
설치 범위agents-cli setup은 PC에 있는 모든 코딩 에이전트에 Skills를 설치합니다. --dry-run으로 먼저 확인하고, 필요하면 --agent나 --workspace로 설치 범위를 줄입니다.
회사 정책고객 데이터와 개인정보는 입력하지 않습니다. 회사가 정한 계정·프로젝트만 사용합니다.
↑ 목차로 돌아가기
↑