Gemini Managed Agents API 완전 가이드 — 단일 API 호출로 격리된 Linux 환경에서 에이전트 실행하기

에이전트를 프로덕션에 배포하려면 샌드박스 인프라 구성, 격리 환경 관리, 상태 지속성 구현이 필요합니다. 수백 줄의 인프라 코드입니다. Google이 오늘(5월 20일) 이걸 API 한 줄로 바꿨습니다. Gemini Managed Agents는 격리된 Linux 환경에서 에이전트를 돌리는 인프라 전체를 Google이 관리합니다.

[핵심 요약 — 오늘(2026.05.20) 발표 정확한 정보]
→ 오늘 Preview 출시 — Gemini API에서 지금 바로 사용 가능
→ 핵심: 단일 API 호출 → 격리된 Linux 샌드박스에서 에이전트 자율 실행
→ 기반: Antigravity 에이전트 하네스 + Gemini 3.5 Flash
→ 에이전트 ID: antigravity-preview-05-2026
→ 3가지 내장 에이전트: Antigravity(범용) / Deep Research / Deep Research Max
→ SDK: google-genai >= 2.0.0 필수 (구버전 google-generativeai는 deprecated)
→ API: Interactions API (client.interactions.create())
→ 샌드박스: 파일시스템·bash·웹 접근, TTL 7일, 멀티턴 세션 간 상태 유지
→ 커스텀 에이전트: AGENTS.md + SKILL.md 마크다운으로 정의
→ 엔터프라이즈: Gemini Enterprise Agent Platform (Private Preview)
→ 주의: 5월 2026 Breaking Changes — steps 배열 사용, response_format 변경

---

기존 에이전트 개발 vs Managed Agents

[기존 에이전트 프로덕션 배포의 고통]

직접 구축 시 필요한 것들:
→ Docker 컨테이너 격리 설정
→ 파일시스템 마운트·권한 관리
→ 멀티턴 세션 상태 저장 (Redis/DB)
→ 네트워크 격리 + 화이트리스트
→ 코드 실행 샌드박스 (gVisor 등)
→ 타임아웃·TTL 관리
→ 스케일링 인프라

코드 규모: 수백~수천 줄 인프라 코드

[Managed Agents — 단 3줄]

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="GitHub 트렌딩 레포 분석해서 PDF 리포트 만들어줘",
    environment="remote",
)
print(interaction.output_text)

→ 위 코드가 실행되면:
   1. Google 서버에 격리된 Linux 환경 자동 생성
   2. 에이전트가 웹 접근 + 코드 실행 + 파일 생성 자율 수행
   3. PDF 생성 후 결과 반환
   4. 샌드박스 상태 7일간 유지 (재접속 가능)

---

실전 1 — 설치 및 첫 호출

SDK 설치

# 중요: 신규 SDK 설치 (구버전과 다름)
pip install -U google-genai

# 구버전 google-generativeai는 deprecated — 사용 금지
# pip install google-generativeai  ← 이거 아님

# API 키 설정
export GEMINI_API_KEY="your-api-key"
# https://aistudio.google.com/apikey 에서 발급

# Node.js
npm install @google/genai
# @google/generative-ai ← 구버전 아님

# 첫 번째 Managed Agent 호출
from google import genai

client = genai.Client()

# Antigravity 에이전트 — 범용, 웹 + 코드 실행 + 파일 관리
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Hacker News 상위 10개 스토리 읽고 요약해서 PDF로 저장해줘",
    environment="remote",  # 격리된 원격 Linux 환경
)

print(interaction.output_text)
# → 에이전트가 Hacker News 접속 → 파싱 → 요약 → PDF 생성 → 결과 반환

// TypeScript
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create(
  {
    agent: "antigravity-preview-05-2026",
    input: "Hacker News 상위 10개 스토리 읽고 요약해서 PDF로 저장해줘",
    environment: "remote",
  },
  { timeout: 300000 }  // 5분 타임아웃 (장기 실행 태스크)
);

console.log(interaction.output_text);

# curl로 직접 호출
curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "antigravity-preview-05-2026",
    "input": "현재 디렉토리의 Python 파일 분석해서 버그 리포트 작성해줘",
    "environment": "remote"
  }'

---

실전 2 — 3가지 내장 에이전트

# ── Antigravity Agent (범용) ──────────────────────────
# 코드 실행 + 파일 관리 + 웹 접근 + Google Search
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Python으로 Fibonacci 수열 생성기 만들고 테스트해줘",
    environment="remote",
)

# ── Deep Research (빠른 리서치) ────────────────────────
# 복잡한 연구 태스크 — 빠른 버전
interaction = client.interactions.create(
    agent="deep-research-preview-04-2026",
    input="2026년 AI 에이전트 시장 현황 분석",
    environment="remote",
)

# ── Deep Research Max (최대 철저함) ───────────────────
# 복잡한 연구 태스크 — 최고 품질, 더 느림
interaction = client.interactions.create(
    agent="deep-research-max-preview-04-2026",
    input="양자 컴퓨팅이 현재 암호화 시스템에 미치는 영향 심층 분석",
    environment="remote",
)

[에이전트별 선택 기준]

antigravity-preview-05-2026:
→ 코드 실행 필요한 태스크
→ 파일 생성·편집
→ 웹 스크래핑 + 자동화
→ 멀티스텝 실용 태스크 (리포트 생성, 데이터 처리)

deep-research-preview-04-2026:
→ 빠른 리서치 요약 필요
→ 여러 소스에서 정보 종합
→ 시간 중요한 경우

deep-research-max-preview-04-2026:
→ 심층 분석, 학술적 리서치
→ 최고 품질 필요 (속도 희생 가능)
→ 복잡한 다차원 분석

---

실전 3 — 멀티턴 세션 (상태 유지)

# 멀티턴 세션 — 파일과 상태가 7일간 유지
from google import genai

client = genai.Client()

# ── 첫 번째 인터랙션 ──────────────────────────────────
interaction1 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="""
    다음 Python 코드를 분석해줘:
    
    def calculate_average(numbers):
        return sum(numbers) / len(numbers)
    
    분석 결과를 analysis.txt 파일에 저장해줘.
    """,
    environment="remote",
)

# 환경 ID 저장 — 다음 세션에서 재사용
env_id = interaction1.environment_id
print(f"환경 ID: {env_id}")
print(interaction1.output_text)

# ── 두 번째 인터랙션 — 같은 환경 재사용 ──────────────
# analysis.txt 파일이 그대로 존재
interaction2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment=env_id,  # 이전 환경 재사용
    input="""
    아까 저장한 analysis.txt를 읽어서
    코드 개선 버전을 개선된_코드.py로 저장해줘.
    엣지케이스 (빈 리스트, None 입력) 처리 추가.
    """,
)
print(interaction2.output_text)

# ── 세 번째 인터랙션 — 계속 이어서 ───────────────────
interaction3 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment=env_id,
    input="""
    개선된_코드.py에 대한 단위 테스트 파일 test_코드.py 작성하고
    실행해서 결과 알려줘.
    """,
)
print(interaction3.output_text)

[멀티턴 세션 동작 방식]

새 environment="remote":
→ 새 격리 Linux 환경 생성
→ 빈 파일시스템으로 시작

environment=env_id (기존 환경):
→ 이전 세션의 모든 파일 그대로 존재
→ 코드·데이터·설치된 패키지 유지
→ TTL: 7일 (인터랙션마다 리셋)

멀티턴이 유용한 경우:
→ 긴 프로젝트를 여러 세션에 나눠서 진행
→ 이전 분석 결과 기반으로 다음 단계
→ 반복적 코드 개선 워크플로우

---

실전 4 — 커스텀 에이전트 정의

마크다운 파일로 자신만의 에이전트를 정의합니다.

# 커스텀 에이전트 생성
agent = client.agents.create(
    display_name="코드 리뷰어",
    description="Python 코드 보안·성능 리뷰 전문 에이전트",
    # AGENTS.md 내용 직접 지정
    system_instruction="""
    당신은 시니어 Python 개발자입니다.
    코드를 리뷰할 때 다음 항목을 반드시 확인합니다:
    
    1. 보안 취약점 (SQL 인젝션, 하드코딩 시크릿, 입력 검증 누락)
    2. 성능 문제 (불필요한 루프, N+1 쿼리, 메모리 누수)
    3. 에러 핸들링 누락
    4. 타입 힌트 누락
    5. 테스트 커버리지 부족
    
    각 이슈를 심각도(Critical/High/Medium/Low)로 분류하고
    구체적인 수정 코드를 제시합니다.
    결과는 항상 Markdown 형식으로 작성합니다.
    """,
    # 허용할 도구 지정
    tools=["code_execution", "file_management"],
    # 웹 접근 (기본: 비활성화)
    network_access=False,
)

agent_id = agent.id
print(f"에이전트 ID: {agent_id}")

# 커스텀 에이전트 사용
interaction = client.interactions.create(
    agent=agent_id,
    input="""
    다음 코드를 리뷰해줘:
    
    def get_user(user_id):
        query = f"SELECT * FROM users WHERE id = {user_id}"
        return db.execute(query)
    """,
    environment="remote",
)
print(interaction.output_text)

# 에이전트 관리
# 목록 조회
agents = client.agents.list()
for agent in agents:
    print(f"{agent.display_name}: {agent.id}")

# 특정 에이전트 조회
agent = client.agents.get(agent_id)

# 에이전트 삭제
client.agents.delete(agent_id)

<!-- AGENTS.md — 파일로 버전 관리 가능 -->
# 데이터 분석 에이전트

## 역할
pandas, numpy, matplotlib를 사용한 데이터 분석 전문가

## 분석 프로세스
1. 데이터 로드 및 기본 통계 확인
2. 결측값·이상치 탐지
3. 시각화 (히스토그램, 박스플롯, 상관관계 히트맵)
4. 인사이트 요약 리포트 생성

## 출력 형식
→ analysis_report.md: 텍스트 분석
→ charts/: 시각화 이미지
→ summary.json: 핵심 통계

## 사용 패키지
pandas >= 2.0, numpy, matplotlib, seaborn

## 주의
→ PII 데이터 출력 금지
→ 항상 한국어로 리포트 작성

---

실전 5 — 스트리밍 응답

# 장기 실행 태스크는 스트리밍으로 진행 상황 실시간 확인
import asyncio
from google import genai

async def stream_agent():
    client = genai.Client()

    async for step in await client.interactions.create_streaming(
        agent="antigravity-preview-05-2026",
        input="""
        다음 작업을 순서대로 수행해줘:
        1. 피보나치 수열 1000번째까지 계산
        2. 소수 필터링
        3. CSV 파일로 저장
        4. 통계 분석 (평균, 중앙값, 분포)
        5. 막대 그래프 생성 (PNG)
        """,
        environment="remote",
    ):
        # steps 배열 — 5월 2026 Breaking Change
        # 구버전 outputs 대신 steps 사용
        if hasattr(step, 'type'):
            if step.type == "thinking":
                print(f"🤔 생각 중: {step.content[:100]}...")
            elif step.type == "tool_call":
                print(f"🔧 도구 실행: {step.tool_name}")
            elif step.type == "tool_result":
                print(f"✅ 결과: {step.content[:100]}...")
            elif step.type == "output":
                print(f"\n📄 최종 응답:\n{step.content}")

asyncio.run(stream_agent())

[5월 2026 Breaking Changes — 반드시 확인]

1. steps 배열 (구버전 outputs 대신):
   # 구버전 (작동 안 함):
   interaction.outputs

   # 신버전:
   interaction.steps

2. response_format (구버전 response_mime_type 대신):
   # 구버전:
   response_mime_type="application/json"

   # 신버전:
   response_format={"type": "json_object"}

3. SDK 버전:
   # 필수: google-genai >= 2.0.0
   # 구버전 google-generativeai는 더 이상 지원 안 함

4. 에이전트 이름 형식:
   # {name}-preview-{month}-{year}
   antigravity-preview-05-2026

---

실전 6 — 실전 워크플로우 패턴

# ── 패턴 1: 코드 생성 + 테스트 + 검증 자동화 ─────────
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="""
    FastAPI로 간단한 할일 관리 REST API 만들어줘:
    - GET /todos: 전체 목록
    - POST /todos: 추가
    - DELETE /todos/{id}: 삭제
    
    구현 후:
    1. uvicorn으로 서버 시작
    2. curl로 각 엔드포인트 테스트
    3. 테스트 결과 포함한 README.md 생성
    """,
    environment="remote",
)
print(interaction.output_text)

# ── 패턴 2: 데이터 수집 + 분석 파이프라인 ────────────
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="""
    다음 작업을 자동화해줘:
    1. https://api.github.com/trending 에서 오늘 트렌딩 레포 데이터 수집
    2. 언어별, 스타 수별 분류
    3. pandas로 분석 후 Excel 파일 생성
    4. 인사이트 요약 (어떤 언어가 뜨는지, 어떤 카테고리가 많은지)
    """,
    environment="remote",
)

# ── 패턴 3: 문서 분석 + 요약 + 번역 ──────────────────
# 파일 업로드 후 에이전트에게 처리 위임
file = client.files.upload(path="technical_paper.pdf")

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input=f"""
    이 논문을 분석해줘 (파일 ID: {file.name}):
    1. 핵심 기여점 3가지
    2. 방법론 요약
    3. 한계점
    4. 한국어 요약 (500자 이내)
    5. 개발자에게 실용적인 적용 방법
    """,
    environment="remote",
)

# ── 패턴 4: CI/CD 통합 ────────────────────────────────
# GitHub Actions에서 코드 품질 검사
import os

pr_diff = os.environ.get("PR_DIFF", "")

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input=f"""
    다음 PR diff를 리뷰해줘:
    
    {pr_diff}
    
    다음 항목 확인:
    1. 보안 취약점
    2. 성능 문제
    3. 테스트 누락
    4. 코드 스타일
    
    JSON 형식으로 결과 반환:
    {{
      "approve": true/false,
      "issues": [...],
      "suggestions": [...]
    }}
    """,
    environment="remote",
    response_format={"type": "json_object"},  # 구조화 응답
)

import json
review = json.loads(interaction.output_text)
print(f"승인: {review['approve']}")

---

Managed Agents vs Claude Code vs Antigravity CLI

[언제 무엇을 쓰나]

Gemini Managed Agents API:
→ 내 앱·서비스에 에이전트 기능 임베딩
→ 백엔드 서버에서 에이전트 호출
→ CI/CD 파이프라인 자동화
→ 사용자에게 에이전트 기능 제공하는 SaaS
→ 인프라 없이 에이전트 배포하고 싶을 때

Claude Code:
→ 개인 개발 생산성 도구
→ 터미널에서 직접 코딩 보조
→ 로컬 코드베이스 작업

Antigravity CLI:
→ 터미널에서 Gemini 에이전트 직접 사용
→ 로컬 개발 환경 자동화
→ 스크립트·CI에서 Gemini 에이전트 실행

Antigravity IDE:
→ 시각적 에이전트 오케스트레이션
→ Artifacts 검토·승인
→ 코딩과 에이전트 동시 작업

[비용 관점]
→ Managed Agents API: Gemini API 사용량 기준 과금
→ Gemini 3.5 Flash 기반 → $1.50/M input, $9.00/M output
→ 샌드박스 실행 시간도 추가 과금 가능 (공식 가격 확인 필요)
→ AI Ultra $100/월: Antigravity에서 5배 높은 한도

---

마무리

✅ Managed Agents API 지금 써야 하는 경우
→ 에이전트 기능을 내 앱에 넣고 싶은데 인프라가 없을 때
→ 복잡한 멀티스텝 태스크를 API 하나로 자동화하고 싶을 때
→ 코드 실행 샌드박스가 필요한 AI 기능 구현
→ 멀티턴 세션으로 긴 작업을 여러 번에 나눠서 진행
→ Deep Research 기능을 앱에 임베딩하고 싶을 때

❌ 아직 주의해야 할 것
→ Preview 단계 — 프로덕션 민감 워크플로우 주의
→ Breaking Changes 계속 있음 (5월 2026이 최신) — 버전 고정 권장
→ 중요한 작업 결과는 배포 전 반드시 인간 검토
→ 기본 네트워크 비활성화 — 외부 접근 필요 시 명시적 설정
→ 가격 정책: 아직 Preview, GA 시 변경 가능
→ 엔터프라이즈 기능 (Agent Platform): Private Preview만

---

관련 글

• Google I/O 2026 핵심 정리 2편 — Antigravity 2.0·WebMCP·Android XR
• Gemini 3.5 Flash 완전 가이드 — 오늘 출시된 구글 최신 모델