코드 실행과 파일 생성이 필요한 에이전트를 직접 운영하려면 컨테이너, 상태 저장, 네트워크 제한, 비밀정보 주입과 세션 수명 관리를 구현해야 한다. Gemini Managed Agents는 Gemini API의 Interactions API를 통해 이런 실행 환경을 Google이 관리하는 원격 Linux 샌드박스로 제공한다. 기본 Antigravity 에이전트를 바로 호출하거나, 지침·스킬·데이터를 포함한 자체 관리형 에이전트를 정의할 수 있다.

핵심 동작

google-antigravity가 데스크톱·CLI·SDK까지 포함하는 개발 플랫폼이라면, Gemini Managed Agents는 그 계열의 실행 하네스를 애플리케이션에서 API로 호출하는 면에 초점을 둔다.

첫 호출

from google import genai

client = genai.Client()

result = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="리포지토리를 분석하고 테스트 실패 원인을 보고서로 작성해줘.",
    environment="remote",
)

print(result.output_text)

첫 호출이 만든 environment_id를 다시 넘기면 설치된 패키지와 작성된 파일을 유지한 채 후속 작업을 이어갈 수 있다. 대화 기록까지 유지하려면 previous_interaction_id도 함께 전달한다.

데이터와 스킬을 탑재한 사용자 정의 에이전트

관리형 에이전트는 저장소, Cloud Storage, 인라인 파일을 기본 환경에 마운트할 수 있다. .agents/AGENTS.md와 .agents/skills/<name>/SKILL.md를 포함하면 실행 규칙과 반복 능력도 함께 배포된다.

agent = client.agents.create(
    id="report-builder",
    base_agent="antigravity-preview-05-2026",
    system_instruction="분석 결과를 표와 출처가 있는 PDF로 내보내라.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "외부 전송 전에 민감 정보 여부를 검사하라.",
            },
            {
                "type": "repository",
                "source": "https://github.com/example/data-project",
                "target": "/workspace/project",
            },
        ],
    },
)

보안 경계

원격 샌드박스라는 사실만으로 안전한 것은 아니다. 기본 환경은 외부 네트워크에 접근할 수 있으므로 민감 저장소나 외부 API를 쓰는 에이전트에는 허용 도메인 목록과 비밀정보 주입 정책이 필요하다.

• 네트워크 허용 목록(allowlist)으로 접근할 호스트만 열어 둔다.
• 자격증명은 샌드박스 파일에 넣지 않고 egress proxy의 HTTP 헤더 변환으로 주입한다.
• Git 저장소, 업로드 파일, 생성 결과물에 개인정보나 비밀이 포함될 수 있는지 검토한다.
• 환경이 영구 저장소가 아니므로 필요한 산출물은 삭제 기한 전에 다운로드하거나 외부 저장소로 옮긴다.

언제 선택할까

• 에이전트가 코드를 실행하고 파일 산출물을 만들어야 하지만 직접 런타임을 운영하고 싶지 않을 때
• 데이터 분석, 리서치, 코드 수정처럼 동일 샌드박스에서 여러 턴을 이어가야 할 때
• 팀별 AGENTS.md와 스킬을 배포 가능한 에이전트 구성으로 관리하려 할 때
• 외부 네트워크와 비밀정보 접근을 정책으로 제한해야 할 때

서비스 조건

Gemini Managed Agents는 오픈소스 런타임이 아니라 Gemini API 관리형 서비스다. 사용 가능 지역, 프리뷰 기능, 과금과 데이터 처리 조건은 배포 전에 Gemini API 약관과 최신 공식 문서를 기준으로 확인해야 한다.

관련 문서

• gemini — Google의 멀티모달 모델 및 서비스 생태계
• gemini-3-5 — 관리형 에이전트의 기반 모델
• google-antigravity — 데스크톱, CLI, SDK와 관리형 에이전트를 묶은 개발 플랫폼
• agent-harness — 모델 외부 실행 루프와 안전장치 설계

참고 자료

• Managed Agents Quickstart — Google AI for Developers (2026-05-27 확인)
• Gemini API Additional Terms of Service — Google AI for Developers
• Gemini Managed Agents: Developer Guide — Philipp Schmid (2026-05-26)