본문으로 건너뛰기
테마
폰트
크기
A A

Antigravity SDK (Python) — 코드로 에이전트 구축

Antigravity SDK는 Antigravity 데스크톱·CLI와 같은 에이전트 하네스를 Python 코드에서 직접 호출할 수 있는 라이브러리입니다. UI에서 만든 Skills·Hooks·MCP 설정이 그대로 호환되며, CI·서버·자동화 스크립트 어디서나 같은 에이전트를 띄울 수 있습니다. 공식 문서 — SDK Overview

이 페이지의 목적: Antigravity SDK의 개념·설치·기본 사용법을 한국어로 정리합니다. 정확한 API 시그니처와 최신 클래스 필드는 변동이 잦으므로 공식 저장소 READMEPyPI 페이지를 함께 참고하세요.
지원 환경: Python 3.10 이상. 현재 Linux·macOS용 wheel만 제공(2026-05 기준). Windows는 WSL2 안에서 동작. 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계층 아키텍처

Antigravity SDK 3계층 구조
계층핵심 클래스역할
진입점Agent가장 단순한 진입점. async context manager로 lifecycle 관리 — 바이너리 탐색, 도구 와이어링, 정책 기본값 적용까지 한 번에.
세션Conversation상태 유지가 필요한 다중 턴 대화 세션. 한 conversation 안에서 컨텍스트가 누적.
전송Connection실제 모델·도구와의 통신 추상화. 일반 사용자는 직접 다룰 일 거의 없음.

대부분의 사용자는 Agent 한 클래스만 알면 됩니다. 더 정교한 제어가 필요할 때 Conversation 단계로 내려가는 구조입니다.

2. 설치 & 인증 #

2.1 설치 — PyPI에서

pip / uv
# 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 키 발급

  1. Google AI Studio에서 API 키 발급
  2. 키를 환경변수 또는 코드에 전달 (아래 3가지 방법 중 택일)
방법 1 — 환경변수 (권장)
export GEMINI_API_KEY="your_key_here"
방법 2 — LocalAgentConfig에 직접 전달
from google_antigravity import Agent, LocalAgentConfig

config = LocalAgentConfig(api_key="your_key_here")
방법 3 — GeminiConfig 별도 구성
from google_antigravity import GeminiConfig

gemini_config = GeminiConfig(api_key="your_key_here")
키 노출 방지: 절대 코드에 평문으로 커밋하지 마세요. .env + deny 패턴·direnv·mise·1password-cli 등을 활용합니다.

3. Hello World — 최소 예제 #

hello.py — 가장 단순한 동기 응답
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())

위 코드는 다음 흐름을 한 줄씩 수행합니다.

  1. LocalAgentConfig 생성 — 시스템 지시문·키·정책 등 에이전트 기본 설정 묶음
  2. Agent를 async context manager로 진입 — 바이너리 시작·도구 등록·세션 준비
  3. agent.chat() 호출 — 자연어 입력에 대한 응답을 비동기로 받음
  4. context manager 종료 — 정상·예외 어느 쪽이든 리소스 정리

스트리밍 응답

stream.py — 토큰이 도착하는 대로 출력
async with Agent(config) as agent:
    response = agent.chat("긴 설명이 필요한 질문")
    async for chunk in response:
        print(chunk, end="", flush=True)

ChatResponse 객체는 async for로 순회하면 도착하는 토큰 단위로 문자열을 내보냅니다. 사용자에게 답이 점진적으로 표시되는 채팅 UI를 만들 때 자연스럽습니다.

멀티모달 입력

multimodal.py — 이미지·문서 첨부
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 함수에 데코레이터를 붙여 도구로 등록합니다. 시그니처의 타입 힌트가 자동으로 도구 스키마가 됩니다.

custom_tool.py
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 등)를 그대로 도구로 노출시킵니다.

mcp_server.py
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)와 같은 개념입니다.

policies.py
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를 전달합니다.

capabilities.py
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)으로 시작해 필요한 능력만 명시적으로 활성화합니다.

CapabilitiesConfig 주요 필드
필드기본값언제 켜는가
can_write_filesFalse코드 생성·파일 수정이 필요한 경우만
can_run_commandsFalse빌드·테스트 실행이 필요한 경우만. 정책으로 명령 패턴 좁히기 필수
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"),  # 그 외 명령은 사용자 확인
]
관련 페이지: SDK의 정책 시스템은 데스크톱 앱의 Unified Permissions 및 Claude Code 스타일 Permissions 패턴과 같은 발상에서 출발합니다. 패턴 작성 팁은 두 페이지를 참고하세요. 인프라 보안 맥락은 Harness Engineering 보안 레이어에서 다룹니다.

6. A2A 프로토콜 — 에이전트 간 상호운용 2.0 신규 #

Agent2Agent (A2A)서로 다른 프레임워크로 만들어진 에이전트들이 통신·협업할 수 있는 개방형 프로토콜입니다. 2025년 4월 Google이 공개한 뒤 150+ 조직이 채택했으며, Antigravity 2.0 SDK에 정식 통합됐습니다. Antigravity 에이전트가 LangChain·AutoGen·LangGraph·BeeAI·Google ADK로 만든 외부 에이전트와 task를 주고받을 수 있습니다.

A2A vs MCP — 역할 분담
MCP — 에이전트 ↔ 도구

에이전트가 도구(GitHub, Slack, DB 등)를 호출. 단방향 호출, 결과 반환. "이 도구를 써서 작업해달라"는 위임.

A2A — 에이전트 ↔ 에이전트

에이전트가 다른 에이전트에게 작업 위임. 양방향 대화 가능, 진행 상태 스트리밍. "이 작업을 당신이 더 잘하니 맡아달라"는 위임.

6.1 A2A의 3가지 핵심 요소

A2A 핵심 요소
요소역할기술
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 엔드포인트를 띄웁니다.

a2a_server.py — 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으로 만든 검색 에이전트)에게 작업을 위임:

a2a_client.py — 외부 A2A 에이전트 호출
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 지원)
예시 — LangChain 검색 에이전트와 협업
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 보안 & 인증

⚠️ A2A 서버 공개 시 필수 확인 사항:
  • 인증 토큰 — Agent Card의 authentication 필드에 OAuth2/Bearer 명시. 익명 공개는 prototype 외 금지.
  • 레이트 리밋 — 외부 호출자가 무한 task를 보낼 수 있으므로 IP·토큰별 제한 필수.
  • capabilities 화이트리스트 — Agent Card에 명시한 capability 외 작업은 거부하도록 SDK 정책 설정.
  • 로깅 — 모든 task 요청·결과를 audit log로 저장 (외부 에이전트가 보낸 지시 추적용).

6.6 학습 자료

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 알림 → 사람에게 검토 요청.

오늘코드 Antigravity 튜토리얼 — Google Antigravity 공식 문서 기반 한국어 학습 가이드

이 튜토리얼은 비공식 학습 자료입니다. 공식 문서: antigravity.google/docs

오늘코드