Gemini API 관리형 에이전트: 3.6 Flash, 후크 및 추가 기능

Gemini API 의 관리형 에이전트가 이제 기본적으로 Gemini 3.6 Flash 를 사용합니다. 새로운 환경 훅을 사용하면 샌드박스 내에서 도구 호출을 차단, 린트 또는 감사할 수 있습니다. 또한 예산 제어, 예약 트리거 및 무료 티어 액세스가 추가되었습니다.

Gemini API 의 관리형 에이전트에 환경 훅, 모델 선택 및 무료 티어 액세스 기능이 추가되었습니다. 이러한 기능은 백그라운드 작업 및 원격 MCP 서버 통합을 도입한 이전 릴리스를 기반으로 합니다.

Gemini Interactions API의 관리형 에이전트를 사용하면 단일 API 호출로 격리된 클라우드 샌드박스 내에서 추론, 코드 실행, 패키지 설치, 파일 관리 및 웹 검색을 조정합니다.

AI 코딩 어시스턴트를 사용 중이라면 터미널에 다음을 입력하여 Interactions API 스킬에 액세스할 수 있습니다: npx skills add google-gemini/gemini-skills --skill gemini-interactions-api

아래는 @google/genai TypeScript/JavaScript SDK 를 사용한 예제입니다. Python 또는 cURL 의 경우 Antigravity 에이전트 문서를 확인하세요.

1npm install @google/genai

Gemini 3.6 Flash 가 이제 기본 모델입니다

antigravity-preview-05-2026 에이전트는 이제 기본적으로 Gemini 3.6 Flash를 실행합니다. 코드 변경이 필요 없습니다. 다음 상호작용부터 자동으로 적용됩니다.

또한 상호작용 또는 관리형 에이전트를 생성할 때 agent_config.model을 전달하여 명시적으로 모델을 선택할 수 있습니다. 비용 절감을 위해 Gemini 3.5 Flash-Lite 를 사용하거나 원하는 모델로 고정할 수 있습니다.

1import { GoogleGenAI } from "@google/genai";
2
3const client = new GoogleGenAI({});
4
5const interaction = await client.interactions.create({
6  agent: "antigravity-preview-05-2026",
7  input: "Audit all dependencies in package.json, upgrade outdated packages, and verify the build by running npm test.",
8  environment: "remote",
9  agent_config: {
10    type: "antigravity",
11    model: "gemini-3.5-flash-lite",
12  },
13});
14
15console.log(interaction.output_text);

지원되는 모델은 다음과 같습니다:

• Gemini 3.6 Flash (gemini-3.6-flash, 기본값): 추론, 코딩 및 도구 사용에 최적화된 균형 잡힌 모델입니다.
• Gemini 3.5 Flash (gemini-3.5-flash): 일반 에이전트 워크플로를 위한 이전 세대 모델입니다.
• Gemini 3.5 Flash-Lite (gemini-3.5-flash-lite): Gemini 3.5 제품군 중 가장 낮은 지연 시간과 비용을 제공합니다.

환경 훅: 샌드박스 내에서 도구 호출 차단, 린트 및 감사

환경 훅을 사용하면 에이전트가 샌드박스 내에서 수행하는 모든 도구 호출 전후에 사용자 정의 스크립트를 실행할 수 있습니다. 환경에 .agents/hooks.json 파일을 추가하면 런타임이 pre_tool_execution 또는 post_tool_execution 이벤트에서 핸들러를 실행합니다.

1{
2  "security-gate": {
3    "pre_tool_execution": [
4      {
5        "matcher": "code_execution|write_file",
6        "hooks": [
7          {
8            "type": "command",
9            "command": "python3 /.agents/hooks-scripts/gate.py",
10            "timeout": 10
11          }
12        ]
13      }
14    ]
15  },
16  "auto-format": {
17    "post_tool_execution": [
18      {
19        "matcher": "*",
20        "hooks": [
21          {
22            "type": "command",
23            "command": "python3 /.agents/hooks-scripts/auto_lint.py",
24            "timeout": 15
25          }
26        ]
27      }
28    ]
29  }
30}

이 구성에서:

• security-gate 그룹은 모든 code_execution 또는 write_file 호출 전에 gate.py를 실행합니다. 스크립트가 {"decision": "deny", "reason": "..."}을 반환하면 도구 호출을 건너뛰고 거부 사유가 모델의 컨텍스트로 전달됩니다.
• auto-format 그룹은 모든 도구 실행이 완료된 후 auto_lint.py를 실행하여 코드 스타일을 적용합니다.
• 훅은 외부 엔드포인트로 직접 POST 하는 http 유형 핸들러도 지원합니다.

전체 HTTP 훅 정의 및 오류 처리 의미 체계는 훅 문서를 참조하세요.

이미 많은 팀에서 훅을 사용하여 프로덕션 수준의 검증 파이프라인을 구축하고 있습니다. 예를 들어, AI 기반 투자 은행 OffDeal 은 post_tool_execution 훅을 사용하여 원격 샌드박스 내에서 자동화된 이미지 검증을 실행합니다.

OffDeal 은 AI 기반 투자 은행이며, Archie 는 당사 은행가들이 매일 사용하는 AI 분석가입니다. 은행가가 사용할 수 있는 덱을 위한 필수 요구 사항은 회사 로고입니다: 바이어 테이블, 스폰서 열, 툼스톤 그리드 등 단일 덱에 30 개 이상의 로고가 있는 경우가 많으며, 모든 로고는 올바른 회사, 적절한 크기와 종횡비를 가지고, 이름을 포함하고, 배경이 투명해야 하며, 흰색 슬라이드에 배치했을 때 대비가 높아야 합니다.

에이전트 훅 이전에는 Gemini 의 관리형 에이전트에서 이 작업을 수행할 수 없었습니다. 샌드박스가 원격에 있기 때문에 검증 코드를 실행할 곳이 없었습니다. 훅을 사용하면 Archie 가 회사 목록을 작성하는 즉시 post_tool_execution 훅이 샌드박스 내에서 파이프라인을 트리거하여 후보를 가져오고, 픽셀 수준의 품질 검사를 적용하고, Gemini 비전으로 각 로고를 확인한 다음, 덱에 허용되는 유일한 이미지인 승인된 파일 매니페스트를 게시합니다.

— Alston Lin, OffDeal 창립자 겸 CTO

비용 제어 및 자동화 기능

무료 티어 이용 가능

이제 무료 티어 프로젝트에서 관리형 에이전트를 사용할 수 있습니다. 개발자는 활성 청구가 없는 프로젝트의 API 키를 사용하여 에이전트 워크플로를 실험해 볼 수 있습니다.

예산 제어

관리형 에이전트는 다중 턴 자율 루프를 실행하기 때문에 복잡한 작업은 상당한 토큰 예산을 소비할 수 있습니다. 실행이 통제 불능 상태가 되는 것을 방지하기 위해 agent_config 내에 max_total_tokens를 전달하여 총 소비량(입력 + 출력 + 사고)을 제한할 수 있습니다.

에이전트가 한도에 도달하면 실행이 안전하게 일시 중지되고 상호작용은 status: "incomplete"를 반환합니다. 환경 상태는 보존되므로 새 예산과 함께 previous_interaction_id를 전달하여 중단된 지점에서 계속할 수 있습니다.

1const interaction = await client.interactions.create({
2  agent: "antigravity-preview-05-2026",
3  input: "Audit all modules in this repo and generate a migration report.",
4  agent_config: {
5    type: "antigravity",
6    max_total_tokens: 10000,
7  },
8  environment: "remote",
9});

트리거를 사용한 예약 실행

예약 트리거를 사용하여 반복적인 에이전트 작업을 자동화하세요. 트리거는 에이전트, 환경, 프롬프트 및 cron 일정을 수동 개입 없이 실행되는 지속적인 리소스에 바인딩합니다. 각 실행은 동일한 샌드박스를 재사용하므로 파일이 실행 간에 유지됩니다.

Environments API

Environments API를 사용하면 코드에서 샌드박스 세션을 나열, 검사 및 삭제할 수 있습니다. 연결이 끊긴 후 환경 ID를 복구하거나, 7 일 TTL 을 기다릴 필요 없이 파이프라인이 완료되면 샌드박스를 정리할 수 있습니다.

관리형 에이전트 시작하기

이러한 업데이트를 통해 관리형 에이전트는 예산을 초과하거나 외부 오케스트레이션이 필요 없이 실제 개발 환경 내에서 자율적으로 작동하는 비용 제어 및 예약된 워커로 전환됩니다.

Gemini Interactions API 개요 및 관리형 에이전트 빠른 시작을 확인하여 사용자 정의 에이전트 정의, 환경 구성, 네트워크 규칙 및 고급 스트리밍 패턴을 살펴보세요.