에이전트 최적화 개발

Cloud Workstations는 Antigravity CLI, Claude Code와 같은 자율적이고 대화형 AI 코딩 에이전트를 위한 최적화된 런타임 환경을 제공합니다. 에이전트 개발 워크플로를 실행할 때 에이전트는 장기 실행 비동기 작업 (예: 코드 생성, 심층 리팩터링, 테스트 실행)을 자주 수행하거나 사람의 입력 및 검토를 기다리는 동안 일시중지됩니다.

표준 워크스테이션 유휴 시간 제한은 장기간의 비활성 상태 중에 임시 워크스테이션 VM을 종료하고 삭제하여 컨테이너를 종료하고 에이전트 컨텍스트를 다시 초기화해야 합니다. 에이전트 최적화 개발은 다음과 같은 두 가지 주요 기능을 결합하여 이 문제를 해결합니다.

1. 워크스테이션 일시중지 (IdleAction.SUSPEND): 이 기능은 워크스테이션 VM이 유휴 제한 시간에 도달하면 중지하는 대신 자동으로 일시중지합니다. 워크스테이션을 일시중지하면 가상 머신의 RAM, 실행 중인 프로세스, 열린 파일, 활성 에이전트 컨텍스트가 영구 스토리지에 보존되는 동시에 vCPU 및 메모리 컴퓨팅 비용이 중지됩니다.
2. 수명 주기 유지 활성 훅: 이러한 훅을 사용하면 AI 에이전트가 활성 처리 중에 백그라운드 유지 활성 스크립트 (/google/scripts/keep_alive.sh)를 실행하여 시간 초과를 방지하고, 사용자 입력을 기다리거나 작업을 완료한 후 스크립트를 종료하여 워크스테이션이 유휴 상태로 전환되고 일시 중지될 수 있습니다.

에이전트 최적화 작동 방식

에이전트 최적화는 장기 실행 작업 중에 지속적인 상태, 비용 효율성, 원활한 작업을 보장합니다.

• 활성 처리: 상담사가 사용자 안내를 실행하기 시작하면 수명 주기 후크가 백그라운드에서 /google/scripts/keep_alive.sh를 시작합니다. 이 스크립트는 Cloud Workstations에서 워크스테이션을 유휴 상태로 표시하지 못하도록 주기적인 연결 유지 신호를 전송합니다.
• 사용자 입력 또는 작업 완료 대기: 에이전트가 작업을 완료하거나 일시중지하여 개발자에게 검토 또는 추가 입력을 요청하면 이벤트 후크가 백그라운드 연결 유지 프로세스를 종료합니다.
• 자동 정지: 활성 상태의 유지 신호나 수신 트래픽이 없으면 워크스테이션의 유휴 타이머가 구성된 유휴 시간 제한 기준점까지 카운트다운됩니다. 제한 시간이 초과되면 Cloud Workstations는 워크스테이션을 종료하는 대신 STATE_SUSPENDED로 전환합니다.
• 즉시 재개: 개발자가 돌아와서 Google Cloud 콘솔, IDE 또는 SSH를 통해 다시 연결하면 워크스테이션이 영구 스토리지에서 전체 에이전트 상태, 터미널 세션, 작업공간 컨텍스트가 그대로 유지된 상태로 즉시 재개됩니다.

워크스테이션 일시 중단 구성

워크스테이션 정지를 사용 설정하려면 idleAction를 SUSPEND로 설정하고 idleTimeout 기간을 초 단위로 설정하여 워크스테이션 구성을 업데이트합니다(예: 30분의 경우 1800s).

이 페이지의 샘플 사용 방법에 대한 탭을 선택하세요.

콘솔

Google Cloud 콘솔을 사용하여 Google Cloud 서비스 및 API에 액세스하는 경우 인증을 설정할 필요가 없습니다.

gcloud

Google Cloud 콘솔에서 Cloud Shell을 활성화합니다.

Cloud Shell 활성화

Google Cloud 콘솔 하단에서 Cloud Shell 세션이 시작되고 명령줄 프롬프트가 표시됩니다. Cloud Shell은 Google Cloud CLI가 사전 설치된 셸 환경으로, 현재 프로젝트의 값이 이미 설정되어 있습니다. 세션이 초기화되는 데 몇 초 정도 걸릴 수 있습니다.

REST

로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공한 사용자 인증 정보를 사용합니다.

Google Cloud CLI를 설치합니다.

외부 ID 공급업체 (IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

자세한 내용은 Google Cloud 인증 문서의 REST 사용을 위한 인증을 참조하세요.

콘솔

Google Cloud 콘솔에서 워크스테이션 구성의 정지를 구성하려면 다음 단계를 따르세요.

1. Google Cloud 콘솔에서 워크스테이션 구성으로 이동합니다.

   워크스테이션 구성으로 이동

2. 추가 만들기를 클릭하거나 기존 구성을 클릭하고 수정 수정을 클릭합니다.

3. 기본 정보 섹션을 완료하고 머신 설정으로 이동합니다.

4. 유휴 상태 제한 시간에서 유휴 상태 제한 시간(예: 30분)을 설정합니다.

5. 유휴 상태 작업 드롭다운에서 정지 (또는 유휴 상태 제한 시간 시 워크스테이션 정지)를 선택합니다.

6. 나머지 구성 단계를 완료하고 만들기 (또는 저장)를 클릭합니다.

gcloud

절전 모드가 사용 설정된 새 워크스테이션 구성을 만들려면 --idle-action=suspend 플래그와 함께 gcloud workstations configs create 명령어를 실행합니다.

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 코드에서는 다음 이벤트 후크가 keep-alive 프로세스를 관리합니다.

1. UserPromptSubmit: 사용자가 프롬프트를 제출할 때 후크가 실행됩니다. 백그라운드에서 keep-alive 스크립트를 시작합니다.

   /google/scripts/keep_alive.sh & echo $! > /tmp/claude_keep_alive.pid
   

2. Notification: 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에서 다음 이벤트 후크는 연결 유지 프로세스를 관리합니다.

1. BeforeAgent: Antigravity CLI가 작업을 실행하기 전에 후크가 실행됩니다. 백그라운드에서 연결 유지 스크립트를 시작합니다.

   /google/scripts/keep_alive.sh & echo $! > /tmp/gemini_keep_alive.pid
   

2. Notification: 에이전트가 턴을 완료하거나 사용자 의견이 필요한 경우 후크가 실행됩니다. 연결 유지 프로세스를 종료합니다.

   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을 백그라운드 프로세스로 실행하고 에이전트가 유휴 또는 대기 상태로 전환되면 프로세스를 종료하여 동일한 연결 유지 패턴을 구현할 수 있습니다.

일시중지된 워크스테이션 재개

워크스테이션이 STATE_SUSPENDED 상태인 경우 언제든지 다시 시작할 수 있습니다.

• Google Cloud 콘솔: Google Cloud 콘솔에서 워크스테이션 페이지로 이동하고 일시중지된 워크스테이션 옆에 있는 실행 또는 시작을 클릭합니다.

• gcloud CLI: 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 지원으로 연결하는 방법을 알아보세요.