google-antigravity/antigravity-sdk-python

Google Antigravity SDK (Python)

무엇인가요 – Google의 Gemini 모델(또는 로컬 Gemma-4 모델)을 기반으로 "에이전트형" AI 애플리케이션을 구축할 수 있는 Python 라이브러리입니다. SDK는 에이전트 루프의 저수준 구현(네트워킹, 도구 실행, 상태 관리)을 숨기므로, 에이전트가 수행해야 할 작업에만 집중할 수 있습니다.

설치

pip install google-antigravity   # 플랫폼별 바이너리 웨일을 다운로드

바이너리 런타임이 필요합니다. 리포지토리만 클론해도 작동하지 않습니다.

시작하기

import asyncio
from google.antigravity import Agent, LocalAgentConfig

async def main():
    cfg = LocalAgentConfig(system_instructions="You are a helpful assistant.")
    async with Agent(cfg) as agent:
        resp = await agent.chat("List the files in the current directory.")
        print(await resp.text())

asyncio.run(main())

GEMINI_API_KEY (또는 Vertex AI 자격 증명)을 설정한 후 examples/ 폴더의 예제 스크립트를 실행하세요.

주요 개념

개념	기능
Agent	고수준 진입점; 바이너리 탐지, 도구 연결, 정책 관리, 스트리밍 응답을 관리합니다.
Conversation	상태를 유지하는 세션으로, 단계 기록을 보관합니다. 메시지 전송/수신에 대한 세밀한 제어가 필요한 경우 유용합니다.
LocalAgentConfig / LiteRTAgentConfig	클라우드(Gemini/Vertex) 또는 오프라인(Gemma-4 via LiteRT-LM) 모델용 구성 객체입니다.
Tools	에이전트가 채팅 중에 호출할 수 있는 일반적인 Python 함수를 등록합니다.
Hooks & Policies	도구 실행 허용 여부 및 조건을 제어하는 선언적 규칙(allow, deny, ask_user, enforce)입니다.
Triggers	백그라운드 비동기 작업으로, 에이전트에 메시지를 전달할 수 있습니다(예: 주기적인 상태 점검).
MCP 통합	외부 Model Context Protocol 서버에 연결하여 추가 도구를 노출합니다.

주요 기능

• 클라우드 및 로컬 실행 통합 – Vertex AI(키 또는 ADC)를 통해 Gemini 사용 또는 LiteRT-LM을 통해 오프라인으로 Gemma-4 26B 실행.
• 스트리밍 출력 – ChatResponse (또는 그 thoughts / tool_calls)를 반복하여 추가 네트워크 비용 없이 토큰 단위 업데이트를 얻을 수 있습니다.
• 다중 모달 입력 – Image, from_file 등의 콘텐츠 클래스를 통해 이미지, PDF, 동영상 등을 직접 첨부할 수 있습니다.
• 사용자 정의 도구 등록 – 어떤 Python 호출 가능 함수도 에이전트가 호출할 수 있는 도구로 변환할 수 있습니다.
• 정책 엔진 – 세밀한 안전성 제어(모든 도구 차단, 특정 도구만 허용, 위험한 작업 전 사용자에게 확인 요청).
• 백그라운드 트리거 – 주기적 또는 이벤트 기반 작업으로 에이전트에 메시지를 전달할 수 있습니다.
• 세 층 아키텍처 – 간단한 Agent API, 세션 수준의 Conversation 계층, 트랜스포트에 독립적인 어댑터 계층.

일반적인 워크플로우

1. 패키지 설치 (로컬 실행 계획 시 litert-lm도 필요).
2. 구성 선택:
   • 클라우드: LocalAgentConfig(vertex=True, api_key=…) 또는 ADC에 의존.
   • 로컬: LiteRTAgentConfig(model_path=…).
3. 선택적으로 도구, 정책, 트리거 등록.
4. async with 블록 내에서 Agent (또는 Conversation) 생성.
5. agent.chat(prompt) 호출 – 프롬프트는 문자열 또는 텍스트와 콘텐츠 객체의 혼합 리스트 가능.
6. await resp.text()로 응답 소비 또는 async for token in resp로 스트리밍 토큰 소비.

아키텍처 스냅샷

계층	책임	핵심 클래스
간소화	대부분의 사용 사례에 대한 단일 라인 진입점	Agent
세션	기록 유지, chat() 제공, 스트리밍 객체 노출	Conversation, ChatResponse, Step, ToolCall, AgentConfig, HookRunner, ToolRunner, TriggerRunner
어댑터	전송 방식(클라우드, 로컬 바이너리, MCP)을 추상화	Connection, ConnectionStrategy, LocalConnection

라이선스 – Apache License 2.0.

---

위 모든 세부 정보는 리포지토리의 README에서 직접 인용되었습니다.