Gemini API Managed Agents: 3.6 Flash, hooks, and more

🖼️ 인포그래픽

Gemini API Managed Agents: 3.6 Flash, hooks, and more 내용을 설명하는 본문 이미지

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Gemini API의 Managed Agents는 Gemini 3.6 Flash 기본 적용과 모델 선택, 샌드박스 훅, 무료 등급, 토큰 예산 제한, 예약 실행 및 환경 관리 기능을 추가해 자율 작업의 통제성과 자동화를 강화했다.

📌 핵심 요약

Gemini Interactions API의 Managed Agents는 단일 API 호출로 추론, 코드 실행, 패키지 설치, 파일 관리, 웹 검색을 격리된 클라우드 샌드박스에서 조율한다.
antigravity-preview-05-2026 에이전트의 기본 모델이 Gemini 3.6 Flash로 변경됐으며, 기존 코드를 수정하지 않아도 다음 상호작용부터 자동으로 적용된다.
환경 훅을 이용하면 샌드박스의 각 도구 호출 전후에 사용자 정의 스크립트를 실행해 호출을 차단하거나 코드 스타일을 검사하고 실행 결과를 감사할 수 있다.
무료 등급 프로젝트에서도 Managed Agents를 사용할 수 있으며, max_total_tokens로 전체 토큰 소비량을 제한하고 중단된 작업을 보존된 환경에서 이어갈 수 있다.
예약 트리거는 에이전트 작업을 크론 일정에 따라 반복 실행하고 동일한 샌드박스를 재사용하며, Environments API는 샌드박스 세션의 조회·점검·삭제를 지원한다.

🧩 주요 포인트

기본 모델 상향과 명시적 모델 선택 지원 → 성능·비용·지연시간 요구에 맞춰 에이전트 실행 모델을 조정할 수 있다.
도구 실행 전후 훅과 정규식 매칭 제공 → 샌드박스 내부에서 보안 차단, 자동 검사, 외부 감사 절차를 실행 흐름에 직접 결합할 수 있다.
무료 접근, 토큰 상한, 예약 트리거, 환경 관리 추가 → 실험부터 비용이 통제된 반복 작업 운영까지 하나의 관리형 실행 체계로 다룰 수 있다.

🧠 상세 정리

1. Managed Agents의 역할과 이번 업데이트

Gemini API의 Managed Agents는 Gemini Interactions API를 통해 에이전트 작업을 격리된 클라우드 샌드박스에서 실행한다. 한 번의 API 호출로 추론뿐 아니라 코드 실행, 패키지 설치, 파일 관리, 웹 검색까지 함께 조율하며, 이전에 제공된 백그라운드 작업과 원격 MCP 서버 통합을 기반으로 기능을 확장했다. 이번 업데이트의 주요 항목은 환경 훅, 실행 모델 선택, 무료 등급 접근, 토큰 예산 제어, 예약 트리거, 샌드박스 환경 관리다. TypeScript와 JavaScript에서는 @google/genai SDK로 기능을 사용할 수 있고, 코딩 보조 도구에는 명령어를 통해 Interactions API 스킬을 추가할 수 있다.

2. Gemini 3.6 Flash 기본 적용과 모델 선택

antigravity-preview-05-2026 에이전트는 이제 Gemini 3.6 Flash를 기본 모델로 사용하며, 사용자가 코드를 변경하지 않아도 다음 상호작용부터 새 기본값이 자동 적용된다. Gemini 3.6 Flash는 추론, 코딩, 도구 사용 사이의 균형을 목표로 제시된 모델이다. 특정 요구가 있다면 상호작용이나 관리형 에이전트를 생성할 때 agent_config.model을 전달해 모델을 명시적으로 고정할 수 있다. 지원 선택지에는 일반 에이전트 작업용 이전 세대인 Gemini 3.5 Flash와, 같은 3.5 계열에서 지연시간과 비용이 가장 낮은 Gemini 3.5 Flash-Lite가 포함된다. 따라서 기본 모델을 그대로 사용하거나 비용과 응답 속도에 맞춰 다른 지원 모델을 지정할 수 있다.

3. 도구 호출을 통제하는 환경 훅

환경 훅은 에이전트가 샌드박스 안에서 도구를 호출하기 직전이나 직후에 사용자 정의 스크립트를 실행하는 기능이다. 환경에 .agents/hooks.json 파일을 추가하고 pre_tool_execution 또는 post_tool_execution 이벤트에 처리기를 등록하면 된다. matcher 필드는 정규식을 지원하므로 여러 도구를 세로줄로 묶어 지정하거나 별표를 사용해 모든 도구 호출을 대상으로 삼을 수 있다. 예시의 security-gate는 code_execution과 write_file 실행 전에 gate.py를 호출하며, 스크립트가 거부 결정과 사유를 반환하면 해당 도구 호출을 생략하고 사유를 모델 문맥에 전달한다. auto-format은 모든 도구 실행 후 auto_lint.py를 호출해 코드 스타일 검사를 적용하며, 각 명령형 훅에는 실행 제한시간도 설정할 수 있다.

4. 외부 연동과 실제 검증 파이프라인

훅 처리기는 샌드박스 명령을 실행하는 command 유형뿐 아니라 외부 엔드포인트로 직접 POST 요청을 보내는 http 유형도 지원한다. 이를 통해 도구 호출 전에는 보안 정책을 검사하고, 호출 후에는 결과물 검증이나 감사 절차를 자동으로 연결할 수 있다. 소개된 OffDeal 사례에서는 post_tool_execution 훅이 회사 목록 작성 직후 원격 샌드박스 안의 이미지 검증 파이프라인을 시작한다. 이 파이프라인은 로고 후보를 가져와 크기, 종횡비, 회사명 포함 여부, 투명 배경, 흰색 슬라이드에서의 대비 같은 품질 조건을 검사하고 Gemini 비전으로 각 로고를 확인한다. 최종적으로 승인된 파일 목록을 게시해 프레젠테이션에는 검증을 통과한 이미지만 사용되도록 구성했다.

5. 무료 등급과 토큰 예산 통제

Managed Agents는 활성 결제가 없는 프로젝트의 API 키를 사용하는 무료 등급 프로젝트에도 개방됐다. 개발자는 이 경로를 통해 관리형 에이전트 워크플로를 실험할 수 있다. 다중 단계의 자율 실행은 복잡한 작업에서 많은 토큰을 사용할 수 있으므로, agent_config의 max_total_tokens로 입력·출력·사고 토큰을 합산한 전체 소비량의 상한을 지정할 수 있다. 설정된 한도에 도달하면 실행은 안전하게 일시 정지되고 상호작용 상태는 incomplete로 반환된다. 샌드박스 환경 상태는 그대로 보존되므로, 새로운 예산과 previous_interaction_id를 전달하면 중단된 지점에서 작업을 계속할 수 있다.

6. 예약 실행과 샌드박스 수명주기 관리

예약 트리거는 에이전트, 실행 환경, 프롬프트, 크론 일정을 하나의 지속적인 리소스로 묶어 수동 호출 없이 반복 작업을 실행한다. 각 실행은 같은 샌드박스를 재사용하므로 이전 실행에서 생성하거나 수정한 파일이 후속 실행에도 유지된다. Environments API는 코드에서 샌드박스 세션을 나열하고 세부 상태를 확인하거나 삭제할 수 있게 한다. 연결이 끊어진 뒤 환경 식별자를 다시 찾을 수 있으며, 파이프라인이 끝나면 기본 7일 만료 시간을 기다리지 않고 사용한 샌드박스를 정리할 수 있다. 이러한 기능은 관리형 에이전트를 별도의 외부 오케스트레이션 없이 비용이 통제되고 일정에 따라 실행되는 자율 작업자로 운영하는 데 필요한 실행·재개·정리 수단을 제공한다.

🧾 핵심 주장 / 시사점

관리 대상이 모델 선택에 그치지 않고 도구 호출 정책, 전체 토큰 상한, 실행 일정, 샌드박스 수명주기까지 확장돼 에이전트 운영의 주요 제어 지점을 API와 환경 설정 안에서 다룰 수 있게 됐다.
pre_tool_execution의 사전 차단과 post_tool_execution의 사후 검사 구조는 위험한 실행을 예방하는 절차와 결과물의 품질을 검증하는 절차를 분리해 적용할 수 있게 한다.
토큰 한도 도달 시 환경을 폐기하지 않고 incomplete 상태와 보존된 샌드박스를 반환하는 방식은 비용 상한을 유지하면서 previous_interaction_id로 장기 작업을 이어갈 수 있도록 설계됐다.

✅ 액션 아이템

antigravity-preview-05-2026 기본 모델 Gemini 3.6 Flash 자동 적용이 성능·비용·지연시간 목표에 맞는지 비교한다.
샌드박스 도구 호출 전후 환경 훅으로 호출 차단·코드 스타일 검사·결과 감사 범위를 정의한다.
무료 등급 Managed Agents 사용 시 max_total_tokens 상한과 예약 트리거의 동일 샌드박스 재사용 기준을 정한다.