Antigravity SDK란? 설치 방법과 첫 에이전트 만들기

Antigravity SDK란 무엇인가요?

SDK는 애플리케이션 코드가 제품 기능을 지원되는 방식으로 호출할 수 있게 해 줍니다. Antigravity SDK를 사용하면 개발자가 에이전트를 정의하고, 승인한 도구를 연결하고, Python에서 결과를 받을 수 있습니다. 내부 어시스턴트, 저장소 도우미, 테스트 하네스, 반복 가능한 자동화 워크플로처럼 실행 흐름을 직접 관리해야 하는 작업에 적합합니다.

가장 중요한 차이는 누가 흐름을 소유하는가입니다. IDE는 프로젝트에서 대화형으로 작업할 때 쓰고, CLI는 터미널 명령에 쓰며, SDK는 프로그램이 전체 워크플로를 소유하게 합니다. 세 표면은 서로 보완할 수 있지만 하나의 공통 버전이나 하나의 설정 파일을 공유한다고 가정해서는 안 됩니다.

Antigravity Python SDK 설치 방법

먼저 공식 SDK 시작 문서와 현재 PyPI 패키지 메타데이터를 확인하세요. 오래된 코드 조각을 그대로 복사하기보다 Python 요구 버전, 추가 패키지, 인증 방식, import 경로를 현재 문서에서 확인하는 것이 좋습니다. 격리된 가상 환경을 사용하면 SDK 문제와 다른 의존성 문제를 분리하기 쉽습니다. 첫 테스트는 삭제해도 되는 프로젝트에서 실행하고, 비밀 값은 Git 밖에 보관하며, 읽기 전용이거나 되돌릴 수 있는 요청부터 시작하세요.

python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate   # macOS or Linux
python -m pip install --upgrade pip
python -m pip install google-antigravity

1. 격리된 환경 만들기프로젝트 안에 가상 환경을 만들면 패키지 해석과 롤백을 예측하기 쉬워집니다.
2. 관리되는 소스에서 설치하기현재 공식 패키지 안내와 인증 및 추가 패키지 단계를 따르세요.
3. 성공한 테스트 뒤에만 버전 고정하기가장 작은 예제를 실행하고 성공한 Python 런타임과 패키지 버전을 기록하세요.
4. 설정을 커밋에서 분리하기환경 변수나 비밀 저장소를 사용하고 로컬 설정 파일은 무시하도록 구성하세요.
5. 업그레이드 전에 릴리스 노트 읽기SDK API는 데스크톱 앱, CLI, IDE와 별도의 일정으로 변경될 수 있습니다.

실제 운영에 사용하기 전에 현재 Python 요구 사항과 패키지 설치 지침을 확인하세요.

작은 첫 에이전트 만들기

좋은 첫 에이전트는 목적 하나, 명확한 지시 하나, 사람이 직접 확인할 수 있는 결과 하나를 가집니다. 짧은 릴리스 노트를 요약하거나 로컬 fixture를 분류하는 작업부터 시작해 보세요. 브라우저, 셸, 데이터베이스, 파일 쓰기 권한을 처음부터 모두 넣으면 문제가 생겼을 때 원인을 격리하기가 어려워집니다.

클래스 이름과 응답 속성은 현재 SDK 릴리스에 속한 API입니다. 아래 예제는 설정하고, 한 번 요청하고, 결과를 살펴보고, 문서에 나온 수명 주기를 따르는 형태만 보여 줍니다. 영구적인 API 약속이 아니라 학습용 골격으로 취급하세요.

from google.antigravity import Agent, AgentConfig

config = AgentConfig(
    instructions="Summarize the supplied release note in three bullets."
)
agent = Agent(config=config)
result = agent.run("Release note: the test suite now reports flaky browser checks.")
print(result)

• 입력 — 예상 답변을 정해 둔 짧은 fixture를 사용하세요.
• 결과 — 자동화를 추가하기 전에 결과를 직접 확인하세요.
• 수명 주기 — 문서에 설명된 수명 주기와 재시도 동작을 따르세요.
• 재현성 — 프롬프트, 버전, 설정, 관찰한 결과를 함께 저장하세요.

도구는 한 번에 하나씩 추가하기

도구는 에이전트의 추론과 외부 동작을 연결합니다. 파일을 읽거나, 제한된 서비스에 질의하거나, 값을 계산하거나, 저장소 작업을 수행하는 등 가장 작은 유용한 동작부터 선택하세요. 입력 계약을 좁게 정의하고 인자를 검증한 뒤, 범위가 정해진 결과를 반환해야 합니다. 안전한 식별자와 결과만 기록하고, 읽기 전용 데이터로 충분할 때 홈 디렉터리나 쓰기 권한을 노출하지 마세요.

서로 다른 작업에는 서브에이전트 사용하기

계획, 검색, 검증, 형식 지정처럼 역할이 분리된 작업에는 서브에이전트가 유용합니다. 각 역할에 명확한 입력과 출력 경계를 부여하세요. 예를 들어 계획 담당 에이전트가 검증 담당 에이전트의 자격 증명을 그대로 물려받아서는 안 됩니다.

처음에는 각 인계 과정을 확인할 수 있도록 순차 실행으로 시작하세요. 경계가 안정된 뒤에만 병렬 작업, 시간 제한, 재시도를 추가하고, 부분 실패도 일반적인 성공 응답 속에 숨기지 말고 드러내세요.

프로그램이 신뢰할 수 있는 구조화된 출력 반환하기

자유 형식 텍스트는 사람이 읽기에는 편하지만 애플리케이션 로직에는 취약합니다. 결과가 데이터베이스, UI, 테스트, 다음 에이전트로 전달된다면 SDK의 현재 구조화된 출력 기능을 사용하고 작은 스키마로 로컬 검증을 수행하세요.

스키마가 응답을 진실로 만들어 주는 것은 아닙니다. 타입, 허용 값, 필수 필드, 비즈니스 규칙을 확인해야 합니다. 원시 진단 정보는 사용자에게 보여 주는 출력과 분리하세요.

result = agent.run("Classify the fixture.")
validated = {
    "label": result.label,
    "confidence": float(result.confidence),
    "needs_review": bool(result.needs_review),
}
assert validated["label"] in {"pass", "review", "fail"}

• 반환된 객체를 로컬에서 검증하세요.
• 유한한 선택지에는 enum과 길이가 제한된 문자열을 사용하세요.
• 필드가 없거나 형식이 잘못되면 명확한 실패로 처리하세요.
• 진단 정보와 사용자용 출력을 분리하세요.

SDK와 IDE 및 CLI 비교: 알맞은 표면 선택하기

SDK는 에이전트 워크플로를 코드에 넣고, IDE는 대화형 프로젝트 작업에 사용하며, CLI는 터미널 명령과 스크립트에 사용합니다. 모두 같은 기능을 호출하는 다른 버튼으로 생각하기보다 실제 작업을 소유하는 표면을 선택하세요.

각 표면의 릴리스 일정은 서로 다를 수 있습니다. 실제로 사용하는 구성 요소의 출처와 확인 날짜를 기록하세요.

확장 사용 전 보안 및 안정성 점검

SDK는 에이전트를 실제 애플리케이션의 일부로 만들 수 있으므로 패키지 출처, 자격 증명, 네트워크 대상, 로컬 경로, 도구 인자, 로그를 검토해야 합니다. 도구가 외부 데이터에 접근한다면 삭제 가능한 프로젝트와 테스트 계정으로 시작하세요.

파일을 변경하거나 메시지를 보내거나 돈을 쓰거나 계정을 수정하거나 콘텐츠를 게시하는 동작은 승인 과정을 눈에 보이게 유지하세요. 시간 제한과 제한된 재시도를 추가하고, 잘못된 입력, 사용할 수 없는 서비스, 권한 거부, 사람의 검토가 필요한 결과를 서로 구분하세요.

• 자격 증명 — 비밀 저장소를 사용하고 토큰을 Git이나 프롬프트에 저장하지 마세요.
• 경로 — 드라이브 루트나 홈 디렉터리가 아니라 필요한 프로젝트 디렉터리만 허용하세요.
• 동작 — 읽기와 쓰기, 셸, 브라우저, 네트워크 호출을 분리하세요.
• 관찰 가능성 — 식별자, 소요 시간, 결과, 안전한 오류 범주를 기록하세요.
• 복구 — 비활성화, 접근 철회, fixture 재생, 롤백 절차를 문서화하세요.

Antigravity SDK에서 자주 겪는 문제 해결 경로

첫 실행이 실패하면 한 번에 한 변수만 남도록 시스템을 줄여 보세요.

패키지는 설치되지만 import가 실패합니다

가상 환경과 인터프리터를 확인한 뒤 현재 quickstart의 import 경로와 비교하세요. 애플리케이션 코드를 바꾸기 전에 패키지 메타데이터를 확인하세요.

에이전트가 인증 오류를 반환합니다

현재 문서에 나온 자격 증명 출처, 계정 범위, 필요한 권한을 비교하세요. 로그에서 비밀 값을 제거하고 가장 작은 요청을 다시 실행하세요.

도구 호출이 멈추거나 반복됩니다

시간 제한을 추가하고 경계를 기록한 뒤 고정 입력으로 도구를 테스트하세요. 재시도는 제한하고, 정체를 알 수 없는 쓰기 작업을 자동으로 반복하지 마세요.

구조화된 출력이 불완전합니다

스키마를 더 작게 만들고 필수 필드를 로컬에서 검증하세요. 거부, 잘림, 잘못된 데이터는 성공이 아니라 검토 상태로 처리하세요.

버전 스냅샷과 공식 출처 원칙

2026년 9월 12일 PyPI에는 google-antigravity v0.1.16이 표시되었습니다. 공식 목록에는 데스크톱 v2.13.0, CLI v1.2.0, IDE v2.5.5가 표시되었으며, 이 표면들은 서로 독립적으로 바뀔 수 있습니다.

현재 공식 설치 페이지를 사용하고 실제 설치된 버전을 기록하세요. 공식 다운로드 페이지는 데스크톱과 CLI에 대한 안내용 대체 출처로 남겨 두세요.