Antigravity CLI 사용
이 페이지에서는 Gemini Enterprise Agent Platform Workbench 인스턴스에서 Antigravity 명령줄 인터페이스 (CLI)를 사용하는 방법을 설명합니다.
이 문서는 Agent Platform Workbench를 사용하는 데이터 분석가, 데이터 과학자, 데이터 개발자를 대상으로 합니다. 이 문서에서는 노트북 환경에서 코드를 작성하는 방법을 알고 있다고 가정합니다.
개요
Antigravity CLI는 터미널에서 실행되는 AI 코딩 에이전트인 Google Antigravity의 터미널 중심 인터페이스입니다. 자세한 내용은 antigravity.google을 참고하세요.
Antigravity CLI는 Agent Platform Workbench 인스턴스의 JupyterLab 인터페이스에 있는 터미널에서 사용할 수 있습니다. 이를 사용하여 자연어로 안내를 제공하여 인스턴스의 노트북 및 파일로 작업하고 셸 명령어와 Google Cloud 명령어를 실행할 수 있습니다.
Agent Platform Workbench는 Antigravity CLI에 다음을 추가합니다.
- 노트북을 만들고, 설명하고, 수정하고, 확인하고, 실행하고, Jupyter 커널을 만드는 노트북 기술
gcloud명령어에 대한 문서 및 안내가 포함된 Google Cloud 플러그인 Google Cloud%%agy셀 매직: 설명에서 노트북 셀의 코드를 작성합니다.
제한사항
Agent Platform Workbench에서 Antigravity CLI를 사용할 때는 다음 제한사항을 고려하세요.
Antigravity CLI는 CLI 전용입니다. 그래픽 채팅 인터페이스와 고급 편집기 내 도구는 포함되지 않습니다.
Antigravity CLI에 노트북을 수정하도록 요청하면 인스턴스 디스크에서 직접 노트북 파일을 변경합니다. 따라서 노트북 편집기의 실행취소 버튼 또는 Control+Z(macOS의 경우 Command+Z)를 사용하여 Antigravity CLI에서 수정한 내용을 실행취소할 수 없습니다. 하지만
Undo your last change와 같은 자연어 명령어를 사용하여 Antigravity CLI에 변경사항을 실행취소하도록 요청할 수 있습니다.Antigravity CLI는 디스크에 직접 쓰고 JupyterLab에서 열려 있는 파일을 변경할 수 있습니다. 노트북에 저장되지 않은 변경사항이 있는 경우 Antigravity CLI에 동일한 노트북을 수정하도록 요청하기 전에 저장하세요.
Antigravity CLI는 인스턴스 이미지에 포함된 버전에 고정되어 있으며 자체적으로 업데이트할 수 없습니다. 최신 버전을 사용하려면 인스턴스를 최신 이미지 버전으로 업그레이드하세요. 자세한 내용은 인스턴스 환경 업그레이드를 참조하세요.
Antigravity CLI는 인스턴스에서 활성 상태인 사용자 인증 정보로 실행됩니다. 기본적으로 이는 Agent Platform Workbench 인스턴스의 서비스 계정 사용자 인증 정보이므로 Antigravity CLI는 인스턴스가 액세스할 수 있는 동일한 리소스에 액세스할 수 있습니다. 인스턴스에서 다른 ID를 인증하는 경우 (예:
gcloud auth login또는gcloud auth application-default login실행) Antigravity CLI는 해당 ID의 권한을 대신 사용합니다.
시작하기 전에
- Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Compute Engine, Notebooks, and Agent Platform APIs, if any are not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Compute Engine, Notebooks, and Agent Platform APIs, if any are not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.
필요한 역할
Agent Platform Workbench에서 Antigravity CLI를 사용하려면 Agent Platform Workbench 인스턴스 사용자 및 인스턴스의 서비스 계정에 권한을 부여해야 합니다.
인스턴스 사용자에게 권한 부여
Agent Platform Workbench 인스턴스에서 Antigravity CLI를 사용하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Agent Platform 사용자 (roles/aiplatform.user) IAM 역할을 부여해 달라고 요청하세요.
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
인스턴스의 서비스 계정에 권한 부여
Agent Platform Workbench 인스턴스의 서비스 계정에 Agent Platform Workbench 인스턴스에서 Antigravity CLI를 실행하는 데 필요한 권한이 있는지 확인하려면 관리자에게 프로젝트의 Agent Platform Workbench 인스턴스 서비스 계정에 Agent Platform 사용자 (roles/aiplatform.user) IAM 역할을 부여해 달라고 요청하세요.
이 사전 정의된 역할에는 Agent Platform Workbench 인스턴스에서 Antigravity CLI를 실행하는 데 필요한 aiplatform.endpoints.predict 권한이 포함되어 있습니다.
관리자는 커스텀 역할이나 다른 사전 정의된 역할을 사용하여 Agent Platform Workbench 인스턴스의 서비스 계정에 이 권한을 부여할 수도 있습니다.
Antigravity CLI 사용 설정
Antigravity CLI는 Debian 12 (workbench-instances-2603) 이상 이미지를 사용하는 Agent Platform Workbench 인스턴스에서만 사용할 수 있습니다. Debian 11 (workbench-instances) 이미지를 사용하는 인스턴스에는 설치되지 않습니다.
새 인스턴스에는 기본적으로 Antigravity CLI가 사용 설정되어 있습니다. 인스턴스를 만들 때 enable-antigravity 인스턴스 메타데이터 키를 설정하지 않으면 Agent Platform Workbench에서 이를 true로 설정합니다.
인스턴스에 Antigravity CLI를 사용 설정하거나 중지하려면 enable-antigravity 인스턴스 메타데이터 키를 false 또는 true로 설정한 후 인스턴스를 중지하고 시작합니다. 인스턴스는 시작할 때 설정을 적용합니다. 자세한 내용은 메타데이터를 통해 기능 관리를 참조하세요.
Antigravity CLI 사용
Google Cloud 콘솔에서 인스턴스 페이지로 이동합니다.
Agent Platform Workbench 인스턴스 이름 옆에 있는 JupyterLab 열기를 클릭합니다.
JupyterLab에서 파일 > 새 런처를 클릭합니다.
런처 탭의 기타 섹션에서 Antigravity CLI 타일을 클릭합니다.
터미널이 열리고 Antigravity CLI가 시작됩니다. JupyterLab 터미널에
agy를 입력할 수도 있습니다.''test-notebook'이라는 새 노트북 만들기'와 같은 프롬프트를 입력합니다. 더 많은 예시는 샘플 프롬프트를 참조하세요.
Antigravity CLI에서 파일 수정 또는 셸 명령어 실행과 같은 작업을 제안하면 이를 검토하고 승인하거나 거부합니다. 자세한 내용은 도구 작업 승인을 참고하세요.
노트북 스킬 및 Google Cloud 플러그인
스킬은 Antigravity CLI가 특정 유형의 작업에 사용하는 안내와 스크립트입니다. Antigravity CLI가 사용 설정되면 Agent Platform Workbench에서 다음과 같은 노트북 기술을 제공합니다.
- 노트북 타겟팅 도구: JupyterLab에서 열려 있는 노트북을 찾아 '이 노트북'으로 참조할 수 있습니다.
- 노트북 설명: 노트북의 셀과 텍스트 출력을 요약합니다.
- 노트북 수정자: 셀을 추가하고 수정합니다. 대상 셀만 변경하고 노트북은 JupyterLab에서 사용하는 형식으로 유지합니다.
- 노트북 검사기: 노트북이 유효한지 확인합니다. 이미 잘못된 노트북을 복구하기 전에 사용자에게 확인을 요청합니다.
- 노트북 작성자: 인스턴스에서 사용할 수 있는 커널로 노트북을 만듭니다.
- 노트북 실행자: 인스턴스의 커널에서 노트북을 실행하고 출력을 저장합니다. 셀이 실패하면 셀의 이름을 지정합니다.
- 커널 생성자: 요청한 패키지로 Python 환경과 Jupyter 커널을 만듭니다.
Antigravity CLI에는 Antigravity 플러그인 마켓플레이스의 google-cloud-developer 플러그인도 함께 제공됩니다. 이 플러그인은 Antigravity CLI에 gcloud 명령어에 대한 안내, 인증 지원, Google Cloud 문서, Cloud Logging, Cloud Monitoring, Agent Platform과 같은 제품에 대한 기술을 제공합니다.
Antigravity CLI는 프롬프트에 필요할 때 스킬 또는 플러그인을 사용합니다. 프롬프트에서 이름을 지정할 필요가 없습니다.
샘플 프롬프트
Antigravity CLI를 사용하는 방법에 대한 아이디어를 얻으려면 다음 샘플 프롬프트를 참고하세요.
"이 노트북을 설명해 줘."
"이 노트북에 'age' 열의 분포를 표시하는 셀을 추가해 줘."
"bigquery-public-data.ml_datasets.census_adult_income을 pandas DataFrame에 로드하는 노트북을 만들고 실행해 줘."
"pandas와 prophet을 사용하여 'forecast'라는 커널을 만들어 줘."
"이 디렉터리의 모든 노트북이 유효한 노트북인지 확인해 줘."
"bigquery-public-data.ml_datasets.census_adult_income 테이블을 쿼리하여 소득 구간이 50,000달러를 초과하는 사람 수를 찾아 줘."
%%agy 셀 매직 사용
Antigravity CLI가 노트북의 셀에 코드를 작성하도록 하려면 다음을 수행합니다.
- Python 노트북의 새 셀 첫 번째 줄에
%%agy을 입력합니다. - 같은 셀의 다음 줄에 원하는 코드를 설명합니다.
- 셀을 실행합니다.
Antigravity CLI가 아래에 코드가 포함된 새 셀을 추가합니다. 코드를 실행하기 전에 검토하세요.
%%agy 셀 매직은 코드 생성을 위해 엄격하게 설계되었습니다. 터미널 인터페이스와 달리 셀 매직은 승인을 요청할 수 없으므로 셸 명령어 실행과 같이 승인이 필요한 모든 작업을 자동으로 거부합니다.
%%agy 셀 매직은 Antigravity CLI가 사용 설정되어 있으면 언제든지 사용할 수 있습니다.
도구 작업 승인
기본적으로 Agent Platform Workbench의 Antigravity CLI는 파일 수정, 셸 명령어 실행, URL 가져오기와 같은 작업을 수행하기 전에 승인을 요청합니다. 제안된 각 작업을 승인하기 전에 검토하세요.
이 기본값은 프롬프트 인젝션을 방지합니다. Antigravity CLI가 읽는 노트북, 스크립트 또는 웹페이지에는 데이터를 외부 주소로 전송하는 등 의도하지 않은 명령어를 에이전트가 실행하도록 시도하는 숨겨진 요청 사항이 포함될 수 있습니다. Antigravity CLI는 인스턴스의 사용자 인증 정보로 실행되므로 승인을 요구하면 실행 전에 이러한 작업을 확인하고 중지할 수 있습니다.
이러한 이유로 Agent Platform Workbench 인스턴스의 Antigravity CLI에서는 승인 프롬프트를 건너뛰는 옵션이 사용 중지됩니다.
Antigravity CLI에 대한 액세스 제어
다음 방법을 사용하여 Agent Platform Workbench에서 Antigravity CLI에 대한 액세스를 제어할 수 있습니다.
관리자는
enable-antigravity인스턴스 메타데이터 키를false로 설정할 수 있습니다. 그러면 다음에 인스턴스를 시작할 때 Antigravity CLI 타일, 노트북 기술, 플러그인,%%agy셀 매직이 삭제됩니다.agy명령어는 설치된 상태로 유지됩니다. 모델 호출을 방지하려면 다음 메서드를 사용하세요.관리자는 조직 정책을 설정하여 조직, 폴더 또는 프로젝트 수준에서 특정 모델의 사용을 제한할 수 있습니다. Model Garden 모델에 대한 액세스 제어를 참조하세요.
관리자는
aiplatform.endpoints.predict권한을 부여하지 않음으로써 일부 ID가 추론에 모델 엔드포인트를 사용하지 못하도록 차단할 수 있습니다.
다음 단계
Gemini Enterprise Agent Platform 자세히 알아보기
인스턴스 메타데이터를 설정하는 방법은 메타데이터를 통해 기능 관리를 참조하세요.