REST API (Managed Agents) - 오늘코드 Antigravity 튜토리얼

1. 빠른 시작 — curl 한 줄로 Hello World #

Step 1 — API 키 발급

Google AI Studio에서 무료 Gemini API 키를 발급받습니다. 발급한 키는 환경변수 GEMINI_API_KEY에 저장합니다.

      환경변수 설정 (macOS/Linux)
      export GEMINI_API_KEY="ya29.your-key-here"
    

Step 2 — 첫 호출

      curl 명령
      curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "Hello World를 Python으로 출력하는 코드를 작성하고 실행해 결과를 알려줘",
    "tools": ["code_execution"]
  }'
    

Step 3 — 응답 확인

약 5-10초 후 다음 같은 JSON 응답이 옵니다:

      응답 예시 (간소화)
      {
  "interactionId": "int_abc123",
  "status": "completed",
  "output": "코드를 작성하고 실행했습니다.\n\n```python\nprint('Hello World')\n```\n\n실행 결과: Hello World",
  "executionTrace": [
    {"step": 1, "type": "reasoning", "content": "..."},
    {"step": 2, "type": "tool_call", "name": "code_execution", "args": "..."},
    {"step": 3, "type": "tool_result", "output": "Hello World\n"}
  ],
  "usage": {"input_tokens": 42, "output_tokens": 87}
}
    

방금 무슨 일이 일어났나?

요청이 generativelanguage.googleapis.com의 Antigravity 하네스에 전달됨
Google이 ephemeral Linux 샌드박스를 띄움
에이전트가 Python 코드를 작성하고 code_execution 도구로 실행
실행 결과를 받아 자연어 응답으로 정리
샌드박스 자동 폐기 (다음 호출은 완전히 새 환경)

2. REST API란? — Managed Agents 개념 #

Antigravity REST API는 정확히 말해 Gemini API의 Managed Agents 기능입니다. 두 가지 엔드포인트로 구성됩니다.

두 가지 API의 역할 분담

Managed Agents API

에이전트의 설정·생애주기 관리. 에이전트 생성, 스킬·MCP·정책 등록, 버전 관리, 삭제.

예: POST /v1beta/agents, GET /v1beta/agents/{id}

Interactions API

실제 에이전트 호출. 자연어 지시 전달, 결과 수신, 스트리밍 응답 처리.

예: POST /v1beta/interactions, GET /v1beta/interactions/{id}

Antigravity REST API vs SDK vs CLI

Antigravity 접근 방법 비교
접근 방법	언어	제어 수준	적합한 사용 사례
REST API	모든 언어 (HTTP만 가능하면)	가장 원시적	Node.js·Go·Rust·Ruby 백엔드, 서버리스, 외부 시스템 통합
SDK (Python)	Python 전용	편리, 타입 안전	Python 백엔드, 데이터 파이프라인, AI/ML 워크플로우
CLI (agy)	셸 (모든 언어에서 spawn)	대화형, 빠른 시작	로컬 개발, CI 셸 스크립트, 빠른 prototype

REST API를 선택해야 할 때

✅ Python을 사용할 수 없는 환경 — Node.js/Go/Rust/Ruby/Elixir/PHP 등 다른 언어 백엔드
✅ SDK 설치가 불가능한 환경 — 일부 서버리스 플랫폼 (Cloudflare Workers, Vercel Edge 등)
✅ 최대한 가벼운 의존성이 필요 — Lambda 콜드 스타트 최소화
✅ 다른 시스템과 통합 — Zapier, n8n, Workato 같은 iPaaS
❌ Python 백엔드 — SDK가 더 편리하고 타입 안전
❌ 로컬 개발 시작 — CLI(agy)가 더 빠르게 시작 가능

3. 인증 & 환경 준비 #

3.1 API 키 발급

aistudio.google.com 접속, Google 계정 로그인
좌측 메뉴 "Get API Key" 클릭
"Create API Key in new project" 또는 기존 프로젝트 선택
발급된 키 안전하게 저장 (한 번만 표시됨)
Managed Agents 기능 활성화: AI Studio → Settings → Experimental Features → "Managed Agents" 토글

⚠️ API 키 보안:

코드에 하드코딩 절대 금지. 환경변수 또는 시크릿 관리 도구 사용
GitHub에 커밋되지 않도록 .env·.gitignore 확인
프로덕션에서는 Google Cloud Secret Manager 또는 동등한 도구 사용
키 유출 시 즉시 AI Studio에서 폐기 후 재발급

3.2 필수 HTTP 헤더 3종

필수 HTTP 헤더
헤더	값	설명
`x-goog-api-key`	`$GEMINI_API_KEY`	API 키 인증 (필수)
`Api-Revision`	`2026-05-20`	API 버전 핀 — 향후 호환성 깨짐 방지 (강력 권장)
`Content-Type`	`application/json`	요청 본문 형식 (POST 시 필수)

Api-Revision 헤더가 중요한 이유: 명시하지 않으면 항상 최신 API 사양으로 동작합니다. Google이 호환성을 깨는 변경을 도입하면 코드가 갑자기 망가질 수 있습니다. 프로덕션에서는 항상 명시적 revision pin을 사용하세요. 새 revision으로 마이그레이션할 때는 dev 환경에서 충분히 테스트.

3.3 엔드포인트 URL

      기본 URL
      # Managed Agents API (설정)
https://generativelanguage.googleapis.com/v1beta/agents

# Interactions API (호출)
https://generativelanguage.googleapis.com/v1beta/interactions

# 스트리밍 응답 (Server-Sent Events)
https://generativelanguage.googleapis.com/v1beta/interactions:stream
    

4. Managed Agents API — 에이전트 설정 #

Interactions API를 호출할 때마다 매번 instruction·tools·skills를 보내는 대신, 사전에 에이전트 설정을 등록해두고 ID로 호출할 수 있습니다.

4.1 에이전트 생성 — POST /v1beta/agents

      에이전트 등록
      curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/agents" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "data-analyst",
    "description": "CSV·DataFrame 분석 전문 에이전트",
    "systemInstruction": "당신은 데이터 분석가입니다. pandas·seaborn을 활용해 EDA·시각화·요약을 수행합니다. 모든 시각화는 한글 폰트(koreanize_matplotlib)로 렌더링합니다.",
    "model": "gemini-3.5-flash",
    "tools": ["code_execution", "file_read", "file_write"],
    "skills": ["data-analysis", "pandas-helpers"],
    "policy": {
      "maxTurnDuration": 300,
      "maxOutputTokens": 4096
    }
  }'
    

4.2 에이전트 조회 · 수정 · 삭제

      CRUD 명령
      # 전체 목록
curl -H "x-goog-api-key: $GEMINI_API_KEY" \
  "https://generativelanguage.googleapis.com/v1beta/agents"

# 단건 조회
curl -H "x-goog-api-key: $GEMINI_API_KEY" \
  "https://generativelanguage.googleapis.com/v1beta/agents/agt_abc123"

# 수정 (PATCH)
curl -X PATCH \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  "https://generativelanguage.googleapis.com/v1beta/agents/agt_abc123" \
  -d '{"systemInstruction": "새 지시..."}'

# 삭제
curl -X DELETE -H "x-goog-api-key: $GEMINI_API_KEY" \
  "https://generativelanguage.googleapis.com/v1beta/agents/agt_abc123"
    

5. Interactions API — 에이전트 호출 #

5.1 일회성 호출 (Inline 설정)

에이전트 사전 등록 없이 즉석에서 설정·호출:

      curl
      curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "data/train.csv를 분석하고 결측치 비율을 컬럼별로 정리해줘",
    "model": "gemini-3.5-flash",
    "tools": ["code_execution", "file_read"],
    "files": [{"name": "train.csv", "url": "gs://my-bucket/train.csv"}]
  }'
    

5.2 등록된 에이전트 호출 (agentId 사용)

      사전 등록 에이전트 호출
      curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agt_abc123",
    "instruction": "train.csv의 결측치 처리 방안 제안"
  }'
    

5.3 요청 본문 주요 필드

Interactions API 요청 필드
필드	타입	설명
`instruction`	string	에이전트에게 줄 자연어 지시 (필수)
`agentId`	string	사전 등록한 에이전트 ID (있으면 model/tools 생략 가능)
`model`	string	모델 선택 (`gemini-3.5-flash`, `gemini-3.1-pro` 등)
`tools`	string[]	활성화할 도구 (`code_execution`, `web_search`, `file_read`, `file_write`, `browser`)
`skills`	string[]	활성화할 스킬 (사전 등록된 스킬 이름)
`files`	object[]	샌드박스에 마운트할 파일 (GCS URL 또는 인라인)
`mcp`	object[]	활성화할 MCP 서버 (이름·인증)
`policy.maxTurnDuration`	integer	최대 실행 시간 (초)
`policy.maxOutputTokens`	integer	최대 출력 토큰 수
`stream`	boolean	스트리밍 응답 사용 여부

5.4 응답 구조

      완료된 인터랙션 응답
      {
  "interactionId": "int_abc123",
  "status": "completed",        // completed | running | failed | cancelled
  "output": "...",              // 최종 자연어 응답
  "executionTrace": [           // 단계별 추론·도구 호출 기록
    {"step": 1, "type": "reasoning", "content": "..."},
    {"step": 2, "type": "tool_call", "name": "code_execution", "args": {...}},
    {"step": 3, "type": "tool_result", "output": "..."}
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 87,
    "total_tokens": 129,
    "duration_ms": 5234
  },
  "files": [                    // 에이전트가 생성한 파일
    {"name": "analysis.html", "url": "https://..."}
  ]
}
    

6. 스트리밍 응답 — Server-Sent Events #

긴 작업의 경우 결과를 한꺼번에 기다리지 말고 실시간으로 받습니다. :stream 엔드포인트 또는 "stream": true 옵션 사용.

6.1 curl로 스트리밍

      curl 스트리밍
      curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions:stream" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "instruction": "Python으로 1만 줄짜리 데이터를 분석하는 코드를 작성해 실행",
    "tools": ["code_execution"]
  }' \
  --no-buffer
    

6.2 응답 이벤트 형식 (SSE)

      스트림 출력 예시
      event: reasoning_started
data: {"step": 1, "content": "데이터 분석 계획 수립 중..."}

event: tool_call
data: {"step": 2, "name": "code_execution", "args": {"code": "import pandas..."}}

event: tool_result
data: {"step": 2, "output": "10000 rows × 12 columns", "duration_ms": 1245}

event: partial_output
data: {"text": "분석 결과:\n\n- 행 수: 10,000"}

event: partial_output
data: {"text": "\n- 결측치 컬럼: 3개"}

event: completed
data: {"interactionId": "int_abc", "status": "completed", "usage": {...}}
    

6.3 Node.js (fetch + EventSource 패턴)

      Node.js 18+ 예제
      // stream.mjs
const response = await fetch(
  "https://generativelanguage.googleapis.com/v1beta/interactions:stream",
  {
    method: "POST",
    headers: {
      "x-goog-api-key": process.env.GEMINI_API_KEY,
      "Api-Revision": "2026-05-20",
      "Content-Type": "application/json",
      "Accept": "text/event-stream",
    },
    body: JSON.stringify({
      instruction: "Hello from Node.js",
      tools: ["code_execution"],
    }),
  }
);

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const chunk = decoder.decode(value);
  console.log(chunk);  // SSE 형식 그대로 출력
}
    

7. 활용 패턴 #

패턴 1: GitHub Actions에서 PR 자동 리뷰

      .github/workflows/pr-review.yml
      name: AI PR Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Get diff
        run: git diff origin/main > /tmp/diff.txt
      - name: Call Antigravity REST API
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        run: |
          DIFF=$(cat /tmp/diff.txt)
          curl -X POST \
            "https://generativelanguage.googleapis.com/v1beta/interactions" \
            -H "x-goog-api-key: $GEMINI_API_KEY" \
            -H "Api-Revision: 2026-05-20" \
            -H "Content-Type: application/json" \
            -d "{
              \"instruction\": \"다음 PR diff를 리뷰: $DIFF\",
              \"agentId\": \"agt_pr_reviewer\"
            }" | jq -r '.output' > /tmp/review.md
          gh pr comment ${{ github.event.pull_request.number }} \
            --body-file /tmp/review.md
    

패턴 2: Slack 봇으로 Antigravity 호출

      Node.js Slack 봇
      const { App } = require("@slack/bolt");

const app = new App({
  token: process.env.SLACK_BOT_TOKEN,
  signingSecret: process.env.SLACK_SIGNING_SECRET,
});

app.message(/^@ag (.+)/, async ({ message, say, context }) => {
  const userPrompt = context.matches[1];
  const response = await fetch(
    "https://generativelanguage.googleapis.com/v1beta/interactions",
    {
      method: "POST",
      headers: {
        "x-goog-api-key": process.env.GEMINI_API_KEY,
        "Api-Revision": "2026-05-20",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        instruction: userPrompt,
        tools: ["web_search", "code_execution"],
      }),
    }
  );
  const data = await response.json();
  await say(data.output);
});

app.start(3000);
    

패턴 3: Cloudflare Workers — Antigravity 프록시

      worker.js
      export default {
  async fetch(request, env) {
    const { prompt } = await request.json();

    const response = await fetch(
      "https://generativelanguage.googleapis.com/v1beta/interactions",
      {
        method: "POST",
        headers: {
          "x-goog-api-key": env.GEMINI_API_KEY,
          "Api-Revision": "2026-05-20",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          instruction: prompt,
          model: "gemini-3.5-flash",
        }),
      }
    );

    return new Response(response.body, {
      headers: { "Content-Type": "application/json" },
    });
  },
};
    

패턴 4: Python (SDK 대신 requests로)

      Python requests
      import os
import requests

def call_antigravity(instruction: str, **kwargs) -> dict:
    response = requests.post(
        "https://generativelanguage.googleapis.com/v1beta/interactions",
        headers={
            "x-goog-api-key": os.environ["GEMINI_API_KEY"],
            "Api-Revision": "2026-05-20",
            "Content-Type": "application/json",
        },
        json={"instruction": instruction, **kwargs},
        timeout=300,
    )
    response.raise_for_status()
    return response.json()

result = call_antigravity(
    "data.csv의 상관관계 매트릭스를 그려줘",
    tools=["code_execution", "file_read"],
    model="gemini-3.5-flash",
)
print(result["output"])
    

8. 트러블슈팅 #

REST API 트러블슈팅
HTTP 상태	증상	원인 / 해결
`401 Unauthorized`	API 키 거부	`x-goog-api-key` 헤더 누락 또는 잘못된 키 / AI Studio에서 키 재발급
`403 Forbidden`	Managed Agents 비활성화	AI Studio → Settings → Experimental Features에서 Managed Agents 토글 ON
`404 Not Found`	잘못된 엔드포인트 또는 agentId 없음	URL 오타 확인 / agentId 존재 확인 (`GET /v1beta/agents`)
`429 Too Many Requests`	레이트 리밋 초과	Retry-After 헤더 값만큼 대기 후 재시도. 지수 백오프 권장
`500 Internal Server Error`	Google 서버 일시 오류	5초 대기 후 재시도. 반복 발생 시 Google Cloud Status 확인
`503 Service Unavailable`	샌드박스 자원 부족	지수 백오프 재시도. 큰 작업은 작은 단위로 분할
`504 Gateway Timeout`	최대 실행 시간 초과	`policy.maxTurnDuration` 증가 또는 작업 분할 / 스트리밍 API 사용 권장
`일부 도구 무시됨`	tools 배열에 미지원 이름	지원 도구 목록 확인: `code_execution`, `web_search`, `file_read`, `file_write`, `browser`
`매번 새 결과`	샌드박스가 ephemeral	매 호출이 독립 환경. 상태 유지 필요 시 외부 스토리지 (GCS, DB) 사용

API 응답 시간 최적화

적절한 모델 선택 — 간단한 작업은 gemini-3.5-flash (빠름·저렴), 복잡한 추론은 gemini-3.1-pro
스트리밍 사용 — 사용자 체감 응답 시간 단축
policy.maxOutputTokens 제한 — 불필요한 긴 응답 차단
agentId 재사용 — 매 호출마다 model·tools·skills를 보내지 않고 사전 등록한 ID만 전달
병렬 호출 — 독립적인 작업은 동시 호출 (단, 레이트 리밋 주의)

비용 모니터링

각 호출의 usage 필드로 토큰 사용량을 추적합니다.

      간단한 비용 로깅
      const result = await response.json();
console.log({
  interactionId: result.interactionId,
  tokens: result.usage.total_tokens,
  duration: result.usage.duration_ms,
  cost_estimate_usd: result.usage.total_tokens * 0.000001,  // 모델별 단가 확인
});
    

9. 관련 자료 #

Antigravity SDK (Python) — Python에서는 SDK가 더 편함
Antigravity CLI (agy) — 셸에서 직접 호출
MCP — 외부 도구·서비스 연결 표준
Skills — 사전 등록한 스킬을 REST API에서도 호출 가능
Harness Engineering — 정책·보안 설계 원칙
공식 Antigravity Agent API 문서
Google Cloud Managed Agents 문서 (엔터프라이즈)
Google AI Studio — API 키 발급

REST API — Managed Agents Gemini API · Antigravity 2.0