Gemini API 한 번 호출로 격리 Linux 샌드박스: Managed Agents가 의미하는 것

한 줄 요약

Google I/O 2026 Developer Keynote에서 공개된 Managed Agents in the Gemini API는, 개발자가 client.interactions.create() 한 번을 호출하면 격리된 임시 Linux 환경이 자동으로 떠서 그 안에서 모델이 추론하고, 도구를 부르고, 코드를 실행하고, 파일을 다룰 수 있게 해주는 기능이다. 컨테이너도, VM도, 오케스트레이션 코드도 직접 다룰 필요가 없다. 출처: Google 공식 블로그 — Introducing Managed Agents in the Gemini API, Gemini API Docs — Antigravity Agent, Gemini API Docs — Building Managed Agents.

데스크탑 Gemini Agent와는 다른 영역이다

먼저 헷갈리기 쉬운 부분부터 정리한다. 같은 I/O 윈도우에서 공개된 데스크탑 Gemini Agent(=완성형 클라이언트 앱으로 사용자의 PC를 조작하는 제품)와 이번 Managed Agents는 다른 레이어의 발표다.

• 데스크탑 Gemini Agent는 최종 사용자가 실행하는 OS 레벨 에이전트 클라이언트다.
• Managed Agents in the Gemini API는 개발자가 자신의 제품 안에 같은 종류의 “행동하는 AI”를 박아 넣기 위해 호출하는 백엔드 API다. 실행 환경은 사용자 PC가 아니라 Google이 운영하는 클라우드 샌드박스다.

같은 키워드로 묶이지만 책임 경계가 정반대다. 본 글은 후자, 즉 개발자 API에 집중한다.

어떻게 동작하나 — 단일 호출, 임시 Linux

Google의 공식 발표는 한 줄 요약이 정확하다.

“With a single call, you can now spin up an agent that reasons, uses tools and executes code in an isolated, ephemeral Linux environment.”
— Google blog, 2026-05-19

기존에 OpenAI Assistants나 Anthropic Computer Use 같은 “행동하는 AI”를 백엔드에서 운영하려면, 개발자는 사실상 두 가지 시스템을 만들어야 했다. 하나는 모델 호출 그 자체, 다른 하나는 모델이 실제로 명령을 실행할 격리 환경 — Docker 컨테이너, 파일시스템 마운트, 네트워크 정책, 세션 관리, TTL, 보안 정리. 이 두 번째 절반이 진짜로 어렵고, 보안 사고의 대부분이 여기서 발생한다.

Managed Agents는 이 두 번째 절반을 Google이 떠안는다. 단일 interactions.create() 호출 안에 다음이 묶여 있다.

• Antigravity 에이전트 하네스 (추론·도구 호출·다단계 계획)
• 원격 Linux 샌드박스 (bash terminal, 파일시스템, 네트워크)
• 기본 도구 세트: code_execution, google_search, url_context
• 멀티턴 대화 시 같은 샌드박스를 이어 쓰는 세션 지속성

출처: Gemini API Docs.

검색 결과에 따르면 샌드박스는 기본 TTL이 7일로 운영되어, 다단계 인터랙션에서 파일, 에이전트 로직, 실행 상태가 유지된다. (검색 결과 인용 — Gemini Enterprise Agent Platform docs 기준)

AGENTS.md / SKILL.md — 업계 표준화 신호

이번 발표에서 개발자가 가장 의미 있게 봐야 할 디테일은 모델 사양이 아니라 “설정 파일을 어떻게 다루느냐”다. Google이 채택한 방식은 다음과 같다.

“Define everything in markdown files like AGENTS.md and SKILL.md and register them as a managed agent.”
— Google blog

공식 문서는 디렉터리 구조도 못박는다.

my-agent/
├── AGENTS.md          # 에이전트 작동 방식 / 페르소나 / 가이드라인
├── skills/            # 도메인별 스킬들
│   └── slide-maker/
│       └── SKILL.md
└── workspace/         # 초기 데이터 파일

샌드박스가 부팅되면 .agents/AGENTS.md가 자동으로 system instruction으로 로드된다. SKILL.md는 YAML frontmatter (name / description) 헤더와 본문 마크다운으로 구성된다. 출처: Gemini API Docs — Building Managed Agents.

이 컨벤션은 우연이 아니다. Anthropic Claude의 Skills 기능과 Claude Code의 AGENTS.md 형식이 이미 같은 명칭, 같은 파일 구조를 쓴다. 즉 빅테크 두 곳이 이제 “에이전트의 정체성과 능력을 마크다운으로 선언한다”는 동일 컨벤션을 자기 SDK의 1급 시민으로 채택한 셈이다.

개발자 관점에서 함의는 단순하다.

• 한 번 작성한 AGENTS.md / SKILL.md가 여러 벤더에서 거의 그대로 동작할 가능성이 커진다.
• 에이전트 정의가 “코드 안의 상수 문자열”이 아니라 “레포에 commit하는 마크다운 자산”이 된다.
• 결과적으로 에이전트 행동이 git diff·코드 리뷰·PR 컨벤션 위로 올라온다.

이건 작은 문법 통일이 아니라, 에이전트 정의가 라이브러리 API에서 “언어 외부의 합의된 문서 포맷”으로 이동하는 신호다.

최소 코드 예제

가장 빠른 사용법은 등록 없이 인라인으로 한 번에 띄우는 패턴이다. 공식 Antigravity Agent docs 예시 기반.

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Analyze the Q1 revenue data and create a slide deck.",
    system_instruction="You are a data analyst.",
    environment={"type": "remote"},
)

print(interaction.output_text)

cURL로는 다음과 같이 호출한다. 인증 헤더 x-goog-api-key가 빠지면 401이 떨어지니 누락하지 말 것.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "agent": "antigravity-preview-05-2026",
    "input": "Analyze the Q1 revenue data and create a slide deck.",
    "system_instruction": "You are a data analyst.",
    "environment": {"type": "remote"}
  }'

멀티턴 대화는 직전 인터랙션 id만 넘기면 된다.

followup = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Now turn slide 3 into a bar chart.",
    previous_interaction_id=interaction.id,
    environment={"type": "remote"},
)

샌드박스 자체는 같은 환경이 이어진다. 슬라이드 파일이 첫 호출에서 만들어졌다면, 두 번째 호출은 그 파일 위에서 작업한다. 출처: Gemini API Docs.

base_agent로 지금 지원되는 값은 antigravity-preview-05-2026 하나다. 도구 세트는 기본으로 code_execution, google_search, url_context가 켜져 있고, 필요 시 network.allowlist로 외부 도메인을 화이트리스트할 수 있다.

다른 frontier API와 한 줄씩 비교

같은 “행동하는 AI를 백엔드 API로 호출한다”는 카테고리 안에서 현재 시장의 위치를 짧게 정리한다.

요약하면 Google은 “행동하는 에이전트를 가장 적은 호출로, 가장 적은 인프라로 띄울 수 있는” 카테고리를 노렸다. OpenAI Code Interpreter가 같은 카테고리에서 가장 가까운 비교 대상이지만, 파일·웹 브라우징·복수 도구 조합까지 한 호출에 묶었다는 점에서 Google이 한 발 더 나갔다.

개발자가 지금 점검할 관전 포인트

1. 가격 모델은 공개되어 있다. Antigravity Agent docs 기준 과금은 사용한 Gemini 모델 토큰과 호출된 도구 기반의 pay-as-you-go이며, 작업 복잡도별 추정 비용 범위(공식 docs에 예시 task당 약 $0.25–$5 수준)가 함께 제시되어 있다. 또한 환경 컴퓨트(샌드박스의 CPU·메모리·실행 자원)는 preview 기간 동안 별도 청구되지 않는다고 명시되어 있어, 현재 시점 비용은 사실상 모델 토큰 사용량에 수렴한다. 활성 rate limit은 AI Studio Rate limits 페이지에서 모델·등급별로 직접 확인하는 게 정석이다. 출처: Antigravity Agent docs, Gemini API Rate limits.
2. Preview 상태이며 “Features and schemas may change”가 명시되어 있다. 같은 이유로 한 계정당 등록 가능한 managed agent는 최대 1000개, 버전 관리 및 롤백은 아직 지원되지 않는다.
3. 격리 수준은 “isolated, ephemeral Linux environment”라는 표현만 공식이고, 구체적인 격리 메커니즘 (gVisor·micro-VM·user namespace 등 중 어떤 것인가)은 현재 공개 자료에 명시되어 있지 않다. 민감 데이터를 다루는 시나리오라면 BAA·DPA 같은 계약 검토부터 시작해야 한다.
4. 네트워크 화이트리스트 (network.allowlist)는 사실상 “SSRF 방지의 1차 방어선”이 된다. 외부로 나가는 모든 도메인은 명시적으로 등록한다는 가정이 안전하다.
5. AGENTS.md / SKILL.md 자산은 모델/벤더에 묶이지 않는 형태로 작성해 두는 게 합리적이다. 같은 마크다운을 Claude Code, Antigravity, Managed Agents 사이에서 돌려쓰는 패턴이 곧 default가 될 가능성이 높다.

정리

Google이 던진 메시지는 단순하다. “에이전트의 인프라는 우리가 책임진다, 너는 마크다운으로 정체성과 능력만 적어라.” 만약 이 약속이 가격·격리·안정성 측면에서 지켜진다면, “행동하는 AI”를 자기 제품 안에 박는 작업의 진입장벽이 한 단계 크게 내려간다. 그리고 Anthropic이 먼저 정착시킨 AGENTS.md / SKILL.md 컨벤션을 Google이 1급 시민으로 채택한 것은, 시장이 무엇을 표준으로 받아들일지에 대한 분명한 신호다.

지금 시점에서 개발자가 할 일은 세 가지다. preview 액세스를 신청하고, 작은 AGENTS.md / SKILL.md 한 쌍을 작성해 실제 호출을 한 번 돌려보고, 환경 컴퓨트가 유료로 전환되는 시점을 트래킹하는 것이다.

참고 자료

• Google blog — Introducing Managed Agents in the Gemini API (2026-05-19)
• Google Developers Blog — All the news from the Google I/O 2026 Developer keynote
• Gemini API Docs — Antigravity Agent
• Gemini API Docs — Building Managed Agents
• Gemini API Docs — Rate limits
• Gemini Enterprise Agent Platform — Managed Agents API sandbox environment
• Developer Tech — Google adds Android app generation and Managed Agents to Gemini developer tools