Gemini 관리형 에이전트, 훅으로 도구 호출 막고 무료 티어까지 개방

Google DeepMind가 2026년 7월 28일 Gemini API의 관리형 에이전트(Managed Agents)에 환경 훅을 추가했습니다. 훅은 에이전트가 도구를 호출하기 직전과 직후에 개발자가 넣어둔 스크립트를 실행하는 장치입니다. 스크립트가 거부를 반환하면 그 도구 호출은 실행되지 않습니다. Google DeepMind의 Philipp Schmid와 Mariano Cocirio가 공식 개발자 블로그에 발표를 올렸습니다.

관리형 에이전트는 API를 한 번 호출하면 Google이 호스팅하는 격리된 Linux 샌드박스가 뜨고, 그 안에서 에이전트가 코드를 실행하고 패키지를 설치하고 파일을 만들고 웹을 뒤지는 서비스입니다. 2026년 5월 19일 프리뷰로 나왔고, 에이전트 동작은 AGENTS.md와 SKILL.md 마크다운 파일로 바꿉니다. 초기 테스터로는 Ramp, ResembleAI, Klipy가 공개됐습니다.

편한 대신 불편한 지점이 하나 있었습니다. 샌드박스가 남의 서버에 있으니, 에이전트가 만든 결과물을 검사할 내 코드를 그 안에 넣을 방법이 없었습니다.

Google은 이 빈 곳을 두 달에 걸쳐 순서대로 메웠습니다. 7월 7일 릴리스가 채운 쪽은 실행 시간과 연결 대상입니다. background: true를 넘기면 API가 곧바로 상호작용 ID를 돌려주고 긴 작업은 서버에서 계속 돕니다. HTTP 연결을 붙잡고 기다릴 필요가 없어졌습니다. 원격 MCP 서버 연결과 커스텀 함수 호출도 이때 들어갔습니다. 7월 28일 릴리스가 채운 쪽은 통제 장치입니다.

훅은 남의 서버 안에서 돈다

검증 스크립트가 내 노트북이 아니라 Google 샌드박스 안에서 돕니다. 훅이 어디서 실행되느냐가 이번 발표에서 달라진 부분입니다.

AI 투자은행 OffDeal의 창업자 겸 CTO Alston Lin이 발표문에서 이 공백을 직접 설명했습니다. OffDeal의 분석 에이전트 Archie는 은행원이 쓸 자료를 만들면서 기업 로고를 30개 넘게 배치하는데, 로고마다 회사가 맞는지, 크기와 비율이 적절한지, 배경이 투명한지, 흰 슬라이드 위에서 대비가 충분한지 확인해야 합니다.

에이전트 훅이 나오기 전에는 Gemini 관리형 에이전트에서 이걸 할 수 없었습니다. 샌드박스가 원격이라 우리 검증 코드가 돌아갈 자리가 없었기 때문입니다.

지금은 Archie가 기업 목록을 쓰는 순간 post_tool_execution 훅이 로고 검증 파이프라인을 샌드박스 안에서 돌립니다. 후보를 모으고 픽셀 단위 품질 검사를 건 뒤 Gemini 비전으로 로고를 확인합니다. 통과한 파일만 매니페스트에 올라가고, 매니페스트에 없는 이미지는 자료에 들어가지 못합니다.

설정은 환경에 .agents/hooks.json을 넣는 방식입니다. matcher는 정규표현식을 받아 |로 여러 도구를 묶거나 *로 전부 잡습니다.

{
  "security-gate": {
    "pre_tool_execution": [
      {
        "matcher": "code_execution|write_file",
        "hooks": [
          { "type": "command", "command": "python3 /.agents/hooks-scripts/gate.py", "timeout": 10 }
        ]
      }
    ]
  }
}

이 설정에서 gate.py는 에이전트가 코드를 실행하거나 파일을 쓰기 전에 매번 호출됩니다. 스크립트가 {"decision": "deny", "reason": "..."}를 반환하면 런타임이 그 도구 호출을 건너뛰고 거부 사유를 모델 컨텍스트에 넣습니다. 에이전트는 자기가 왜 막혔는지 읽고 다른 방법을 찾습니다. 핸들러는 샌드박스 안 스크립트를 실행하는 command 외에 외부 엔드포인트로 POST하는 http 타입도 지원합니다.

무료 티어와 토큰 상한

두 번째 변화는 진입 비용입니다. 관리형 에이전트를 결제가 활성화되지 않은 프로젝트의 API 키로 쓸 수 있게 됐습니다. 공식 문서 기준으로 과금은 Gemini 모델 토큰과 도구 사용량에 붙고, 프리뷰 기간에는 환경 컴퓨트를 청구하지 않습니다.

무료로 열어준 대신 토큰 소비를 막는 일은 개발자 몫으로 남겼습니다. 문서는 상호작용 1회가 보통 10만에서 300만 토큰을 쓴다고 밝힙니다. 에이전트가 여러 턴을 자율로 도는 구조라 실수 한 번이 비쌉니다. agent_config.max_total_tokens가 입력과 출력과 사고 토큰의 합계에 상한을 겁니다.

const interaction = await client.interactions.create({
  agent: 'antigravity-preview-05-2026',
  input: 'Audit all modules in this repo and generate a migration report.',
  agent_config: {
    type: 'antigravity',
    max_total_tokens: 10000,
  },
  environment: 'remote',
})

상한에 닿으면 실행이 그 자리에서 멈추고 상호작용이 status: "incomplete"를 반환합니다. 환경 상태는 그대로 남아서 previous_interaction_id에 새 예산을 붙이면 멈춘 곳부터 이어집니다. 예산이 떨어져도 처음부터 다시 돌릴 필요가 없으니 재시도 비용이 줄어듭니다.

스케줄 트리거는 에이전트와 환경, 프롬프트, cron 일정을 하나의 영속 리소스로 묶습니다. 매 실행이 같은 샌드박스를 재사용하므로 파일이 남습니다. Environments API로는 샌드박스 세션을 코드에서 나열하고 조회하고 삭제할 수 있습니다. 연결이 끊긴 뒤 환경 ID를 되찾거나, 7일 TTL을 기다리지 않고 파이프라인 종료 시점에 정리하는 용도입니다.

기본 모델도 바뀌었습니다. antigravity-preview-05-2026 에이전트가 이제 gemini-3.6-flash로 돕니다. 코드를 고칠 필요는 없고 다음 상호작용부터 자동 적용됩니다. 비용을 더 낮추려면 agent_config.model에 gemini-3.5-flash-lite를 지정합니다.

샌드박스를 누가 들고 있는가

세 회사의 에이전트 SDK를 가르는 기준은 모델 점수가 아니라 실행 환경을 누가 운영하느냐입니다. Google은 샌드박스와 정책 스크립트 실행을 모두 자기 API 안에 넣었습니다. OpenAI Agents SDK는 샌드박스 클라이언트 9종을 두고 개발자가 고르게 합니다. Blaxel, Cloudflare, Daytona, Docker, E2B, Modal, Runloop, Vercel, 로컬 Unix가 목록에 있습니다. Anthropic의 Claude Agent SDK는 훅 이벤트를 촘촘하게 제공하지만 내 프로세스 안에서 돌아가므로 격리 환경은 직접 준비해야 합니다.

Google 쪽을 고르면 Gemini API에 묶입니다. 샌드박스와 훅 런타임, 스케줄러가 전부 Google 안에 있어서 다른 모델로 갈아탈 때 옮길 것이 많습니다. 대신 결제 정보 없이 API 키 하나로 정책과 예산과 일정이 붙은 클라우드 에이전트를 돌려볼 수 있습니다. ADK Go 2.0이 사람 승인 단계를 그래프 워크플로에 넣었을 때는 승인 로직을 개발자가 자기 서버에서 관리했지만, 이번 훅은 실행 자체가 Google 안에서 끝납니다.

원격 MCP 연결은 7월 7일에 이미 들어갔습니다. mcp_server 도구로 사설 데이터베이스나 사내 API를 샌드박스에 붙일 수 있고, 여기에 훅을 겹치면 외부 도구 호출도 같은 정책 스크립트로 걸러집니다. MCP 무상태 사양이 7월 28일 확정된 것과 시점이 겹치는 만큼, 원격 MCP 서버를 운영 중이라면 두 변경을 같이 점검하는 편이 낫습니다.

프리뷰가 아직 못 하는 것

공식 문서에 적힌 프리뷰 제약은 여섯 가지입니다.

• base_agent로 쓸 수 있는 것은 antigravity-preview-05-2026 하나뿐입니다.
• 에이전트 버전 관리와 롤백이 없습니다. 정의를 바꾸면 이전 상태로 되돌릴 공식 경로가 없습니다.
• 서브에이전트 위임이 없습니다. 작업을 쪼개 병렬로 돌리려면 호출 측에서 직접 오케스트레이션해야 합니다.
• 프로젝트당 관리형 에이전트는 최대 1,000개입니다.
• 환경은 비활성 7일 뒤 영구 삭제되고, VM은 짧은 비활성 뒤 종료됩니다.
• 무료 티어에는 별도의 요청 한도와 사용량 쿼터가 붙습니다.

훅으로 막을 수 있는 범위도 도구 호출 단위까지입니다. 샌드박스 안에서 이미 실행된 코드가 그다음에 무엇을 하는지까지 훅이 감시하지는 않습니다. 자격 증명을 샌드박스에 넣어야 한다면 7월 7일에 추가된 네트워크 자격 증명 갱신 경로로 토큰 수명을 짧게 가져갈 수 있습니다. environment_id를 그대로 두고 네트워크 설정만 새로 넘기면 파일시스템과 설치된 패키지는 유지된 채 자격 증명만 교체됩니다.