Gemini Managed Agents 팁 – 5줄 코드 뒤에서 일어나는 10단계 내부 실행 흐름

시작: 5줄 코드
10단계 내부 실행 흐름
단계별 상세
2. Sandbox 부팅
3. 소스 마운트
4. 스킬 로드
5–9. 모델 루프
10. 최종 응답
핵심 시사점
사용 패턴
참고 자료

gemini-managed-agents API는 5줄로 에이전트를 실행할 수 있다. 하지만 그 한 번의 호출 뒤에는 sandbox 부팅, 스킬 로드, 모델 루프 실행이 모두 숨어 있다. 내부 작동 원리를 이해하면 디버깅, 성능 최적화, 스킬 설계에 도움이 된다.

시작: 5줄 코드

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="최신 레고 세트 데이터를 분석하고 차트가 포함된 PDF 리포트를 생성해줘",
    environment="remote",
)

print(interaction.output_text)

이 코드는 단순한 모델 호출이 아니다. 뒤에서 10단계 실행 흐름이 진행된다.

10단계 내부 실행 흐름

1. Request      → HTTPS로 Interactions API에 프롬프트 전달
2. Boot Sandbox → Debian Linux VM (4 vCPU, 16GB) 부팅
3. Mount Sources → 코드, 데이터, GCS 버킷 등 소스 마운트
4. Discover Skills → 사용 가능한 스킬 목록 로드
5. Reason       → Gemini 3.5 Flash가 태스크 계획
6. Tool Call    → code_execution, filesystem 등 도구 선택
7. Execute      → VM 내부에서 코드 실행
8. Return Results → 실행 결과를 모델에 반환
9. Loop         → 완료까지 5–8 반복
10. Final Response → output_text 반환

단계별 상세

2. Sandbox 부팅

격리된 Debian Linux 환경이 매 interactions.create() 호출마다 새로 부팅된다. 4 vCPU + 16GB RAM, 워크스페이스 디렉터리가 자동 생성된다. 이 VM은 사용자의 머신이 아니라 Google 인프라에서 실행된다.

3. 소스 마운트

요청에 소스(코드, 파일, GCS 버킷)를 지정하면 /workspace에 마운트된다. 에이전트가 기존 코드베이스나 데이터를 참조하도록 할 수 있다.

4. 스킬 로드

사용 가능한 스킬이 발견된다. 기본 스킬:

code_execution — Python, bash 실행
filesystem — 파일 읽기/쓰기
GCS — Google Cloud Storage 접근

사용자 정의 스킬을 등록하면 이 단계에서 함께 로드된다.

5–9. 모델 루프

Gemini 3.5 Flash가 루프를 돌며 태스크를 처리한다. 단계 5(Reason)에서 다음 도구를 결정하고, 6(Tool Call)에서 도구를 선택하고, 7(Execute)에서 VM 안에서 실행하고, 8(Return Results)에서 결과를 다시 모델에 넣는다. 태스크가 완료될 때까지 반복한다.

Model → pick tool → execute in VM → result → Model → pick tool → ...

10. 최종 응답

루프가 완료되면 interaction.output_text에 최종 결과가 담긴다. PDF, 차트 등 파일 결과물은 별도 필드로 접근한다.

핵심 시사점

격리 보장: 코드는 내 머신이 아닌 격리된 VM에서 실행된다. 의도치 않은 로컬 파일 접근이나 프로세스 실행 걱정이 없다.

단일 호출 = 완전한 실행: 프롬프트를 보내고 결과를 받는 동안 중간 루프를 직접 관리할 필요가 없다. 하지만 내부적으로 여러 번의 모델 호출과 도구 실행이 일어난다는 점을 비용 추산 시 감안해야 한다.

Gemini 3.5 Flash 고정: 현재 오케스트레이션 모델은 Flash다. 더 강력한 모델을 원하면 에이전트 설정에서 별도 지정이 필요하다.

환경은 ephemeral: sandbox는 매 호출마다 새로 부팅된다. 세션 간 상태를 유지하려면 GCS나 외부 저장소를 활용해야 한다.

사용 패턴

# 파일 결과물이 있는 경우
interaction = client.interactions.create(
    agent="antigravity-preview-05-2026",
    input="CSV를 읽고 막대 차트를 PNG로 저장해줘",
    environment="remote",
    sources=[{"type": "inline", "content": csv_data}],
)

# 파일 다운로드
for artifact in interaction.artifacts:
    with open(artifact.name, "wb") as f:
        f.write(artifact.content)

참고 자료

How Gemini Managed Agents Works under the Hood — Philipp Schmid (2026-06-10)

Like?

AI Sparkup