AI 기술 설명 – 안티그래비티 에이전트(Antigravity Agent) – API 호출 한 번으로 일을 맡기는 관리형 에이전트
안티그래비티 에이전트(Antigravity Agent)는 Gemini API에서 쓸 수 있는 범용 관리형 에이전트(Managed Agent)입니다. 공식 문서는 API 호출 한 번으로 추론하고, 코드를 실행하고, 파일을 관리하고, 웹을 탐색하는 에이전트를 구글이 호스팅하는 리눅스 샌드박스에서 받는다고 소개해요.
앞선 글에서 하네스를 직접 짜는 이야기를 했는데, 이 에이전트는 반대쪽에 있습니다. 문서에 따르면 안티그래비티 IDE와 같은 하네스를 쓰고, 기본 모델은 Gemini 3.8 Flash입니다. 하네스와 실행 환경을 내가 꾸리지 않고 호출 한 번으로 빌려 쓰는 구조인 셈이죠.
안티그래비티 에이전트에 일을 맡기는 구조
문서의 첫 예제는 interactions.create에 에이전트 이름, 할 일, 환경 세 가지를 넘기는 것이 전부입니다. 에이전트 이름은 antigravity-preview-09-2026이고, 할 일은 “Hacker News를 읽고 상위 10개 글을 요약해 PDF로 저장하라”는 문장이에요. environment를 "remote"로 주면 기본 설정의 새 샌드박스가 만들어집니다.
호출마다 샌드박스를 만들거나 이어 쓰고 도구 사용 루프(Tool-use Loop)를 시작하는데, 문서는 이 루프를 “계획하고, 행동하고, 결과를 보고, 일이 끝날 때까지 반복한다”고 적었습니다. 코드 실행은 Bash, Python, Node.js 명령을 돌리고 패키지 설치와 테스트, 앱 빌드까지 포함해요. 샌드박스 안의 파일은 상호작용(Interaction)이 바뀌어도 남습니다.
긴 작업을 위해 컨텍스트 압축(Context Compaction)도 자동으로 돌아갑니다. 문서에 적힌 기준은 약 135k 토큰이에요. 컨텍스트 엔지니어링 글에서 다룬 문제를 서비스 쪽에서 대신 처리해 주는 부분입니다.
기본 도구와 직접 붙이는 도구
tools를 적지 않으면 code_execution, google_search, url_context가 기본으로 열립니다. 파일 도구는 environment를 지정하면 자동으로 켜지고요. 도구를 줄이고 싶으면 필요한 것만 tools에 넘기면 됩니다. 검색과 URL 읽기만 허용하는 예제가 문서에 있어요.
| 도구 | 종류 값 | 하는 일 |
|---|---|---|
| 코드 실행 | code_execution |
Bash, Python, Node 명령을 돌리고 출력을 받는다 |
| 구글 검색 | google_search |
공개 웹을 검색한다 |
| URL 컨텍스트 | url_context |
웹 페이지를 가져와 읽는다 |
| 사용자 정의 함수 | function |
내 API를 에이전트가 요청하면 내가 실행한다 |
| 원격 MCP 서버 | mcp_server |
외부 서버를 도구로 등록한다 |
MCP 연결은 type에 mcp_server, 고유 이름 name, 서버 주소 url을 적는 방식이에요. 헤더(headers)로 인증값을 보낼 수 있고 allowed_tools로 실행을 허용할 도구를 좁힐 수 있습니다. 원격 MCP 서버는 스트리머블 HTTP(Streamable HTTP)로 연결하고, 서버 이름은 소문자와 숫자, _, -만 써야 해요.
사용자 정의 함수는 한 번 더 왕복합니다. 에이전트가 함수 호출을 요청하면 상태가 requires_action이 되고, 내가 함수를 실행해 previous_interaction_id와 함께 결과를 돌려보내는 방식이에요. 같은 샌드박스를 이어 쓰려면 environment에 이전 결과의 environment_id 값을 넘깁니다.
지시문과 스킬을 샌드박스에 올리기
문서는 에이전트를 파일 중심으로 꾸미는 방식을 소개합니다. 지시문은 AGENTS.md로, 스킬은 .agents/skills/ 아래에 샌드박스로 올려 두는 식이에요. 호출할 때 설정을 직접 넘겨 보다가 마음에 들면 관리형 에이전트로 저장할 수도 있습니다. 자세한 방법은 문서의 에이전트 만들기 글로 넘겨지고, 이 글에서는 거기까지 읽지 않았어요.
앞서 정리한 에이전트 스킬과 같은 이름의 폴더라서 연결해 본 것은 제 해석입니다. 다만 어떤 형식의 스킬 파일을 읽는지는 위 문서에서 확인한 내용이 아니라서 여기서는 위치만 적습니다.
샌드박스는 새로 만들 수도, 이어 쓸 수도 있다
environment 값은 세 가지 모양을 받습니다. "remote"는 기본 설정의 새 샌드박스를 만들고, "env_abc123"처럼 환경 ID를 적으면 기존 샌드박스를 파일과 상태 그대로 다시 씁니다. 세 번째는 소스와 네트워크 규칙을 담은 EnvironmentConfig 객체예요.
문서의 토큰 상한 예제는 이 객체 형태를 써서 inline 소스로 /workspace/data.csv 파일을 샌드박스에 넣어 주고 “이 데이터를 분석해 요약 보고서를 만들라”고 시킵니다. 소스 종류와 네트워킹, 수명, 자원 한도는 별도의 환경 문서가 맡고 있고, 이 글에서는 거기까지 읽지 않았어요.
코드 실행과 파일 도구의 실행에 검사를 끼우고 싶다면 문서의 훅(Hooks)을 보라고 안내합니다. 샌드박스 안에서 동기 방식으로 code_execution과 파일 작업을 가로채 검증하는 기능이에요. 동작을 통제하고 싶다면 이 문서를 먼저 읽어 볼 만합니다.
입력으로 줄 수 있는 것
안티그래비티 에이전트가 받는 입력은 현재 텍스트와 이미지뿐이고, 이미지는 base64로 인코딩한 문자열(data)과 mime_type을 함께 넣는 방식이에요. 문서의 예제는 차트 이미지를 주고 “추세를 요약하라”고 시킵니다. 오디오, 비디오, 문서 입력은 아직 지원하지 않는다고 제한 사항에 적혀 있어요.
모델 선택과 토큰 상한
agent_config를 생략하면 기본 모델 gemini-3.8-flash가 쓰입니다. 바꿀 수 있는 값은 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash, 3.5 Flash-Lite 다섯 가지예요. agents.create로 저장한 관리형 에이전트는 모델이 만들 때 고정되고 호출 시점에 바꿀 수 없다고 문서에 적혀 있습니다.
비용은 모델 토큰과 에이전트가 쓴 도구에 따라 종량제로 붙습니다. 문서는 이런 상호작용이 자율 루프를 도는 만큼 토큰을 많이 쓸 수 있으니 예산 제어를 걸라고 권해요. agent_config에 "type": "antigravity"와 함께 max_total_tokens를 넣으면 입력, 출력, 생각 토큰의 합계가 제한됩니다.
한도에 닿으면
캐시된 토큰은 한도에 세지 않습니다. 한도에 닿으면 상호작용이 멈추고 status가 incomplete로 돌아와요. 한도는 단계 사이에 확인하기 때문에 조금 넘을 수 있다고 문서가 밝힙니다. 이때 원래 상호작용의 id와 environment_id를 넘겨 새 상호작용을 만들면 작업과 컨텍스트가 보존된 채 이어지고, 새 상호작용은 자기 몫의 max_total_tokens를 따로 받습니다.
문서는 작업 종류별 추정치도 싣고 있어요. 조사와 정보 종합은 입력 100k에서 500k 토큰에 보통 $0.30에서 $1.00이고, 데이터 처리와 분석은 300k에서 3M 토큰에 $0.70에서 $3.25입니다. 도구 호출이 많은 복잡한 작업은 한 번에 3~5백만 토큰까지 쌓여 최대 약 $5에 이른다고 해요. 프리뷰 기간에는 환경 컴퓨팅(CPU, 메모리, 샌드박스 실행)에 요금이 붙지 않습니다. 이 수치는 문서가 실행 사례로 잡은 추정이라 내 작업에 그대로 맞지는 않을 수 있습니다. 작업에 따라 에이전트가 도구를 몇 번 부를지 스스로 정하기 때문에, 처음에는 작은 일로 max_total_tokens를 걸고 usage.total_tokens를 찍어 보며 감을 잡는 것이 무난해 보여요.
오래 걸리는 일은 백그라운드와 트리거로
여러 단계를 도는 작업은 몇 분씩 걸릴 수 있어서, background=True로 비동기 실행하고 상호작용 ID를 받아 상태가 completed나 failed가 될 때까지 조회하는 방식이 있습니다. 이 방식은 store=True(기본값)가 필요해요. 실행 중인 상호작용은 취소할 수도 있습니다.
정해진 시간에 안티그래비티 에이전트를 돌리고 싶다면 트리거(Trigger)가 있어요. 에이전트, 환경, 프롬프트, 일정을 하나의 리소스로 묶어 크론 표현식에 맞춰 자동으로 실행하는 기능이고, 실행마다 같은 환경을 재사용해서 앞선 실행이 만든 파일이 다음 실행에도 남습니다. 연속 실패 허용 횟수 기본값은 5회, 실행 제한 시간 기본값은 600초예요.
프리뷰라서 생기는 제한과 버전 교체
안티그래비티 에이전트 문서의 제한 사항 첫 줄이 프리뷰 상태입니다. 이 에이전트와 Interactions API 모두 기능과 스키마가 바뀔 수 있다는 내용이에요. 그 밖에 알아둘 것이 몇 가지 있습니다.
문서에 적힌 제한 사항
temperature,top_p,top_k,stop_sequences,max_output_tokens는 지원하지 않고 400 오류가 난다- 구조화 출력(Structured Output)은 지원하지 않는다
file_search,computer_use,google_maps도구는 아직 쓸 수 없다- 원격 MCP는 SSE 전송을 지원하지 않는다
- 함수 호출은
previous_interaction_id로 잇는 상태 유지 방식만 가능하다 - 입력은 텍스트와 이미지만 받고, 이미지는 base64 문자열로 넣는다
변경 기록도 눈여겨볼 만합니다. 2026년 5월 19일에 antigravity-preview-05-2026이 공개 프리뷰로 나왔고, 9월 17일에 antigravity-preview-09-2026이 이를 대체하면서 05 버전은 10월 5일 종료 예정으로 적혀 있었고 그 날짜는 이미 지났습니다. 지금 05 이름이 막혔는지는 직접 확인하지 못했어요. 원격 샌드박스에서 output_text만 읽는다면 에이전트 이름만 바꾸면 되지만, 도구를 로컬에서 돌리거나 function_call 단계를 읽는다면 내장 도구의 이름과 인자가 달라졌습니다.
이어서 볼 문서
문서 끝의 안내는 멀티턴 대화와 스트리밍을 다루는 퀵스타트(Quickstart), 지시문과 스킬을 담아 에이전트를 저장하는 커스텀 에이전트 문서, 샌드박스 설정을 다루는 환경 문서, 보안 검사를 넣는 훅 문서, 긴 조사를 맡기는 딥 리서치 에이전트(Deep Research Agent) 문서로 이어집니다. 안티그래비티 에이전트는 코드와 파일 작업까지 하는 범용 쪽이고, 딥 리서치 에이전트는 문서가 장문 조사용으로 따로 소개하는 에이전트예요.
이 글에서 읽은 범위는 안티그래비티 에이전트 본문과 변경 기록까지입니다. 직접 호출해 돌려 본 결과는 없어서, 문서가 약속한 동작을 정리한 글로 읽어 주세요.
참고한 공식 문서
본문은 안티그래비티 에이전트 문서와 Gemini API 변경 기록을 읽고 정리했습니다. 프리뷰라서 내용이 바뀔 수 있으니 쓰기 전에 원문을 확인하세요.
안티그래비티 에이전트 자주 묻는 질문
안티그래비티 에이전트가 뭔가요?
Gemini API에서 쓰는 범용 관리형 에이전트입니다. 공식 문서는 API 호출 한 번으로 추론하고, 코드를 실행하고, 파일을 다루고, 웹을 보는 에이전트를 구글이 호스팅하는 리눅스 샌드박스에서 쓸 수 있다고 설명합니다.
토큰이 얼마나 쓰일지 미리 막을 수 있나요?
agent_config에 max_total_tokens를 넣으면 입력, 출력, 생각에 쓴 토큰의 합계를 제한할 수 있습니다. 캐시된 토큰은 세지 않고, 한도에 닿으면 status가 incomplete로 끝납니다. 한도는 최선 노력 방식이라 조금 넘을 수 있다고 문서가 밝힙니다.
지금 바로 서비스에 써도 되나요?
공식 문서는 이 에이전트와 Interactions API가 프리뷰 상태이고 기능과 스키마가 바뀔 수 있다고 적고 있습니다. 구조화 출력과 일부 도구도 아직 지원하지 않으니 쓰려는 기능이 지원 범위에 있는지 문서의 제한 사항부터 확인하는 편이 좋습니다.
글에 나온 규칙 파일과 에이전트는 Claude Code에서 쓰는 방식이고, 공식 안내는 Claude Code 공식 문서에 있습니다.
이 글은 직접 만들고 운영하며 남긴 기록입니다. 적힌 수치는 작성 시점의 제 계정 기준이며, 같은 결과나 수익을 보장하지 않습니다.
One Comment