Gemini API 매니지드 에이전트 입문 — Google 관리 샌드박스에서 자율 AI 구동하기

Google이 Gemini API의 매니지드 에이전트(Managed Agents)를 공개 프리뷰(Public Preview)로 제공하기 시작했습니다(2026년 5월 19일 발표). 단 1회의 API 호출로 Google이 호스트하는 Linux 샌드박스(Sandbox)가 프로비저닝되며, 그 안에서 에이전트가 「추론·계획·코드 실행·파일 조작·Web 브라우징」을 자율적으로 수행합니다.

지금까지 자율 에이전트를 구동하려면 코드 실행용 샌드박스, 파일 영속화, 도구 호출 오케스트레이션(Orchestration)과 같은 「스캐폴딩(Scaffolding, 기반 구조)」을 직접 구축해야 했습니다. 매니지드 에이전트는 이러한 기반 구조를 Google 측에서 대신 처리해 주는 매니지드 서비스(Managed Service)입니다.

이 기사에서는 공식 문서를 바탕으로 Gemini API 매니지드 에이전트의 전체 모습과 google-genai SDK를 사용한 기본적인 구현 패턴을 해설합니다.

• Gemini API 매니지드 에이전트의 구조와 제공되는 2종류의 에이전트

• client.interactions.create()를 사용한 기본적인 호출 방법

• 샌드박스 환경(Environment)을 재사용하여 멀티턴(Multi-turn)으로 상태를 이어가는 방법

• 커스텀 에이전트 정의 방법과 네트워크 제어·요금 체계의 요점

• AI 에이전트를 애플리케이션에 통합하고 싶은 엔지니어

• 코드 실행 샌드박스를 직접 운영하는 번거로움을 줄이고 싶은 분

• Gemini API로 도구 실행형 에이전트를 시도해 보고 싶은 분

• Python 3.9 이상

• google-genai SDK

• Gemini API 키 (Google AI Studio에서 취득)

매니지드 에이전트는 집필 시점(2026년 6월) 기준으로 공개 프리뷰 상태입니다. 모델명(예: antigravity-preview-05-2026)이나 API 사양은 GA(General Availability) 전까지 변경될 가능성이 있습니다. 최신 정보는 공식 문서를 참조해 주세요.

• Gemini API 매니지드 에이전트는 1회 호출로 Linux 샌드박스를 실행하여 자율 에이전트를 구동하는 매니지드 서비스
• 범용 **Antigravity 에이전트 (Gemini 3.5 Flash 기반)**와 Deep Research 에이전트의 2종류가 제공됨
• client.interactions.create(agent=..., input=..., environment="remote")로 호출하며, environment_id를 전달하면 상태를 이어갈 수 있음

공식 문서에서는 매니지드 에이전트를 「설정 가능한 에이전트 하네스(Agent Harness)」라고 설명합니다. 여기서 말하는 하네스란 모델이 사고하고, 도구를 호출하며, 그 결과를 받아 다음 행동을 결정하는 일련의 루프(Loop)를 돌리는 실행 기반을 의미합니다.

기존의 「단발성 생성 API」와의 차이점은 1회의 요청으로 여러 번의 추론 루프가 돌아간다는 점에 있습니다. 에이전트는 태스크를 받으면 스스로 코드를 작성하여 실행하고, 생성된 파일을 읽고, Web을 검색하는 등의 시행착오를 인간이 매번 지시하지 않아도 자율적으로 진행합니다.

에이전트	베이스 모델	용도
Antigravity	Gemini 3.5 Flash	범용. 코드 실행·파일 관리·Web 브라우징 수행
Deep Research	(리서치 특화)	시장 분석·듀 딜리전스(Due Diligence)·문헌 조사 등의 자율 리서치

Antigravity가 범용 에이전트이며, 우선 이것을 시도하는 것이 기본입니다. Deep Research는 복잡한 조사 태스크에 특화된 에이전트입니다.

에이전트가 구동되는 Linux 샌드박스에는 미리 실행 환경이 준비되어 있습니다. 공식 문서에 따르면 주요 사양은 다음과 같습니다.

• 베이스 OS: Ubuntu (Python 3.12·Node.js 22 프리인스톨)
• 환경은 비활성 상태가 7일간 지속되면 완전히 삭제됨
• 계정당 최대 1,000개의 에이전트까지 생성 가능
• VM은 일정 비활성 기간이 지나면 셧다운되며, 다음 요청 시 상태를 복원(Cold Start)

즉, 코드 실행을 위한 컨테이너나 언어 런타임 (Language Runtime)을 직접 준비할 필요가 없으며, 파일과 상태도 일정 기간 유지됩니다.

지금부터는 google-genai SDK를 사용한 구현 패턴을 살펴보겠습니다. 먼저 SDK를 설치합니다.

pip install google-genai

퀵스타트 (Quickstart)를 따라 Antigravity 에이전트에게 간단한 작업을 요청해 보겠습니다. client.interactions.create()가 매니지드 에이전트 (Managed Agent)를 호출하는 핵심 메서드입니다.

from google import genai
client = genai.Client()
interaction = client.interactions.create(
...

주요 파라미터 (Parameter)는 다음과 같습니다.

파라미터	설명
agent	사용할 에이전트 ID (예: antigravity-preview-05-2026)
input	에이전트에 대한 지시 (자연어)
environment	실행 환경. "remote"로 설정 시 새로운 샌드박스 (Sandbox) 할당

이 코드에서 에이전트는 "피보나치 수를 생성하는 Python 스크립트를 작성한다 → 실행한다 → 파일로 저장한다 → 다시 읽어서 표시한다"라는 여러 단계를 샌드박스 내에서 자율적으로 처리합니다. 응답의 environment_id는 다음 호출에서 재사용하기 위한 식별자입니다.

에이전트의 진정한 가치는 이전 작업 결과를 이어받아 다음 작업을 수행할 수 있다는 점에 있습니다. 앞선 호출에서 얻은 interaction.id와 interaction.environment_id를 다음 호출에 전달하면 동일한 샌드박스 상에서 대화를 지속할 수 있습니다.

interaction_2 = client.interactions.create(
agent="antigravity-preview-05-2026",
previous_interaction_id=interaction.id,
...

previous_interaction_id로 대화의 문맥 (Context)을, environment에 environment_id를 전달함으로써 파일 시스템의 상태를 이어받습니다. 이를 통해 첫 번째 호출에서 생성한 fibonacci.txt를 두 번째 호출에서 그대로 읽어 그래프로 시각화하는 등의 연속적인 작업이 가능해집니다.

시간이 오래 걸리는 작업의 경우, 에이전트의 사고 과정이나 도구 실행의 중간 과정을 스트리밍 (Streaming)으로 받을 수 있습니다. stream=True를 지정하면 이벤트를 순차적으로 수신할 수 있습니다.

stream = client.interactions.create(
agent="antigravity-preview-05-2026",
input="Read Hacker News, summarize the top 5 stories, and save the results as a PDF.",
...

이 예시에서는 웹을 탐색하여 Hacker News의 상위 기사를 요약하고 PDF로 저장하는 일련의 작업 진행 상황을 순차적으로 출력합니다.

범용 Antigravity 외에도, 고유한 지시 사항이나 도구 구성을 가진 **커스텀 에이전트 (Custom Agent)**를 정의할 수 있습니다. client.agents.create()를 통해 베이스 에이전트 (Base Agent), 시스템 지시 (System Instruction), 사용할 도구를 지정합니다.

agent = client.agents.create(
id="research-planner",
base_agent="antigravity-preview-05-2026",
...

생성한 에이전트는 agent="research-planner"와 같이 ID를 지정하여 interactions.create()를 통해 호출할 수 있습니다. 또한, 파일 시스템 조작은 environment를 지정하여 실행할 때 자동으로 이용 가능해지므로, 위와 같이 명시적으로 도구에 추가하지 않더라도 생성된 파일의 읽기 및 쓰기가 가능합니다 (지정 가능한 도구의 정확한 목록은 공식 문서를 참조하십시오).

공식 블로그에 따르면, 에이전트의 동작은 AGENTS.md나 SKILL.md

와 같은 Markdown 파일로 커스텀 지시사항(Custom Instructions)이나 스킬(Skill)을 정의함으로써 확장할 수 있도록 설계되어 있어, 복잡한 오케스트레이션(Orchestration) 코드를 작성할 필요가 없습니다. Claude Code의 CLAUDE.md나 AGENTS.md와 동일한 발상으로, 에이전트의 '인격'과 '절차'를 선언적(Declarative)으로 기술할 수 있는 것입니다.

샌드박스(Sandbox)는 기본적으로 외부로의 아웃바운드 통신(Outbound Communication)이 무제한입니다. 따라서 불필요한 통신을 차단하고 싶다면, 네트워크 허용 목록(Allowlist)을 설정하여 특정 도메인이나 와일드카드 패턴으로만 전송 대상을 제한할 수 있습니다. 구체적인 설정 방법은 공식 문서를 확인하십시오.

에이전트가 생성한 코드나 데이터 변환, 설정 변경은 배포 전에 반드시 검증해야 합니다. 특히 외부 시스템과 연동하거나 데이터를 변경하는 태스크의 경우, 출력의 타당성 확인이 중요하다는 점이 공식 문서에서도 주의사항으로 언급되어 있습니다.

요금은 토큰 사용량과 도구(Tool) 소비에 기반한 종량제입니다. 공식 문서에 따르면, 1회의 인터랙션(Interaction)은 여러 번의 추론 루프(Inference Loop)를 동반하기 때문에 대략 10만~300만 토큰을 소비하는 것으로 알려져 있습니다. 단발성 생성 API와 비교했을 때 토큰 소비량이 훨씬 커지기 쉽다는 점은 비용 설계 시 반드시 유념해야 할 포인트입니다.

참고로, 샌드박스의 컴퓨팅 비용은 공개 프리뷰(Public Preview) 기간 동안에는 과금되지 않는 것으로 알려져 있습니다 (프리뷰 종료 후의 취급은 변경될 수 있습니다).

도구 실행형 매니지드 에이전트(Managed Agent)는 각 기업이 잇따라 투입하고 있는 영역입니다. Anthropic 또한 Claude를 위해 자사 인프라 상의 샌드박스에서 도구를 실행하는 메커니즘을 제공하고 있습니다. Gemini API의 매니지드 에이전트는 Google이 호스트하는 샌드박스를 그대로 사용할 수 있는 풀 매니지드(Full-managed)형이라는 점이 특징이며, 인프라 운영 부담을 최소화하고 싶은 케이스에 적합합니다.

반면, 샌드박스 실행 환경을 완전히 자사 관리하에 두고 싶다면 셀프 호스트(Self-hosted)형을 제공하는 선택지도 있습니다. 요구사항(운영 부하를 낮추고 싶은지 / 실행 환경을 통제하고 싶은지)에 따라 구분하여 사용하는 것이 좋습니다.

• Gemini API 매니지드 에이전트는 1회 호출로 Linux 샌드박스를 실행하여 자율 에이전트를 구동하는 풀 매니지드 서비스
• 범용적인 **Antigravity (Gemini 3.5 Flash)**와 Deep Research 두 종류가 제공됨
• client.interactions.create()가 중심이며, environment_id와 previous_interaction_id를 이어받으면 멀티 턴(Multi-turn)으로 상태를 유지할 수 있음
• client.agents.create()로 도구 구성 및 지시사항을 가진 커스텀 에이전트를 정의할 수 있음
• 1회 인터랙션에서 10만~300만 토큰을 소비할 수 있으므로 비용 설계에 주의

기반 인프라 구축을 Google에 맡길 수 있기 때문에, 에이전트가 '수행하고자 하는 작업'에 집중할 수 있다는 것이 큰 이점입니다. 우선 Antigravity 에이전트로 간단한 태스크를 요청해 보고, 환경 재사용이나 커스텀 에이전트 정의로 범위를 넓혀가는 것이 좋습니다.

• Agents Overview | Gemini API — 매니지드 에이전트의 전체상 및 사양
• Managed Agents Quickstart | Gemini API — 기본적인 호출 코드
• Introducing Managed Agents in the Gemini API | Google Blog — 공식 발표 (2026-05-19)