Gemini API Managed Agents, 3.6 Flash 기본 적용과 샌드박스 제어 훅 도입

KEY POINT

- Gemini API Managed Agents가 Gemini 3.6 Flash를 기본 모델로 채택하고, 무료 티어 접근 권한과 샌드박스 제어용 환경 훅(Environment Hooks) 기능을 추가했다.

- 개발자는 `.agents/hooks.json` 설정을 통해 도구 호출 전후에 커스텀 스크립트를 실행하고, `max_total_tokens`로 자율 루프의 비용 소모를 물리적으로 제한할 수 있다.

- LLM의 확률적 결과물에 대해 픽셀 검사 등 결정론적 검증이 필요한 워크플로우라면, 외부 오케스트레이션 대신 샌드박스 내부 훅을 통한 검증-필터링-출력 파이프라인 구축을 선택해야 한다.

#Google #Gemini #ManagedAgents #AI에이전트 #샌드박스

Gemini 3.6 Flash 기본 적용 및 무료 티어 접근 확대

Google DeepMind는 `antigravity-preview-05-2026` 에이전트의 기본 모델을 Gemini 3.6 Flash로 업데이트했다. 사용자는 별도의 코드 수정이나 설정 변경 없이 다음 상호작용부터 업데이트된 모델의 성능을 자동으로 적용받는다. 모델 선택의 유연성을 위해 `agent_config.model` 파라미터를 통해 특정 모델을 명시적으로 지정하거나, 비용 절감이 필요한 작업에 Gemini 3.5 Flash-Lite를 할당해 운영 비용을 낮출 수 있다.

Google은 결제 정보가 등록되지 않은 무료 티어 프로젝트에서도 API 키를 통해 Managed Agents 기능을 실험할 수 있도록 접근 권한을 확대했다. 개발자는 활성화된 결제 수단 없이도 구글이 관리하는 인프라와 실행 환경에서 에이전트 워크플로우의 프로토타입을 빠르게 제작하고 검증할 수 있다. 이는 진입 장벽을 낮춰 더 많은 개발자가 에이전트 기반의 자동화 설계를 시도하게 만든다.

Gemini Interactions API는 단일 API 호출을 통해 모델의 추론, 코드 실행, 패키지 설치, 파일 관리, 웹 검색 결과 회수 과정을 통합 조정한다. 모든 작업은 외부 시스템과 격리된 클라우드 샌드박스(Cloud Sandbox) 내부에서 수행되어 실행 환경의 오염을 방지하고 보안성을 확보한다. AI 코딩 어시스턴트를 사용하는 개발자는 아래 터미널 명령어를 통해 Interactions API 스킬을 자신의 환경에 즉시 추가할 수 있다.

bash

npx skills add google-gemini/gemini-skills --skill gemini-interactions-api

.agents/hooks.json을 통한 샌드박스 환경 훅 구현

Managed Agents는 샌드박스 내 도구 호출 전후에 커스텀 스크립트를 실행할 수 있는 환경 훅(Environment Hooks) 기능을 도입했다. 개발자가 환경 내에 `.agents/hooks.json` 파일을 추가하면, 런타임은 에이전트가 도구를 호출하는 시점에 맞춰 정의된 핸들러를 실행한다. 이 기능은 도구 실행 전 단계인 `pre_tool_execution`과 실행 후 단계인 `post_tool_execution` 이벤트를 모두 지원하여 도구 호출의 차단, 린팅(Linting), 감사(Audit)를 수행한다.

훅의 실행 대상은 `matcher` 필드 내 정규 표현식을 통해 정밀하게 제어한다. 개발자는 `|` 기호를 사용하여 여러 개의 도구를 동시에 타겟팅하거나, 별표(`*`)를 입력해 샌드박스 내의 모든 도구 호출에 훅을 적용할 수 있다. 이를 통해 공통 보안 정책을 일괄 적용하는 동시에, 민감한 권한이 필요한 특정 도구에만 별도의 검증 로직을 추가하는 분리 관리 체계를 구축한다.

환경 훅의 상세한 HTTP 정의와 실패 처리 시맨틱은 hooks documentation에서 제공하는 가이드를 통해 설정할 수 있다. 이 메커니즘은 에이전트의 자율적인 도구 사용 권한을 유지하면서도, 개발자가 실행 흐름의 특정 지점에 개입해 결과의 신뢰도를 높이는 제어 장치로 작동한다. 샌드박스 내부에서 직접 스크립트가 실행되므로 외부 시스템으로 데이터를 전송하고 다시 받는 오버헤드가 발생하지 않는다.

모델 선택 옵션과 max_total_tokens 기반 비용 제어

사용자는 `agent_config.model` 설정을 통해 작업의 복잡도와 예산 상황에 맞는 모델을 명시적으로 선택할 수 있다. 높은 추론 능력이 필요한 핵심 로직에는 고성능 모델을 배치하고, 단순 반복 작업에는 Gemini 3.5 Flash-Lite를 지정해 토큰 비용을 최적화한다. 이는 에이전트의 역할에 따라 자원을 차등 배분하여 전체 운영 효율을 높이는 전략적 선택지를 제공한다.

Managed Agents는 스스로 목표를 설정하고 도구를 호출하는 다회차 자율 루프(autonomous loop) 구조로 작동하므로, 예상치 못한 토큰 과소비를 방지하기 위한 제어 장치가 필요하다. Google은 `agent_config` 내에 `max_total_tokens` 설정을 추가하여 입력, 출력, 그리고 모델의 내부 사고(thinking) 토큰을 모두 포함한 전체 소비량을 캡핑(Capping)할 수 있게 했다. 설정된 한도에 도달하면 에이전트의 실행은 안전하게 일시 중단된다.

토큰 한도 도달 시 시스템은 `incomplete` 상태값을 반환하며, 이때 샌드박스의 환경 상태는 그대로 보존된다. 개발자는 `previous_interaction_id`를 사용하여 중단된 지점의 세션 ID를 전달하고, 새로운 토큰 예산을 할당함으로써 작업을 이어서 수행할 수 있다. 이러한 구조는 대규모 작업 시 예산을 분할 투입하여 리스크를 관리하고, 자율 에이전트의 무한 루프나 예산 초과 실행을 물리적으로 차단하는 기준이 된다.

스케줄 트리거 및 Environments API를 통한 자동화

Google은 에이전트, 환경, 프롬프트, cron 스케줄을 하나의 지속성 리소스로 결합한 스케줄 트리거 기능을 제공한다. 이 트리거는 수동 개입 없이 정해진 주기마다 에이전트를 실행시켜 반복적인 업무를 자동화한다. 특히 각 실행 시 동일한 샌드박스를 재사용하도록 설정하면, 이전 실행에서 생성된 파일이나 설치된 패키지가 유지되어 환경 구축 시간을 단축하고 상태 유지형 데이터 파이프라인을 구현할 수 있다.

Environments API는 개발자가 코드 수준에서 샌드박스 세션의 생명주기를 직접 관리할 수 있는 기능을 제공한다. 개발자는 API를 통해 현재 활성화된 샌드박스 목록을 조회하고, 세션의 상태를 검사하며, 불필요한 세션을 즉시 삭제할 수 있다. 네트워크 단절로 인해 제어권을 상실한 경우에도 API로 환경 ID를 복구하여 중단된 작업을 재개함으로써 장기 실행 작업의 안정성을 확보한다.

샌드박스의 기본 TTL(Time To Live)은 7일로 설정되어 있으며, 기간 만료 후에는 환경이 자동으로 소멸한다. 하지만 Environments API의 삭제 기능을 활용하면 작업 완료 즉시 리소스를 회수하여 불필요한 환경 잔존을 방지할 수 있다. 대규모 자동화 공정에서는 API 기반의 직접적인 생명주기 관리를 통해 매 실행마다 최적화된 리소스 상태를 유지하고 인프라 효율을 극대화한다.

실무 적용: 샌드박스 내 결정론적 검증 파이프라인 구축

AI 기반 투자은행 Offdeal은 AI 분석가 Archie가 생성하는 기업 로고 배치 작업에 `post_tool_execution` 훅을 적용해 정밀 검증을 수행한다. 보고서 덱에 포함되는 30개 이상의 로고는 기업 식별의 정확성뿐 아니라 픽셀 단위의 크기, 가로세로 비율, 배경 투명도, 대비 수준 등의 엄격한 품질 기준을 충족해야 한다. 기존의 원격 샌드박스 환경에서는 검증 코드를 실행할 공간이 없어 이러한 세밀한 제어가 불가능했다.

Offdeal은 샌드박스 내부 훅을 통해 Archie가 기업 목록을 작성하는 즉시 후보 로고를 가져와 픽셀 수준의 품질 체크를 수행하는 파이프라인을 구축했다. 이후 Gemini Vision을 통해 로고의 정확성을 최종 확인하고, 검증을 통과한 파일들로만 구성된 매니페스트(파일 목록 명세서)를 생성한다. 최종 결과물 덱에는 이 매니페스트에 승인된 파일만 포함되도록 제한하여 데이터 무결성을 확보했다.

이 사례는 LLM의 확률적 생성 결과물에 대해 픽셀 검사나 데이터 무결성 확인 같은 결정론적 검증이 필수적인 워크플로우에서 중요한 실행 기준을 제시한다. 외부 오케스트레이션 시스템을 추가해 데이터를 주고받는 대신, 샌드박스 내부 훅을 통해 '검증-필터링-출력' 파이프라인을 구축하는 것이 운영 복잡도를 낮추고 결과의 신뢰도를 높이는 가장 구체적인 방법이다. 개발자는 이를 통해 외부 시스템 전송 지연을 없애고 데이터 변형 가능성을 차단한 고신뢰도 에이전트 환경을 구현할 수 있다.