실습 노트
Gemini API Managed Agents: 원격 Linux 샌드박스에 에이전트를 맡길 때 볼 것
Gemini API Managed Agents가 원격 Linux 샌드박스에서 코드·파일·웹 작업을 실행하는 구조와 네트워크·비용·수명 제한을 정리합니다.
에이전트에게 코드를 실행시키려면 모델 호출만으로는 부족합니다. 파일을 읽고 쓰는 작업 공간, 명령을 실행할 환경, 웹 접근 정책, 결과를 이어 갈 상태가 함께 필요합니다. Google의 Gemini API Managed Agents는 한 번의 Interactions API 호출로 Google이 호스팅하는 Linux 샌드박스를 만들고, 그 안에서 에이전트 루프가 코드 실행·파일 관리·웹 탐색을 수행하는 방식입니다.
Managed Agent의 기본 구조
Google 공식 문서가 설명하는 기본 흐름은 agent, environment="remote", input을 지정해 상호작용을 만드는 것입니다. 예제에서는 antigravity-preview-05-2026 에이전트가 원격 환경을 만들고 Python 파일을 생성한 뒤 내용을 읽습니다. 다음 턴에서는 이전 상호작용 ID로 대화 맥락을 이어 가고, 환경 ID로 파일과 설치 상태가 남은 샌드박스를 다시 지정합니다.
이 구분이 중요합니다.
- 대화 상태: 이전 요청, 응답, 도구 사용 흐름을 이어 가는 식별자
- 환경 상태: 샌드박스 안의 파일, 패키지, 실행 환경을 이어 가는 식별자
- 작업 결과: 스트리밍 응답이나 다운로드 파일처럼 애플리케이션이 회수해야 하는 산출물
따라서 에이전트에게 “지난번 파일을 계속 수정해”라고 말하는 것만으로는 부족할 수 있습니다. 다음 요청에 대화 상태와 환경 상태를 모두 연결했는지 확인해야 합니다. 이 글은 공식 Quickstart를 읽고 구조를 해석한 것이며, 실제 Gemini API 호출이나 샌드박스 작업을 이 저장소에서 실행한 내용이 아닙니다.
샌드박스라는 말만 믿지 말아야 하는 이유
Google 문서에 따르면 Managed Agents는 Public Preview이며, 각 에이전트는 운영체제 수준에서 격리된 환경에서 실행됩니다. 동시에 기본 네트워크는 외부로 제한 없이 나갈 수 있고, 필요하면 도메인 허용 목록으로 줄이거나 끌 수 있다고 안내합니다. 즉 “샌드박스”는 네트워크·자격 증명·산출물 정책을 대신 결정해 주는 단어가 아닙니다.
외부 도구와 API를 연결할 때는 권한 범위를 최소화해야 합니다. 문서의 설명처럼 자격 증명은 egress proxy의 헤더 변환으로 주입할 수 있고 샌드박스 내부에 직접 노출되지 않도록 설계할 수 있지만, 에이전트가 접근할 수 있는 자격 증명의 권한 자체가 넓다면 위험은 사라지지 않습니다. 짧은 수명의 토큰, 읽기 전용 서비스 계정, 허용된 목적지 목록을 함께 두는 이유입니다.
비용은 모델 토큰만 세면 안 된다
Managed Agents는 모델 토큰과 도구 사용량을 기준으로 과금됩니다. Google은 한 번의 상호작용에서 여러 추론 루프가 발생하고, 일반적으로 10만~300만 토큰이 소비될 수 있다고 설명합니다. Preview 기간에는 샌드박스의 환경 컴퓨트 비용을 청구하지 않는다고 안내하지만, 토큰과 도구 사용 비용까지 무료라는 뜻은 아닙니다.
이 구조에서는 짧은 프롬프트 한 번의 가격보다 종료 조건이 중요합니다.
- 몇 단계의 계획과 재시도를 허용할 것인가
- 웹 탐색과 코드 실행을 모두 켤 필요가 있는가
- 파일 생성 후 사람의 검토를 거쳐야 배포할 것인가
- 반복 요청마다 새 환경을 만들 것인가, 기존 환경을 이어 갈 것인가
공식 가격 문서는 비용 계산의 기준을 제공하지만 조직의 실제 사용량을 보장하지 않습니다. 이 글에서 독립적으로 측정한 토큰 소비나 비용 비교 결과는 없으므로, 도입 전에는 동일한 업무와 종료 조건으로 별도 계측해야 합니다.
환경 수명과 복구 설계
공식 Agents overview에는 환경이 7일 동안 비활성 상태이면 영구 삭제되고, VM은 유휴 상태 뒤 중지되며 다음 요청에서 콜드 스타트가 발생할 수 있다고 적혀 있습니다. 기본 환경에는 Ubuntu 기반 도구와 Python 3.12, Node.js 22가 제공되고, 최대 에이전트 수는 1,000개로 안내됩니다.
이 제한은 “원격 개발 서버”라는 기대와 다릅니다. 장기 보관해야 하는 결과를 샌드박스 파일 시스템에만 두면 안 됩니다. 중요한 파일은 작업이 끝날 때 애플리케이션이 검증한 뒤 별도 저장소로 옮기고, 환경 ID를 데이터베이스나 로그에 남기더라도 만료될 수 있다는 전제를 둬야 합니다.
권장되는 최소 흐름은 다음과 같습니다.
- 새 작업마다 입력·권한·네트워크 허용 목록을 정합니다.
- 에이전트가 만든 코드와 데이터를 자동 배포하지 않고 검토 큐에 둡니다.
- 결과 파일의 해시, 생성 시각, 사용한 환경 ID를 애플리케이션 쪽에 기록합니다.
- 7일 이상 이어질 상태는 외부 저장소에 보관하고 새 환경에서 복구합니다.
- Preview가 끝난 뒤 달라질 수 있는 가격·제한·모델 버전을 주기적으로 다시 확인합니다.
적용 판단
Managed Agents는 에이전트 실행기를 직접 운영하지 않고도 코드·파일·웹 작업을 묶어 실험할 수 있는 선택지입니다. 다만 Public Preview, 기본 외부 네트워크, 다중 추론 루프 비용, 환경 삭제라는 조건이 함께 있습니다. 따라서 민감한 업무에서는 “Google이 실행한다”는 편의보다 허용 목록과 승인 단계를 먼저 설계해야 합니다.
독립 보안 감사나 특정 조직의 실제 운영 성과는 확인한 공식 문서에 제시되지 않았습니다. 현재 공개된 근거만으로는 기능 구조와 운영 조건을 판단할 수 있을 뿐, 샌드박스가 모든 공격 경로를 차단한다거나 비용이 일정하다고 말할 수 없습니다. 작은 비민감 작업으로 환경 연결·파일 회수·네트워크 차단·재시작을 검증한 뒤 범위를 넓히는 편이 합리적입니다.