Antigravity SDK (Python) — 코드로 에이전트 구축
Antigravity SDK는 Antigravity 데스크톱·CLI와 같은 에이전트 하네스를 Python 코드에서 직접 호출할 수 있는 라이브러리입니다. UI에서 만든 Skills·Hooks·MCP 설정이 그대로 호환되며, CI·서버·자동화 스크립트 어디서나 같은 에이전트를 띄울 수 있습니다. 공식 문서 — SDK Overview
git clone만으로는 동작하지 않으며 반드시 PyPI에서 빌드된 wheel을 설치해야 합니다 — 컴파일된 runtime 바이너리가 wheel에 포함돼 있기 때문입니다.
1. 왜 SDK가 필요한가? #
Antigravity IDE·2.0 데스크톱·CLI(agy)는 사람이 키보드로 대화하는 방식에 최적화되어 있습니다. 반면 SDK는 같은 에이전트를 코드로 운영해야 하는 다음 상황에 유용합니다.
- CI/CD 파이프라인 — PR이 열릴 때마다 변경 사항을 에이전트가 자동 분석·요약
- 외부 시스템 통합 — Slack 봇·Jira 자동화·내부 도구에서 Antigravity 에이전트 호출
- 대량 반복 작업 — 수백 개 파일에 같은 규칙을 적용하거나 점검
- 커스텀 UI — 사내 도구에 대화 UI를 임베드하면서 백엔드만 Antigravity로
- 장기 실행 작업 — 백그라운드에서 외부 이벤트에 반응하는 trigger 기반 자동화
3계층 아키텍처
| 계층 | 핵심 클래스 | 역할 |
|---|---|---|
| 진입점 | Agent | 가장 단순한 진입점. async context manager로 lifecycle 관리 — 바이너리 탐색, 도구 와이어링, 정책 기본값 적용까지 한 번에. |
| 세션 | Conversation | 상태 유지가 필요한 다중 턴 대화 세션. 한 conversation 안에서 컨텍스트가 누적. |
| 전송 | Connection | 실제 모델·도구와의 통신 추상화. 일반 사용자는 직접 다룰 일 거의 없음. |
대부분의 사용자는 Agent 한 클래스만 알면 됩니다. 더 정교한 제어가 필요할 때 Conversation 단계로 내려가는 구조입니다.
2. 설치 & 인증 #
2.1 설치 — PyPI에서
# pip
pip install google-antigravity
# uv (빠르고 가상환경 자동 관리)
uv add google-antigravity
# 한 번만 실행
uvx --from google-antigravity python -c "from google_antigravity import Agent"
2.2 인증 — Gemini API 키 발급
- Google AI Studio에서 API 키 발급
- 키를 환경변수 또는 코드에 전달 (아래 3가지 방법 중 택일)
export GEMINI_API_KEY="your_key_here"
from google_antigravity import Agent, LocalAgentConfig
config = LocalAgentConfig(api_key="your_key_here")
from google_antigravity import GeminiConfig
gemini_config = GeminiConfig(api_key="your_key_here")
3. Hello World — 최소 예제 #
import asyncio
from google_antigravity import Agent, LocalAgentConfig
async def main():
config = LocalAgentConfig(
system_instructions="너는 친절한 한국어 코딩 도우미야."
)
async with Agent(config) as agent:
response = await agent.chat("현재 디렉터리에 어떤 파일이 있는지 알려줘")
print(response.text)
asyncio.run(main())
위 코드는 다음 흐름을 한 줄씩 수행합니다.
- LocalAgentConfig 생성 — 시스템 지시문·키·정책 등 에이전트 기본 설정 묶음
- Agent를 async context manager로 진입 — 바이너리 시작·도구 등록·세션 준비
- agent.chat() 호출 — 자연어 입력에 대한 응답을 비동기로 받음
- context manager 종료 — 정상·예외 어느 쪽이든 리소스 정리
스트리밍 응답
async with Agent(config) as agent:
response = agent.chat("긴 설명이 필요한 질문")
async for chunk in response:
print(chunk, end="", flush=True)
ChatResponse 객체는 async for로 순회하면 도착하는 토큰 단위로 문자열을 내보냅니다. 사용자에게 답이 점진적으로 표시되는 채팅 UI를 만들 때 자연스럽습니다.
멀티모달 입력
from pathlib import Path
async with Agent(config) as agent:
response = await agent.chat(
"이 스크린샷의 차트가 어떤 추세를 보여주는지 설명해줘",
attachments=[Path("./reports/2026-q1.png")],
)
print(response.text)
이미지·비디오·오디오·문서를 함께 전달할 수 있습니다. Gemini 모델의 멀티모달 능력이 그대로 노출됩니다.
4. 핵심 기능 6종 #
Agent 클래스 한 줄로 시작해도, 점진적으로 다음 6가지를 끼워 넣어 본격적인 자동화로 확장할 수 있습니다.
4.1 커스텀 도구 — Python 함수가 곧 도구
일반 Python 함수에 데코레이터를 붙여 도구로 등록합니다. 시그니처의 타입 힌트가 자동으로 도구 스키마가 됩니다.
from google_antigravity import Agent, LocalAgentConfig, tool
@tool
def get_weather(city: str) -> str:
"""주어진 도시의 현재 날씨를 조회한다."""
# 실제로는 외부 API 호출
return f"{city}는 흐림, 18도"
config = LocalAgentConfig(tools=[get_weather])
async with Agent(config) as agent:
response = await agent.chat("서울 날씨 알려줘")
print(response.text)
4.2 MCP 서버 연결
외부 MCP 서버(GitHub·Slack·DB 등)를 그대로 도구로 노출시킵니다.
from google_antigravity import Agent, LocalAgentConfig, McpStdioServer
github_mcp = McpStdioServer(
command="npx",
args=["-y", "@modelcontextprotocol/server-github"],
env={"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."},
)
config = LocalAgentConfig(mcp_servers=[github_mcp])
async with Agent(config) as agent:
response = await agent.chat("내 저장소에서 오늘 새로 열린 이슈 목록 보여줘")
print(response.text)
같은 MCP 정의가 Antigravity IDE·CLI·SDK에서 모두 동일하게 동작합니다. 한 번 설정하면 어디서 호출하든 같은 도구가 제공됩니다.
4.3 정책 (Policies)
각 도구·도구 호출 패턴에 대해 사전 정책을 선언합니다. Unified Permissions(Allow/Ask/Deny)와 같은 개념입니다.
from google_antigravity import (
Agent, LocalAgentConfig,
allow, deny, ask_user,
)
config = LocalAgentConfig(
policies=[
allow("read_file"), # 읽기는 자동 허용
ask_user("write_file"), # 쓰기는 사용자 확인
deny("run_terminal_command", args="rm -rf*"), # rm -rf는 영구 차단
]
)
4.4 Capabilities — 기본 안전 모드
Agent는 기본적으로 read-only 모드입니다. 파일 쓰기·실행 같은 위험 도구를 활성화하려면 명시적으로 CapabilitiesConfig를 전달합니다.
from google_antigravity import Agent, LocalAgentConfig, CapabilitiesConfig
config = LocalAgentConfig(
capabilities=CapabilitiesConfig(
can_write_files=True,
can_run_commands=True,
)
)
이 두 단계 보안(기본 read-only + 정책 선언)은 SDK가 자동화 환경에서 의도치 않은 파괴 작업을 일으키지 않도록 막는 가장 중요한 장치입니다.
4.5 Triggers — 외부 이벤트에 반응
Trigger는 외부 신호(웹훅·파일 변경·스케줄 등)에 반응해 에이전트에 메시지를 자동 푸시합니다. 사용자가 직접 메시지를 보내지 않아도 백그라운드 자동 실행이 가능합니다.
- CI 후속 분석 — 빌드 실패 웹훅 → 로그 분석 메시지 자동 푸시
- 모니터링 알림 — Datadog 알림 → 관련 코드 검토 메시지
- 주기 실행 — cron-style trigger로 일일 리포트 생성
4.6 Hooks — 턴 전·후 자동화
매 턴 시작 전·종료 후에 실행되는 함수를 등록합니다. Claude Code의 preTurn/postTurn 개념과 유사합니다. 로깅·메트릭·자동 포맷팅 같은 횡단 관심사를 한 곳에 모을 수 있습니다.
5. 정책 & Capabilities 안전 가이드 #
SDK는 사람이 직접 보지 않는 환경(CI·서버·스케줄)에서 돌아가는 경우가 많아 UI 기반 사용보다 사고 위험이 큽니다. 다음 두 단계를 함께 적용하는 것을 권장합니다.
단계 1 — Capabilities를 최소만 켜기
기본값(read-only)으로 시작해 필요한 능력만 명시적으로 활성화합니다.
| 필드 | 기본값 | 언제 켜는가 |
|---|---|---|
can_write_files | False | 코드 생성·파일 수정이 필요한 경우만 |
can_run_commands | False | 빌드·테스트 실행이 필요한 경우만. 정책으로 명령 패턴 좁히기 필수 |
can_use_network | 기본 제한 (변경 가능) | 외부 API 호출이 필요한 경우만. 화이트리스트 도메인과 함께 |
단계 2 — 정책으로 추가 좁히기
Capabilities로 큰 카테고리를 켰다면, 정책으로 구체 패턴까지 좁힙니다.
policies=[
# 읽기는 안전 — 자동 허용
allow("read_file", path="reports/**"),
allow("read_file", path="data/processed/**"),
# 결과 파일 작성은 reports만 허용
allow("write_file", path="reports/**"),
ask_user("write_file"), # 그 외는 사용자 확인
# 분석 명령만 자동 허용
allow("run_terminal_command", args="uv run pytest:*"),
allow("run_terminal_command", args="git diff:*"),
deny("run_terminal_command", args="rm -rf:*"),
deny("run_terminal_command", args="git push --force:*"),
ask_user("run_terminal_command"), # 그 외 명령은 사용자 확인
]
6. A2A 프로토콜 — 에이전트 간 상호운용 2.0 신규 #
Agent2Agent (A2A)는 서로 다른 프레임워크로 만들어진 에이전트들이 통신·협업할 수 있는 개방형 프로토콜입니다. 2025년 4월 Google이 공개한 뒤 150+ 조직이 채택했으며, Antigravity 2.0 SDK에 정식 통합됐습니다. Antigravity 에이전트가 LangChain·AutoGen·LangGraph·BeeAI·Google ADK로 만든 외부 에이전트와 task를 주고받을 수 있습니다.
에이전트가 도구(GitHub, Slack, DB 등)를 호출. 단방향 호출, 결과 반환. "이 도구를 써서 작업해달라"는 위임.
에이전트가 다른 에이전트에게 작업 위임. 양방향 대화 가능, 진행 상태 스트리밍. "이 작업을 당신이 더 잘하니 맡아달라"는 위임.
6.1 A2A의 3가지 핵심 요소
| 요소 | 역할 | 기술 |
|---|---|---|
| Agent Card | 에이전트의 능력·엔드포인트 공개 (서비스 디스커버리) | JSON 메타데이터, /.well-known/agent.json |
| Tasks | 에이전트 간 주고받는 작업 단위 (요청·진행·결과) | JSON-RPC 2.0 |
| Transports | 실시간 상태 스트리밍, 장시간 작업 지원 | HTTP + Server-Sent Events (SSE) |
6.2 Antigravity 에이전트를 A2A 서버로 노출
SDK로 만든 Antigravity 에이전트를 외부 에이전트가 호출할 수 있도록 A2A 엔드포인트를 띄웁니다.
from antigravity import Agent
from antigravity.a2a import A2AServer
agent = Agent(
name="data-analyst",
description="CSV·데이터프레임 분석 전문 에이전트",
skills=["data-analysis", "pandas-helpers"],
)
server = A2AServer(
agent=agent,
agent_card={
"name": "data-analyst",
"description": "Data analysis tasks (EDA, pandera schema, ydata-profiling)",
"version": "1.0",
"capabilities": ["analyze_csv", "infer_schema", "generate_report"],
},
)
# HTTP 서버 시작 (포트 8080, /.well-known/agent.json 자동 노출)
server.run(host="0.0.0.0", port=8080)
6.3 외부 A2A 에이전트 호출
반대로 Antigravity 에이전트가 외부 A2A 에이전트(예: LangChain으로 만든 검색 에이전트)에게 작업을 위임:
from antigravity import Agent
from antigravity.a2a import A2AClient
# 외부 A2A 에이전트의 Agent Card 자동 발견
search_agent = A2AClient.from_url("https://search-service.example.com")
# Task 전달 — 결과는 스트림으로 받음
task = search_agent.send_task(
instruction="2026년 5월 Antigravity 관련 최신 블로그 5개를 찾아 요약",
on_progress=lambda event: print(f"진행: {event['status']}"),
)
result = task.wait_for_completion(timeout=300)
print(result.output)
# 본 에이전트는 결과를 받아 후속 처리
agent = Agent(name="orchestrator")
agent.process(f"다음 검색 결과를 마크다운 보고서로 정리: {result.output}")
6.4 LangChain / AutoGen / LangGraph 상호운용
A2A는 프레임워크 중립 표준입니다. 다음 같은 조합이 가능합니다:
- Antigravity ↔ LangChain — LangChain의 RAG 에이전트를 A2A 서버로 띄우고, Antigravity가 호출
- Antigravity ↔ AutoGen — AutoGen의 multi-agent 시뮬레이션 결과를 Antigravity가 가져와 코드로 구현
- Antigravity ↔ LangGraph — LangGraph의 stateful 워크플로우 노드를 Antigravity가 도구처럼 호출
- Antigravity ↔ Google ADK — ADK 에이전트와 직접 통신 (양쪽 모두 1급 A2A 지원)
from antigravity import Agent
from antigravity.a2a import A2AClient
# LangChain 팀이 운영하는 A2A 검색 서버
langchain_search = A2AClient.from_url("https://lc-search.team-x.com")
# Antigravity 에이전트 — 코딩 전문
coder = Agent(name="coder", skills=["python", "code-review"])
# 협업: LangChain이 정보 수집, Antigravity가 코드 작성
search_result = langchain_search.send_task(
instruction="pandas 2.3의 새 API 5가지 검색"
).wait_for_completion()
coder.process(
f"다음 새 API들을 사용하는 예제 코드를 작성:\n{search_result.output}"
)
6.5 보안 & 인증
- 인증 토큰 — Agent Card의
authentication필드에 OAuth2/Bearer 명시. 익명 공개는 prototype 외 금지. - 레이트 리밋 — 외부 호출자가 무한 task를 보낼 수 있으므로 IP·토큰별 제한 필수.
- capabilities 화이트리스트 — Agent Card에 명시한 capability 외 작업은 거부하도록 SDK 정책 설정.
- 로깅 — 모든 task 요청·결과를 audit log로 저장 (외부 에이전트가 보낸 지시 추적용).
6.6 학습 자료
- A2A 공식 GitHub (a2aproject/A2A) — 사양, SDK, 예제
- Announcing the A2A Protocol — Google Developers Blog (2025-04)
- MCP 페이지 — A2A의 보완 프로토콜 (도구 호출용)
7. 활용 시나리오 #
6.1 PR 자동 리뷰 봇
GitHub Actions에서 PR이 열리면 SDK를 호출해 변경 사항을 분석하고 코멘트를 남깁니다. Antigravity IDE에서 직접 했을 작업을 봇이 수행.
6.2 일일 분석 리포트 발행
cron으로 매일 오전 9시에 트리거 → 어제 데이터로 KPI 계산 → 마크다운 보고서 생성 → Slack·이메일로 발송. Antigravity 2.0의 Scheduled Tasks와 결합 가능.
6.3 사내 챗봇 백엔드
사내 Slack 봇·Teams 봇이 SDK로 Antigravity 에이전트를 호출. 기업 컨텍스트·MCP·정책은 워크스페이스 설정으로 관리하고, 인터페이스만 사내 도구.
6.4 대량 코드베이스 리팩터링
한 번에 100개 파일에 같은 패턴을 적용해야 할 때 — 데스크톱 UI에서 한 파일씩 처리하기 너무 큰 작업을 SDK로 배치 실행. 각 파일마다 새 Conversation을 띄워 병렬화.
6.5 데이터 분석 결과 검증
분석 노트북이 만든 결과 CSV를 SDK 에이전트가 받아 정합성 점검 → 이상치 발견 시 Slack 알림 → 사람에게 검토 요청.