AI 에이전트 운영자를 위한 Google Antigravity 마이그레이션 가이드

AI 에이전트 작업에서 실제로 바뀌는 것

이번 변경의 대상은 Gemini API에서 제공하는 Antigravity 관리형 에이전트입니다. 컴퓨터에 설치하는 Antigravity IDE 업데이트와는 무관합니다.

두 제품은 런타임 기반을 공유하므로 이름도 겹칩니다. 그러나 여기서 바뀌는 것은 애플리케이션이 Google Interactions API로 보내는 에이전트 ID이며, 일부 연동에서는 애플리케이션이 처리하는 내장 툴 호출도 달라집니다. IDE를 업데이트한다고 이 API 계약까지 자동으로 갱신되지는 않습니다.

새 에이전트는 antigravity-preview-09-2026입니다. 기본 추론 모델은 Gemini 3.8 Flash이지만, Antigravity Agent 가이드에 따르면 애플리케이션은 agent_config를 통해 지원되는 다른 모델을 선택할 수 있습니다. 앞서 다룬 Gemini 관리형 에이전트 해설에서는 호스팅 워크스페이스, 백그라운드 작업, 툴 루프를 설명했습니다. 이번 마이그레이션은 그보다 한 단계 아래에 있습니다. 기존 작업을 계속 시작할 수 있는지, 그리고 툴 호출을 계속 실행할 수 있는지를 결정합니다.

Google은 9월 17일 릴리스 노트에서 마이그레이션 경로를 두 가지로 나눴습니다.

• 원격 샌드박스에서 실행되며 output_text 또는 model_output만 읽는 작업은 에이전트 문자열만 바꾸면 됩니다.
• local_environment를 사용하거나 function_call 단계를 파싱하는 작업은 툴 어댑터도 업데이트해야 합니다.

판단 기준은 이 구분 하나면 충분합니다. 어댑터는 툴 이름과 인수를 받아 검증하고, 로컬 작업을 실행한 뒤 결과를 반환하는 작은 애플리케이션 코드입니다.

로컬 툴 계약에서 바뀐 다섯 가지

기존 에이전트는 파일 작업을 대체로 범용 읽기와 쓰기로 처리했습니다. 9월 에이전트는 파일 작업을 더 세분화한 이름과 인수로 제공합니다. 인수 키 표기도 snake_case에서 PascalCase로 바뀝니다.

파일 및 검색 기능군 다섯 가지가 바뀌었고, 표에 나온 내장 기능 두 가지는 그대로입니다. 따라서 write_file을 중심으로 만든 포괄형 핸들러는 새 에이전트 ID가 정확해도 실패할 수 있습니다.

새 편집 계약은 더 정밀합니다. 작은 변경을 위해 파일 전체를 다시 보내는 대신 에이전트가 줄 범위, 그 위치에서 예상하는 텍스트, 대체할 텍스트를 지정합니다. TargetContent가 현재 파일과 더 이상 일치하지 않으면 어댑터가 호출을 거부해야 합니다. 그렇지 않으면 지연된 작업이 사람이 나중에 수정한 내용을 덮어쓸 수 있습니다.

실제 마이그레이션 작업이 필요한 경우

혼자 원격 보고서 작업을 운영하는 창업자

매일 밤 Antigravity가 Google 샌드박스에서 데이터를 모으고, 보고서를 저장한 뒤 최종 텍스트를 돌려주는 작업을 가정해 보겠습니다. 애플리케이션은 output_text만 읽고 내부 단계를 살펴보지 않습니다.

이 경우 마이그레이션 범위는 작습니다. antigravity-preview-05-2026을 antigravity-preview-09-2026으로 바꾸고, 대표 보고서 하나를 기존 작업과 나란히 실행해 최종 결과물을 비교한 다음 스케줄을 옮기면 됩니다. 존재하지도 않는 로컬 툴 디스패처를 새로 만들 이유는 없습니다.

자체 시스템에서 툴을 실행하는 플랫폼 팀

이번에는 자체 러너 안에서 툴 호출을 실행하는 저장소 작업자를 생각해 보겠습니다. 이 작업자는 파일을 읽고, 코드를 검색하고, 설정을 편집한 뒤 툴 결과를 인터랙션에 돌려줍니다.

이 팀은 더 큰 범위의 마이그레이션을 맡아야 합니다. 디스패처가 새 이름을 인식하고 PascalCase 인수를 검증하며, 경로와 명령 정책을 적용하고, 줄 범위 편집을 안전하게 수행한 뒤 인터랙션이 기대하는 형식으로 결과를 반환해야 합니다. 이를 마치면 5월 엔드포인트가 사라진 뒤에도 코드 리뷰, 보고서 생성, 유지보수 작업을 계속 실행할 수 있습니다.

모든 단계를 수집하는 관측성 팀

모든 작업을 원격에서 실행하더라도 function_call 단계를 감사 로그, 진행 상황 UI, 승인 대기열 또는 비용 대시보드로 복사하는 애플리케이션이 있습니다. 이런 애플리케이션은 출력만 소비하는 경우에 해당하지 않습니다.

Google이 내장 파일시스템 작업을 실행하더라도 파서에는 여전히 write_file, path, content가 전제되어 있을 수 있습니다. 허용 목록과 픽스처를 업데이트해 대시보드가 실제 편집을 알 수 없는 작업으로 표시하거나, 인수를 누락하거나, 잘못된 승인 정책으로 보내지 않도록 해야 합니다.

무인 트리거를 관리하는 운영 책임자

예약 트리거는 호출 시점에 지켜보는 사람이 없기 때문에 위험이 가장 큽니다. 트리거는 에이전트, 환경, 프롬프트, cron 스케줄을 하나로 묶습니다. 저장된 인터랙션이 계속 5월 에이전트를 가리키면 스케줄 자체는 정상이어도 그 뒤의 실행은 종료일 이후 실패할 수 있습니다.

주 애플리케이션의 SDK 호출만 보지 말고 모든 트리거 정의에 저장된 에이전트 ID를 조사해야 합니다. 그런 다음 서로 다른 툴 패턴마다 작업 하나를 섀도 실행합니다. 둘 다 Antigravity를 쓴다고 해서 보고서 작업과 저장소 복구 작업을 같은 마이그레이션 테스트로 볼 수는 없습니다.

작은 파일 편집 계약 테스트

가장 안전한 첫 테스트에는 프로덕션 자격 증명이 필요하지 않습니다. 캡처해 둔 호출 형태의 픽스처를 어댑터에 입력하고, 폐기 가능한 파일을 편집한 다음 의도한 줄만 바뀌었는지 확인하면 됩니다.

아래 코드는 Google이 공개한 replace_file_content 이름과 PascalCase 필드를 사용해 Node에서 실행했습니다. 실제 Gemini API 호출이 아니라 로컬 어댑터 테스트입니다.

import assert from "node:assert/strict";
import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

function applyReplaceFileContent(call) {
  assert.equal(call.name, "replace_file_content");

  const {
    TargetFile,
    StartLine,
    EndLine,
    TargetContent,
    ReplacementContent,
  } = call.arguments;

  const lines = readFileSync(TargetFile, "utf8").split("\n");
  const current = lines.slice(StartLine - 1, EndLine).join("\n");
  assert.equal(current, TargetContent, "line window no longer matches");

  lines.splice(
    StartLine - 1,
    EndLine - StartLine + 1,
    ...ReplacementContent.split("\n"),
  );
  writeFileSync(TargetFile, lines.join("\n"));
}

const dir = mkdtempSync(join(tmpdir(), "antigravity-adapter-"));
const file = join(dir, "scheduled-job.env");
writeFileSync(file, "owner=ops\nstatus=old\nmode=scheduled\n");

applyReplaceFileContent({
  name: "replace_file_content",
  arguments: {
    TargetFile: file,
    StartLine: 2,
    EndLine: 2,
    TargetContent: "status=old",
    ReplacementContent: "status=ready",
  },
});

assert.equal(
  readFileSync(file, "utf8"),
  "owner=ops\nstatus=ready\nmode=scheduled\n",
);
console.log("PASS: line 2 changed from status=old to status=ready");

테스트는 통과했습니다. 더 중요한 점은 픽스처의 TargetContent를 바꾸면 오래된 내용을 편집하지 않고 중단된다는 것입니다.

비용 판단의 핵심은 마이그레이션 공수와 누락된 작업의 손실입니다

Google은 이번 에이전트 마이그레이션과 함께 새로운 토큰당 가격을 발표하지 않았습니다. 달라진 예산 항목은 엔지니어링과 운영에 드는 시간입니다.

다음 두 식만 사용하면 됩니다.

출력만 소비하는 원격 작업이라면 엔지니어링 항목은 에이전트 문자열 변경과 섀도 실행 한 번이면 충분할 수 있습니다. 로컬 툴을 연동했다면 변경된 기능군 다섯 가지, 파서 픽스처, 안전성 테스트, 서로 다른 워크플로 형태마다 전체 실행 한 번을 예산에 반영해야 합니다.

이를 모든 조직에 통용되는 가짜 소요 시간으로 바꾸지는 마십시오. 범위가 좁은 보고서 생성기와 로컬 코딩 에이전트는 툴 범위, 승인 로직, 실패 비용이 서로 다릅니다. 실제 인건비를 반영한 엔지니어링 단가와 실행당 사업 가치를 식에 넣어야 합니다. 그래야 재무팀도 벤더 기능 목록이 아니라 현실적인 판단 근거를 얻을 수 있습니다.

솔직히 짚어야 할 부분

위 로컬 테스트가 입증하는 것은 픽스처와 어댑터가 서로 일치한다는 사실뿐입니다. 실제 에이전트가 모든 프롬프트에 어떤 호출을 내보낼지까지 증명하지는 않습니다. 이번 실행에는 Gemini API 자격 증명이 없었으므로 호스팅 에이전트를 실행했다고 가장하지 않았습니다. 최종 통과 기준은 폐기 가능한 환경에서 캡처한 9월 에이전트 호출입니다.

또한 모든 Antigravity 사용자가 똑같은 작업을 해야 하는 것은 아닙니다.

• 프로덕션 작업이 antigravity-preview-05-2026을 지정하거나, local_environment를 사용하거나, function_call 단계를 파싱하거나, 무인 스케줄로 실행된다면 이번 주에 바로 대응해야 합니다.
• 작업이 원격 샌드박스에서 실행되고 output_text 또는 model_output만 소비한다면 간단한 경로를 따르면 됩니다. ID를 바꾸고 섀도 실행합니다.
• 아직 API를 평가하는 단계이고 프로덕션에서 5월 에이전트 작업을 운영하지 않는다면 새 ID로 바로 시작합니다.
• Antigravity IDE만 사용하고 Gemini API를 통해 관리형 에이전트를 호출하지 않는다면 이번 마이그레이션은 무시해도 됩니다.

월요일에 바로 할 일

한 사람에게 인벤토리 책임을 맡깁니다. 배포된 설정, 트리거 정의, 환경 변수, 대시보드, 픽스처에서 5월 에이전트 ID와 기존 툴 이름을 찾습니다. 코드를 바꾸기 전에 결과를 출력 전용 목록과 어댑터 작업이 필요한 목록으로 나눕니다.

그런 다음 각 목록에서 대표 작업 하나씩을 마이그레이션합니다. 9월 실행 결과를 확인하는 동안 기존 스케줄은 일시 중지하되 다시 사용할 수 있게 유지하고, 나머지 작업은 워크플로 유형별로 옮기며, 10월 5일까지 알 수 없는 툴 호출에 대한 알림을 설정합니다. 월요일의 결과물은 발표 자료가 아닙니다. 담당자가 지정된 인벤토리, 통과한 섀도 실행, 남은 모든 작업의 완료 예정일입니다.

실제 워크플로를 중단시킬 수 있는 변경 사항을 쉬운 말로 정리한 운영 노트를 더 받아보려면 뉴스레터를 구독하세요.