Gemini API로 Managed Agents 구축하기: 완전한 개발자 가이드

추론하고, 코드를 작성 및 실행하고, 웹을 탐색하고, 파일을 관리하는 자율 에이전트는 그동안 몇 주에 걸친 인프라 작업이 필요했습니다. Gemini API의 Managed Agents 출시와 함께 Google은 그 설정을 단 하나의 API 호출로 압축했습니다. 한 번의 요청으로 Google이 호스팅하는 안전한 임시 Linux 샌드박스가 생성되고, 그 안에서 실제 작업을 수행할 준비가 된 에이전트가 실행됩니다.

이 가이드는 개발자가 알아야 할 모든 것을 다룹니다. Antigravity 에이전트의 동작 방식, 커스텀 에이전트의 구축 및 배포 방법, 재현 가능한 실행을 위한 환경 포크 방법, 네트워킹과 자격 증명 제한 방법, 그리고 새로운 Gemini CLI가 에이전트 중심 워크플로우에 어떻게 맞는지까지 설명합니다.

Gemini API Managed Agents란 무엇인가요?

Managed Agents는 Gemini API에서 자율 AI 에이전트를 위한 Google의 새로운 개발 프리미티브(primitive)입니다. 오케스트레이션 로직, 코드 실행 환경, 도구 호출 인프라, 보안 제어를 직접 하나씩 엮을 필요 없이, API가 이 모든 것을 처리합니다.

Interactions API에 대한 단일 호출만으로 샌드박스 처리된 Linux 환경이 프로비저닝되고, Gemini로 구동되는 에이전트가 시작되며, 작업이 처음부터 끝까지 실행됩니다. 에이전트는 Google이 관리하는 안전한 런타임 내에서 추론하고 계획을 세우며, 도구를 호출하고, 코드를 실행하고, 파일을 관리하고, 웹을 탐색할 수 있습니다.

이를 가능하게 하는 두 가지 표면이 있습니다.

• Interactions API — 런타임 인터페이스입니다. 작업을 보내면 추론하고 행동하는 에이전트가 돌아옵니다.
• Agents API — 제어 플레인(control plane)입니다. 커스텀 지침, 도구, 스킬, 환경 구성으로 이름이 지정된 에이전트를 정의하고, 등록하고, 관리합니다.

Antigravity 에이전트: 바로 사용할 수 있는 범용 에이전트

Gemini API의 첫 번째 범용 managed agent는 Antigravity입니다. Gemini 3.5 Flash로 구동되며, Antigravity IDE와 다른 Google 퍼스트파티 에이전트 제품 뒤에서 사용되는 것과 같은 harness에서 실행됩니다. Antigravity 이전에는 Deep Research만이 제공되는 managed agent였으며, 이는 다단계 연구 워크플로우를 위한 특화된 에이전트였습니다.

Antigravity는 그에 대응하는 범용 에이전트로, 단 한 번의 API 호출로 원격 Linux 환경을 프로비저닝하고 작업을 시작합니다.

Antigravity로 할 수 있는 일

관리되는 샌드박스 안에서 Antigravity 에이전트는 다음을 수행할 수 있습니다.

• Gemini 에이전트 harness를 사용해 추론하고 계획하기
• 안전한 Linux 환경에서 코드를 실행하고 파일 관리하기
• 웹을 탐색하여 실시간 데이터를 가져오고 처리하기
• 웹 검색, 코드 실행, 파일 I/O를 포함한 도구 사용하기

첫 번째 Antigravity API 호출

가장 단순한 Antigravity 호출 예시는 다음과 같습니다. 원격 환경을 프로비저닝하고, 에이전트를 실행하며, 출력을 반환하는 단 하나의 API 호출입니다.

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
    environment="remote",  # Remote Linux environment hosted by Google
)

print(interaction.output_text)

이게 전부입니다. 컨테이너 설정도, 샌드박싱 코드도, tool-calling 스캐폴딩도 필요 없습니다. Google이 이 모든 것을 처리합니다.

지속형 환경: 상태를 유지하는 멀티턴 에이전트

환경은 호출 간에 유지됩니다. 첫 번째 상호작용이 샌드박스를 프로비저닝하고 environment_id를 반환합니다. 후속 요청에서 그 ID를 전달하면, 에이전트는 이전 호출이 남긴 파일, 패키지, 상태를 그대로 이어받아 재개합니다.

# First call — provisions a new remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment="remote",
    input="Research the top 10 AI stories today and create a PDF briefing with summaries",
)

# Second call — resumes in the same environment with full state intact
interaction_2 = client.interactions.create(
    agent="antigravity-preview-05-2026",
    environment=interaction.environment_id,
    previous_interaction_id=interaction.id,
    input="Now create a landing page using javascript and html",
)

print(interaction_2.output_text)

이러한 상태 유지 기능이 다단계 워크플로우를 실용적으로 만듭니다. 한 호출에서 패키지를 설치하고, 파일을 작성하고, 분석을 실행한 에이전트는 그 모든 결과를 다음 호출로 자연스럽게 넘길 수 있습니다. 재설정도, 재다운로드도, 재실행도 필요 없습니다.

환경은 시작 시 외부 데이터도 받을 수 있습니다. Git 저장소, Google Cloud Storage 객체, 또는 인라인 콘텐츠를 에이전트가 작업을 시작하기 전에 샌드박스에 마운트할 수 있습니다.

커스텀 Managed Agents 구축하기

Antigravity 에이전트는 범용 작업을 잘 처리합니다. 하지만 프로덕션 사용 사례에는 거의 항상 커스텀 동작이 필요합니다. 특정 지침, 도메인 스킬, 독점 도구, 선별된 데이터 소스 등이 그것입니다. 이를 위해 Agents API가 존재합니다.

Gemini Managed Agents를 사용하면 지침, 스킬, 도구, 환경을 하나로 묶어 이름이 지정된 에이전트로 만들고 ID로 호출할 수 있습니다. 복잡한 오케스트레이션 코드를 작성하는 대신, AGENTS.md와 SKILL.md 같은 마크다운 파일에 모든 것을 선언적으로 정의하고 한 번만 등록하면 됩니다.

소스에서 에이전트 정의하기

시스템 지침과 소스를 지정해 처음부터 에이전트를 만들 수 있습니다. 소스는 GitHub 저장소, Google Cloud Storage 경로, 또는 인라인 콘텐츠일 수 있습니다. 플랫폼은 호출할 때마다 파일이 포함된 새 샌드박스를 프로비저닝합니다.

agent = client.agents.create(
    name="data-analyst",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "You are a data analyst agent..."
            },
            {
                "type": "inline",
                "target": ".agents/slide-maker/SKILL.md",
                "content": "Instructions for creating slides..."
            },
            {
                "type": "github",
                "source": "https://github.com/my-org/data-templates.git",
                "target": "/workspace/"
            },
            {
                "type": "gcs",
                "source": "gs://my-bucket/analysis-skills/",
                "target": "/.agents/skills/"
            },
        ]
    }
)

result = client.interactions.create(
    agent="data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote",
)

print(result.output_text)

한 번 등록되면 data-analyst는 이름으로 호출할 수 있는 지속형 에이전트가 됩니다. 각 실행은 정확히 같은 구성으로 깨끗한 환경을 프로비저닝하므로, 호출 간 상태가 새지 않습니다.

기존 환경 포크하기

커스텀 에이전트로 가는 가장 빠른 방법은 반복(iteration)일 때가 많습니다. 먼저 기본 Antigravity 에이전트로 인터랙티브하게 작업하면서 패키지를 설치하고, 템플릿을 만들고, 환경을 구성한 다음, 그 환경 스냅샷을 재사용 가능한 이름 있는 에이전트로 포크합니다.

# Step 1: Iterate with the base agent in a remote environment
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="Install pandas and matplotlib. Create an analysis template.",
    environment="remote"
)

# Step 2: Create a new agent from the existing environment snapshot
agent = client.agents.create(
    name="my-data-analyst",
    base_agent="antigravity-preview-05-2026",
    instructions="You are a data analyst that creates slide presentations.",
    base_environment=interaction.environment_id,
)

저장된 후에는 my-data-analyst의 이후 모든 호출이 그 기본 스냅샷에서 포크됩니다. 즉, 매번 깨끗하고 사전 구성된 상태에서 시작합니다.

result = client.interactions.create(
    agent="my-data-analyst",
    input="Analyze Q1 revenue data and create a slide deck.",
    environment="remote"
)

print(result.output_text)

fork-and-register 패턴은 대규모 설정이 필요한 에이전트에 특히 효과적입니다. 복잡한 의존성 그래프, 큰 모델 아티팩트, 혹은 매번 다시 빌드하기에는 너무 오래 걸리는 사전 컴파일된 템플릿 같은 경우입니다.

보안 네트워킹과 자격 증명 프록시

프로덕션 에이전트는 거의 항상 GitHub, 내부 API, 패키지 레지스트리 같은 외부 서비스에 접근해야 하며, 거의 항상 샌드박스 안에 민감한 자격 증명을 노출하지 않는 방식으로 접근해야 합니다. Managed Agents는 구성 가능한 egress proxy로 이 두 가지를 모두 처리합니다.

네트워크 구성은 두 가지 목적을 가집니다.

1. **허용 목록(allowlist)**은 아웃바운드 연결을 명시적으로 허용된 도메인으로 제한하여, 에이전트가 의도치 않은 외부 서비스에 접근하지 못하도록 막습니다.
2. **헤더 변환(header transforms)**은 서버 측에서 자격 증명을 주입하므로, API 토큰과 시크릿이 샌드박스 환경 자체로 전달되지 않습니다.

agent = client.agents.create(
    id="issue-resolver",
    base_agent="antigravity-preview-05-2026",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/my-org/backend",
                "target": "/workspace/repo",
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "api.github.com",
                    "transform": {
                        "Authorization": "Bearer ghp_your_github_token"
                    },
                },
                {"domain": "pypi.org"},
            ]
        },
    },
)

이 구성에서는 에이전트가 api.github.com과 pypi.org에만 접근할 수 있습니다. 다른 도메인에 연결하려는 시도는 차단됩니다. GitHub 요청에는 Authorization 헤더가 자동으로 포함되도록 변환되며, 샌드박스 코드는 토큰을 직접 보지 않습니다.

이 아키텍처는 내부 코드 저장소, 독점 API, 또는 자격 증명 관리가 규정 준수 요구사항인 모든 환경을 대상으로 배포되는 에이전트에 필수적입니다.

Gemini API CLI: 에이전트 우선 개발 경험

API와 함께 Google은 코딩 에이전트가 구조화되고 에이전트 친화적인 방식으로 Gemini API와 상호작용할 수 있도록 설계된 실험적 오픈소스 Gemini API CLI도 출시했습니다.

# Run a prompt against any model
gemini-api run "What is the capital of France?"

# Image generation
gemini-api run "A cat in space" --model gemini-3.1-flash-image-preview --output cat.png

# Text-to-speech
gemini-api run "Hello from Gemini" --model gemini-3.1-flash-tts-preview --voice Kore --output hello.wav

# Scaffold, test, and deploy an agent
gemini-api agents init my-agent
gemini-api agents test --prompt "Analyze the Q1 revenue data"
gemini-api agents create

# Run against a deployed agent
gemini-api run "Summarize this quarter" --agent my-agent

agents init / agents test / agents create 워크플로우는 Google이 개발자에게 Gemini API를 어떻게 활용하길 기대하는지 보여줍니다. 파일에 에이전트 동작을 정의하고, 로컬에서 테스트한 뒤, 이름 있는 managed agent로 배포하는 방식입니다. 인프라스트럭처-애즈-코드(infrastructure-as-code) 도구에 익숙한 패턴과 같습니다.

보완적인 도구들

CLI 외에도, 두 가지 추가 요소가 코딩 에이전트가 Gemini API를 최신 상태로 유지하는 데 도움이 됩니다.

• Gemini API Docs MCP server — MCP를 통해 Gemini 문서, SDK, 모델 정보에 실시간으로 접근할 수 있게 합니다. 코딩 에이전트는 오래된 학습 데이터에 의존하는 대신 문서를 직접 조회할 수 있습니다.
• gemini-interactions-api Skill — Interactions API 패턴과 모범 사례를 에이전트의 컨텍스트에 자동으로 주입하여, Gemini Managed Agents로 만든 에이전트가 처음부터 관례에 맞는 interaction 코드를 작성하도록 돕습니다.

Managed Agents가 프로덕션 사용 사례에서 중요한 이유

Managed Agents의 핵심 전제는 에이전트 개발에서 가장 어려운 부분이 모델 자체가 아니라 그 주변의 인프라라는 점입니다. 샌드박싱, 도구 통합, 자격 증명 관리, 환경 재현성, 네트워크 보안은 모두 에이전트를 출시하는 모든 팀이 개별적으로 해결해야 하는 문제입니다. Managed Agents는 그 부담을 Google이 대신 지도록 만듭니다.

그 변화는 프로덕션 배포에 실질적인 의미를 갖습니다.

재현 가능한 실행. 포크된 환경은 모든 에이전트 호출이 동일한 기준 상태에서 시작되도록 보장합니다. 의존성 드리프트도, 실행 간 상태 오염도 없습니다.

공격 표면 축소. 자격 증명이 샌드박스에 들어가지 않습니다. 네트워크 egress는 허용 목록으로 제한됩니다. 실행 환경은 임시적이고 격리되어 있습니다. 이는 선택적인 강화 단계가 아니라 기본값입니다.

더 빠른 반복. fork-and-register 워크플로우를 통해 팀은 인터랙티브하게 실험하고, 구성을 안정화한 뒤, 이름 있는 에이전트로 승격할 수 있습니다. 프로토타입과 프로덕션 사이에서 인프라를 다시 작성할 필요가 없습니다.

프레임워크 호환성. Managed Agents는 팀이 이미 사용 중인 오케스트레이션 프레임워크와 함께 동작합니다. 출시 파트너에는 Vercel AI SDK, LiteLLM, Agno, Eigent, LlamaIndex가 포함됩니다. 따라서 기존 워크플로우를 전면 재작성하지 않고도 관리형 인프라의 이점을 활용할 수 있습니다.

엔터프라이즈를 위한 Managed Agents

대규모로 커스텀 managed agent를 운영해야 하는 엔터프라이즈를 위해 Google은 Gemini Enterprise Agent Platform을 제공합니다. 동일한 API에 거버넌스, 중앙 집중식 가시성, 조직 수준 정책 제어가 추가된 형태입니다.

Gemini API의 Managed Agents는 현재 프리뷰로 제공됩니다. 엔터프라이즈 팀은 Enterprise Agent Platform을 통해 동일한 managed agent 프리미티브에 접근할 수 있으며, 감사, DLP 강제 적용, 멀티팀 거버넌스를 위한 추가 제어 기능도 제공됩니다.

핵심 요점

Gemini API Managed Agents 출시는 개발자에게 이전에는 함께 얻기 어려웠던 세 가지를 제공합니다. 바로 즉시 사용할 수 있는 유능한 범용 에이전트(Antigravity), 프로덕션급 보안을 갖춘 커스텀 에이전트를 정의하고 배포하기 위한 깔끔한 API, 그리고 에이전트를 만드는 에이전트를 위해 설계된 개발자 경험 — CLI, MCP server, Skills입니다.

인프라 결정도 타당합니다. 지속형 환경, 환경 포크, egress 허용 목록, 서버 측 자격 증명 주입은 프로덕션 에이전트 배포에 적합한 프리미티브입니다. 오픈소스 CLI와 Skill은 에이전트 개발자 경험이 그 기반 모델의 성능만큼이나 중요하다는 Google의 인식을 보여줍니다.

Eigent의 모델 비종속(platform-agnostic) 플랫폼 위에서 구축하는 팀에게 Gemini Managed Agents는 강력한 배포 대상입니다. Google이 샌드박스 실행 계층을 처리하는 동안, Eigent가 모델 제공자 전반에 걸쳐 작업을 지능적으로 라우팅하는 기능과 잘 맞물립니다.

시작하려면 AI Studio Playground에서 Antigravity 에이전트를 사용해 보고, Managed Agents 문서를 읽고, Python SDK 또는 JavaScript SDK를 설치하세요.

자주 묻는 질문

Gemini API Managed Agents란 무엇인가요?

Gemini API Managed Agents는 Google이 호스팅하는 샌드박스 처리된 Linux 환경에서 실행되는 자율 AI 에이전트입니다. Interactions API에 대한 단일 호출로 샌드박스가 프로비저닝되고, Gemini로 구동되는 에이전트가 시작되며, 코드 실행, 웹 브라우징, 파일 관리까지 포함한 작업이 사용자의 인프라 설정 없이 수행됩니다.

Antigravity 에이전트란 무엇인가요?

Antigravity는 Gemini 3.5 Flash로 구동되는 Gemini API의 Google 범용 managed agent입니다. 안전한 원격 Linux 환경 안에서 추론하고 계획하며, 코드를 실행하고, 파일을 관리하고, 웹을 탐색할 수 있습니다. Antigravity IDE와 다른 Google 퍼스트파티 에이전트 제품을 구동하는 것과 같은 agent harness를 사용합니다.

지속형 환경은 어떻게 작동하나요?

environment="remote"를 사용하는 첫 번째 interaction 호출이 새 샌드박스를 프로비저닝하고 environment_id를 반환합니다. 이후 호출에서 그 ID를 전달하면 같은 환경에서 에이전트가 재개되며, 파일, 설치된 패키지, 상태가 모두 보존됩니다. 이를 통해 호출 간 재설정 없이 상태를 유지하는 멀티턴 워크플로우를 구현할 수 있습니다.

커스텀 managed agent는 어떻게 만들 수 있나요?

Agents API를 사용해 base agent, 지침, 소스(GitHub 저장소, GCS 객체, 또는 인라인 콘텐츠)를 지정하여 이름 있는 에이전트를 정의하세요. 등록 후에는 Interactions API를 통해 이름으로 에이전트를 호출할 수 있습니다. 또는 Antigravity와 인터랙티브하게 반복 작업을 한 뒤, 기존 environment_id를 가리키는 base_environment를 사용해 client.agents.create()로 그 결과 환경을 이름 있는 에이전트로 포크할 수도 있습니다.

자격 증명 프록시는 어떻게 작동하나요?

managed agent egress proxy는 샌드박스와 인터넷 사이에 위치합니다. 허용된 도메인의 allowlist를 구성하고, 필요하면 도메인별 transform 헤더 규칙도 지정합니다. 프록시는 일치하는 아웃바운드 요청에 Authorization: Bearer <token> 같은 헤더를 자동으로 주입하므로, 샌드박스 코드는 토큰 값에 직접 접근하지 않습니다.

어떤 프레임워크가 Gemini Managed Agents와 호환되나요?

Gemini Managed Agents는 출시 시점부터 Vercel AI SDK, LiteLLM, Agno, Eigent, LlamaIndex와 바로 동작합니다. Interactions API는 REST 기반이므로, HTTP를 사용할 수 있는 어떤 오케스트레이션 프레임워크도 통합할 수 있습니다.

Gemini API CLI란 무엇인가요?

Gemini API CLI는 코딩 에이전트가 Gemini API와 상호작용할 수 있도록 설계된 실험적 오픈소스 도구입니다. 프롬프트 실행, 이미지 및 오디오 생성, 그리고 init, test, create, run으로 구성된 전체 managed agent 생명주기를 명령줄에서 관리할 수 있습니다.

Gemini Managed Agents는 엔터프라이즈에서도 사용할 수 있나요?

네. 동일한 Managed Agents API는 추가 거버넌스 제어, 중앙 집중식 가시성, DLP 강제 적용, 조직 정책 관리를 포함한 Gemini Enterprise Agent Platform을 통해 제공됩니다. Gemini API의 Managed Agents는 현재 프리뷰로 제공됩니다.