Cloud Workstations는 Antigravity CLI 및 Claude Code와 같은 자율적이고 대화형 AI 코딩 에이전트를 위한 최적화된 런타임 환경을 제공합니다. 에이전트 개발 워크플로를 실행할 때 에이전트는 장기 실행 비동기 작업 (예: 코드 생성, 심층 리팩터링, 테스트 실행)을 자주 실행하거나 사용자 입력 및 검토를 기다리는 동안 일시중지합니다.
표준 워크스테이션 유휴 시간 제한은 장기간의 비활성 상태에서 임시 워크스테이션 VM을 종료하고 삭제하여 컨테이너를 종료하고 에이전트 컨텍스트를 다시 초기화해야 할 수 있습니다. 에이전트 최적화 개발 은 두 가지 주요 기능을 결합하여 이 문제를 해결합니다.
- 워크스테이션 일시중지 (
IdleAction.SUSPEND): 이 기능은 워크스테이션 VM이 유휴 시간 제한에 도달하면 중지하는 대신 자동으로 일시중지합니다. 워크스테이션을 일시중지하면 가상 머신의 RAM, 실행 중인 프로세스, 열려 있는 파일, 활성 에이전트 컨텍스트가 영구 스토리지에 보존되는 반면 vCPU 및 메모리 컴퓨팅 비용은 중지됩니다. - Lifecycle 연결 유지 후크: 이러한 후크를 사용하면 AI 에이전트가 활성 처리 중에 백그라운드 연결 유지 스크립트 (
/google/scripts/keep_alive.sh)를 실행하여 시간 제한을 방지하고 사용자 입력을 기다리거나 작업을 완료한 후 스크립트를 종료하여 워크스테이션이 유휴 상태로 전환되고 일시중지될 수 있습니다.
에이전트 최적화 작동 방식
에이전트 최적화는 장기 실행 작업 중에 지속적인 상태, 비용 효율성, 원활한 운영을 보장합니다.
- 활성 처리: 에이전트가 사용자 명령어 실행을 시작하면
수명 주기 후크가 백그라운드에서
/google/scripts/keep_alive.sh를 시작합니다. 이 스크립트는 Cloud Workstations가 워크스테이션을 유휴 상태로 표시하지 못하도록 하는 주기적인 연결 유지 신호를 전송합니다. - 사용자 입력 또는 작업 완료 대기: 에이전트가 작업을 완료하거나 개발자에게 검토 또는 추가 입력을 요청하기 위해 일시중지하면 이벤트 후크가 백그라운드 연결 유지 프로세스를 종료합니다.
- 자동 일시중지: 활성 keep-alive 신호 또는 수신
트래픽이 없으면 워크스테이션의 유휴 타이머가 구성된
유휴 시간 제한 기준점까지 카운트다운됩니다. 시간이 초과되면 Cloud Workstations는 워크스테이션을 종료하는 대신
STATE_SUSPENDED로 전환합니다. - 즉시 재개: 개발자가 돌아와서 콘솔, IDE 또는 SSH를 통해 Google Cloud 다시 연결하면 워크스테이션이 영구 스토리지에서 전체 에이전트 상태, 터미널 세션, 작업공간 컨텍스트를 그대로 유지한 채 즉시 재개됩니다.
워크스테이션 일시중지 구성
워크스테이션 일시중지를 사용 설정하려면 idleAction이 SUSPEND로 설정되고 idleTimeout 기간이 초 단위로 설정된 워크스테이션 구성(예: 30분의 경우 1800s)으로 업데이트합니다.
이 페이지의 샘플 사용 방법에 대한 탭을 선택하세요.
콘솔
콘솔 Google Cloud 을 사용하여 Google Cloud 서비스 및 API에 액세스하는 경우 인증을 설정할 필요가 없습니다.
gcloud
Google Cloud 콘솔에서 Cloud Shell을 활성화합니다.
콘솔 Google Cloud 하단에 Cloud Shell 세션이 시작되고 명령줄 프롬프트가 표시됩니다. Cloud Shell은 Google Cloud CLI가 사전 설치된 셸 환경으로, 현재 프로젝트의 값이 이미 설정되어 있습니다. 세션이 초기화되는 데 몇 초 정도 걸릴 수 있습니다.
REST
로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면
gcloud CLI에 제공한 사용자 인증 정보를 사용합니다.
Google Cloud CLI를 설치합니다.
외부 ID 공급업체 (IdP)를 사용하는 경우 먼저
제휴 ID로 gcloud CLI에 로그인해야 합니다.
자세한 내용은 인증 문서의 REST 사용을 위한 인증 을 참조하세요. Google Cloud
콘솔
콘솔Google Cloud 에서 워크스테이션 구성에 일시중지를 구성하려면 다음 안내를 따르세요.
콘솔에서 Google Cloud 워크스테이션 구성으로 이동합니다.
추가 만들기 를 클릭하거나 기존 구성을 클릭하고 수정 수정 을 클릭합니다.
기본 정보 섹션을 작성하고 머신 설정 으로 이동합니다.
유휴 시간 제한에서 유휴 시간 제한 기간(예: 30분)을 설정합니다.
유휴 작업 드롭다운에서 일시중지 (또는 유휴 시간 제한 시 워크스테이션 일시중지)를 선택합니다.
나머지 구성 단계를 완료하고 만들기 (또는 저장)를 클릭합니다.
gcloud
일시중지가 사용 설정된 새 워크스테이션 구성을 만들려면
gcloud workstations configs create
명령어와 함께 --idle-action=suspend 플래그를 실행합니다.
gcloud workstations configs create CONFIG_NAME \
--cluster=CLUSTER_NAME \
--region=LOCATION \
--idle-timeout=1800 \
--idle-action=suspend
일시중지를 사용하도록 기존 워크스테이션 구성을 업데이트하려면
gcloud workstations configs update
명령어를 실행합니다.
gcloud workstations configs update CONFIG_NAME \
--cluster=CLUSTER_NAME \
--region=LOCATION \
--idle-timeout=1800 \
--idle-action=suspend
다음을 바꿉니다.
CONFIG_NAME: 워크스테이션 구성의 이름입니다.CLUSTER_NAME: 워크스테이션 클러스터의 이름입니다.LOCATION: 워크스테이션 클러스터가 있는 리전입니다.
REST
REST API를 사용하여 일시중지를 구성하려면 idleAction을 SUSPEND로 설정하고
idleTimeout을 선택한 기간으로 설정합니다.
workstationConfigs
페이로드:
{
"idleTimeout": "1800s",
"idleAction": "SUSPEND"
}
샘플 연결 유지 후크로 에이전트 구성
Cloud Workstations 사전 구성된 기본 이미지는 /google/samples/agents/keepalive/에 샘플 에이전트 구성 파일이 사전 설치되어 제공됩니다. 이러한 샘플은 연결 유지 수명 주기를 자동으로 관리하도록 AI 코딩 에이전트를 구성하는 방법을 보여줍니다.
에이전트 연결 유지 후크 작동 방식
최신 AI 코딩 에이전트는 주요 수명 주기 마일스톤에서 명령어를 실행하는 이벤트 후크 시스템을 제공합니다.
- 실행 시작 후크: 에이전트가 사용자 입력 처리를 시작하기 전에 트리거됩니다. 후크는 백그라운드에서
/google/scripts/keep_alive.sh를 실행하고 백그라운드 프로세스 ID (PID)를 임시 파일 (예:/tmp/agent_keep_alive.pid)에 씁니다. - 알림 / 사용자 입력 대기 후크: 에이전트가 작업을 완료하거나 사용자에게 입력을 요청하기 위해 일시중지할 때 트리거됩니다. 후크는 임시 파일에서 PID를 읽고 백그라운드
keep_alive.sh프로세스를 종료합니다.
Claude Code 구성
Claude Code는 설정에서 구성된 수명 주기 이벤트 후크를 지원합니다. Claude Code의 샘플 구성 파일은 다음 위치에 있습니다.
/google/samples/agents/keepalive/claude/
Claude Code에서 다음 이벤트 후크는 연결 유지 프로세스를 관리합니다.
UserPromptSubmit: 사용자가 프롬프트를 제출할 때 후크가 실행됩니다. 백그라운드에서 연결 유지 스크립트를 시작합니다./google/scripts/keep_alive.sh & echo $! > /tmp/claude_keep_alive.pidNotification: Claude Code가 알림을 내보내거나 사용자 입력을 위해 일시중지할 때 후크가 실행됩니다. 활성 연결 유지 백그라운드 프로세스를 종료합니다.if [ -f /tmp/claude_keep_alive.pid ]; then kill "$(cat /tmp/claude_keep_alive.pid)" 2>/dev/null || true rm -f /tmp/claude_keep_alive.pid fi
샘플 구성을 적용하려면 /google/samples/agents/keepalive/claude/의 샘플 파일을 Claude 구성 디렉터리 (예: ~/.claude/settings.json 또는 프로젝트 수준 구성)에 복사하거나 병합합니다.
Antigravity CLI 구성
Antigravity CLI는 설정에 정의된 수명 주기 이벤트 후크를 지원합니다. Antigravity CLI의 샘플 구성 파일은 다음 위치에 있습니다.
/google/samples/agents/keepalive/gemini/
Antigravity CLI에서 다음 이벤트 후크는 연결 유지 프로세스를 관리합니다.
BeforeAgent: Antigravity CLI가 작업 실행을 시작하기 전에 후크가 실행됩니다. 백그라운드에서 연결 유지 스크립트를 시작합니다./google/scripts/keep_alive.sh & echo $! > /tmp/gemini_keep_alive.pidNotification: 에이전트가 차례를 완료하거나 사용자 의견이 필요할 때 후크가 실행됩니다. 연결 유지 프로세스를 종료합니다.if [ -f /tmp/gemini_keep_alive.pid ]; then kill "$(cat /tmp/gemini_keep_alive.pid)" 2>/dev/null || true rm -f /tmp/gemini_keep_alive.pid fi
샘플 구성을 적용하려면 /google/samples/agents/keepalive/gemini/의 샘플 파일을 Antigravity CLI 구성 디렉터리 (예: ~/.gemini/config.yaml 또는 프로젝트 설정)에 복사하거나 병합합니다.
커스텀 에이전트 통합
커스텀 AI 에이전트를 빌드하거나 사용하는 경우 활성 에이전트 실행 중에 /google/scripts/keep_alive.sh를 백그라운드 프로세스로 실행하고 에이전트가 유휴 또는 대기 상태로 전환될 때 프로세스를 종료하여 동일한 keep-alive 패턴을 구현할 수 있습니다.
일시중지된 워크스테이션 재개
워크스테이션이 STATE_SUSPENDED 상태인 경우 언제든지 재개할 수 있습니다.
- Google Cloud 콘솔: Google Cloud 콘솔에서 워크스테이션 페이지로 이동하고 일시중지된 워크스테이션 옆에 있는 실행 또는 시작을 클릭합니다.
gcloudCLI:gcloud workstations start명령어를 실행합니다.gcloud workstations start WORKSTATION_NAME \ --cluster=CLUSTER_NAME \ --region=LOCATION \ --config=CONFIG_NAME다음을 바꿉니다.
WORKSTATION_NAME: 워크스테이션의 이름입니다.CLUSTER_NAME: 워크스테이션 클러스터의 이름입니다.LOCATION: 워크스테이션 클러스터가 있는 리전입니다.CONFIG_NAME: 워크스테이션 구성의 이름입니다.
브라우저 또는 SSH 연결: 워크스테이션의 웹 URL로 이동하거나 SSH를 사용하여 연결하면 워크스테이션이 자동으로 재개됩니다.
재개되면 모든 터미널 버퍼, 에이전트 명령어 기록, 작업공간 파일이 종료할 때와 정확히 동일하게 복원됩니다.
다음 단계
- 워크스테이션 구성 만들기.
- Gemini CLI를 사용한 AI 에이전트 지원 코딩에 대해 자세히 알아봅니다.
- 사전 구성된 기본 이미지를 살펴봅니다.
- SSH 지원으로 연결하는 방법을 알아봅니다.