Molayo

© 2026 Molayo

Qiita헤드라인2026. 06. 27. 21:30

Antigravity SDK로 소스 코드와 일치하지 않는 README 수정해 보기

요약

Antigravity SDK를 사용하여 소스 코드와 일치하지 않는 README 문서를 자동으로 수정하는 에이전트 활용 사례를 소개합니다. 로컬 환경과 연결된 에이전트를 Python 프로그램에서 제어하는 실전적인 방법을 다룹니다.

핵심 포인트

  • Antigravity SDK는 로컬 환경과 연결된 에이전트를 다루는 도구임
  • 문서 유지보수 에이전트를 통해 코드와 문서 간 불일치 해결 시도
  • Gemini API를 기반으로 작동하며 에이전트 실행 시 쿼터 제한 주의 필요

지난번에 Antigravity SDK를 다뤄보았습니다.

처음에는 Antigravity SDK가 무엇인지 잘 몰랐습니다.

LINE SDK나 Slack SDK라면 의미를 알 수 있습니다.

API를 직접 HTTP로 호출하는 대신, 인증이나 요청(Request), 응답(Response) 처리를 사용하기 쉽게 감싸주는 도구입니다.

하지만 Antigravity SDK는 조금 달랐습니다.

이것은 무엇을 래핑(Wrap)하고 있는 것일까.

Gemini API인가.

Antigravity라는 앱인가.

아니면 에이전트(Agent)라는 작업 단위 그 자체인가.

그래서 공식 샘플을 실행해 보았습니다.

hello_world.py는 Agent와 대화하는 최소한의 예시였습니다.

quick_start.py에서는 Agent가 현재 디렉터리(Current directory)를 확인하여 파일 목록을 반환해 주었습니다.

여기서 조금씩 보이기 시작했습니다.

Antigravity SDK는 단순한 채팅 API의 래퍼(Wrapper)가 아닌 것 같습니다.

로컬 환경과 연결된 Agent를 자신의 Python 프로그램에서 다루기 위한 부품처럼 보입니다.

이번에는 조금 더 실전적인 샘플로 들어가 보겠습니다.

테스트할 것은 공식 리포지토리(Repository)의 Deep Dives에 있는 doc_maintenance_agent.py입니다.

소스 코드와 어긋난 README를 Antigravity SDK의 에이전트로 수정할 수 있을까.

반중력의 불씨에 약간의 투혼을 주입해 보겠습니다.

이번 대상은 직접 준비한 작은 Node.js 프로젝트입니다.

이 프로젝트는 일부러 구현 내용과 Markdown 문서의 내용을 다르게 설정했습니다.

리포지토리 설명은 다음과 같습니다.

A tiny app where the code tells the truth and the README lies.

코드는 진실을 말하고, README는 약간의 거짓말을 하고 있는 그런 프로젝트입니다.

구현은 다음과 같이 되어 있습니다.

  • 서버는 3000번 포트에서 실행된다
  • /에 브라우저용 프론트엔드(Frontend)가 있다
  • GET /tasks?status=todo와 같이 상태(Status)로 필터링할 수 있다
  • 태스크 완료 API는 PATCH /tasks/:id/complete이다
  • 태스크에는 status, priority, dueDate가 있다
  • POST /tasks는 201 Created를 반환한다

반면, README나 docs/api.md에는 오래된 정보가 남아 있습니다.

  • 서버는 8080번 포트에서 실행된다고 적혀 있다
  • 프론트엔드는 없다고 적혀 있다
  • 쿼리 파라미터(Query parameter)는 미지원이라고 적혀 있다
  • 태스크 완료 API는 PATCH /tasks/:id/done이라고 적혀 있다
  • 태스크에는 done 필드가 있다고 적혀 있다
  • POST /tasks는 200 OK를 반환한다고 적혀 있다

이 정도라면 문서 유지보수 Agent의 실험대로 딱 좋을 것 같습니다.

처음에는 Google AI Studio에서 만든 무료 티어 프로젝트의 API Key로 실행했습니다.

export GEMINI_API_KEY="YOUR_API_KEY"

실행합니다.

uv run python doc_maintenance_agent.py ~/repos/antigravity-doc-maintenance-sample

하지만 도중에 멈췄습니다.

google.antigravity.types.AntigravityExecutionError: model unreachable: Error 429, Message: You exceeded your current quota, please check your plan and billing details.
...
Quota exceeded for metric: generativelanguage.googleapis.com/generate_content_free_tier_requests, limit: 5, model: gemini-3.5-flash
...

무료 티어의 요청 한도(Quota)에 걸린 것 같습니다.

doc_maintenance_agent.py는 단발성 채팅이 아닙니다.

대상 디렉터리를 보고, 파일을 읽고, 내용을 판단하여, 필요한 수정을 수행합니다.

그렇기 때문에 최소 샘플보다 API 호출이 더 많아지는 것 같습니다.

여기서 한 번, 무료 티어의 API Key로 실행하는 것은 포기했습니다.

그래서 Tier 1 유료 설정이 되어 있는 프로젝트에 API Key를 추가했습니다.

API Key 추가는 https://aistudio.google.com/api-keys 에서 진행했습니다.

그 API Key를 환경 변수(Environment Variable)에 다시 설정합니다.

export GEMINI_API_KEY="YOUR_TIER1_PROJECT_API_KEY"

다시 마음을 가다듬고 실행합니다.

uv run python doc_maintenance_agent.py ~/repos/antigravity-doc-maintenance-sample

실행하면 로그가 흐릅니다.

상당히 많이 흐릅니다.

Streaming agent output:
INFO:root:RAW WS MSG: {"seqNum":"1", "timestampMicros":"1782561295711971", "trajectoryStateUpdate":{"trajectoryId":"6bffec8792c7783dc0635f403fa34b17", "state":"STATE_RUNNING"}}
...생략...
...

마지막에 stderr

라는 글자가 보였습니다.

실패한 것인가 생각했습니다.

하지만, 여기서 중요한 것은 로그가 아닙니다.

결과물입니다.

git diff

를 확인합니다.

cd ~/repos/antigravity-doc-maintenance-sample
git diff

차이점(Diff)을 보니, README가 수정되어 있었습니다.

-Task Tracker API is a small Node.js API for managing tasks.
-
-This project provides an API only. It does not include a browser-based frontend.
...

프론트엔드가 없다는 오래된 설명이 사라졌습니다.

그리고, Cosmo Task Console이라는 구현상의 프론트엔드에 맞춘 설명으로 수정되어 있습니다.

포트 번호도 수정되었습니다.

-The server starts on port `8080`.
+The server starts on port `3000`. You can access the Cosmo Task Console by open http://localhost:3000 in your browser.

8080에서 3000으로 고쳐져 있습니다.

게다가, GET /tasks의 쿼리 파라미터(Query Parameter)도 추가되어 있습니다.

+Supported query parameters:
+- `status`: Filter tasks by status (`todo` or `done`).

완료 API도 수정되었습니다.

-### PATCH /tasks/:id/done
+### PATCH /tasks/:id/complete

태스크의 필드도 구현에 맞춰 고쳐져 있습니다.

-- id
-- title
-- done
...

이것은 확실히 작동하고 있습니다.

docs/api.md도 수정되어 있었습니다.

Base URL은 8080에서 3000으로.

-http://localhost:8080
+http://localhost:3000

프론트엔드가 없다는 설명도 수정되어 있습니다.

-This project does not provide a frontend page.
+The application serves a browser-based static interface (Cosmo Task Console) at the following paths:
+- `GET /`: Serves the primary HTML page (`index.html`).
...

나아가, 구현에 존재하는 /health도 추가되어 있습니다.

+## GET /health
+
+애플리케이션의 상태(health status)를 반환합니다.
...
```json
+{
+ "ok": true
+}

GET /tasks의 쿼리 파라미터 (query parameter)도 수정되었습니다.

-Query parameters are not supported.
+### Query Parameters
+
...

POST /tasks의 응답 상태 (response status)도 200 OK에서 201 Created로 수정되었습니다.

-Response status: `200 OK`
+Response status: `201 Created`

완료 API도 구현에 맞춰 PATCH /tasks/:id/complete로 수정되었습니다.

-## PATCH /tasks/:id/done
+## PATCH /tasks/:id/complete

상당히 구현 내용을 읽고 있습니다.

docs/maintenance-prompt.md에도 작은 차이(diff)가 있었습니다.

-Use this prompt when running the official Antigravity SDK example.
+Use this prompt when running the official Google Antigravity SDK example.

이 부분은 큰 변경은 아닙니다.

다만, 대상 디렉토리 내의 Markdown을 보고 필요하다고 판단한 것을 업데이트하고 있다는 점은 알 수 있습니다.

로그의 timestampMicros를 보면, 시작과 종료는 다음과 같았습니다.

1782561375366886 - 1782561295711971 = 79654915

단위는 마이크로초 (microseconds)이므로,

79654915 마이크로초 = 약 79.7초

1분 조금 넘게 기다리자, Markdown이 구현에 맞춰 업데이트되었습니다.

솔직히, 이것은 상당히 흥미롭습니다.

hello_world.py는 단순한 인사를 하는 것처럼 보였습니다.

quick_start.py는 현재 디렉토리의 파일 목록을 반환해 주었습니다.

그리고 이번의 doc_maintenance_agent.py는 구현을 읽고 오래된 Markdown을 고쳤습니다.

이것은 단순한 파일 목록이 아닙니다.

구현과 문서 사이의 차이점을 찾아내어 Markdown을 업데이트하고 있습니다.

"나만의 Antigravity를 만드는 부품"이라는 감각이 상당히 강해졌습니다.

Antigravity SDK의 공식 예제(example)인 doc_maintenance_agent.py를 사용하여, 소스 코드와 어긋난 README를 고쳐 보았습니다.

결과적으로 README와 docs/api.md는 구현 내용대로 업데이트되었습니다.

수정된 내용은 예를 들어 다음과 같습니다.

  • 포트 번호가 8080에서 3000으로 수정됨
  • 프론트엔드 없음이라는 오래된 설명이 삭제됨
  • GET /tasks의 status 쿼리 파라미터가 추가됨
  • POST /tasks의 응답이 201 Created로 수정됨
  • 완료 API가 PATCH /tasks/:id/done에서 PATCH /tasks/:id/complete로 수정됨
  • 태스크(task)의 필드가 done에서 status, priority, dueDate로 수정됨

무료 티어의 API Key로는 429 에러가 발생하며 멈췄습니다.

반면, Tier 1 프로젝트의 API Key로 전환하니 끝까지 실행할 수 있었습니다.

Antigravity SDK는 단순한 채팅 API가 아닙니다.

로컬 환경과 연결된 에이전트 (Agent)를 자신의 Python 프로그램에서 다루기 위한 SDK입니다.

그렇게 생각하면 상당히 꿈이 큽니다.

의욕만 있다면 자신만의 작은 Antigravity 스타일의 도구도 만들 수 있을 것 같습니다.

글로 쓰면 담담하게 적고 있는 것처럼 보일지 모르겠지만, 이것을 쓰고 있는 저는 지금 매우 흥분되어 있습니다!

Antigravity ―― 반중력(Antigravity)이라서, 조금 들떴네요.

AI 자동 생성 콘텐츠

본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0