Gemini API 에이전트(Agents) 개요

Gemini API 에이전트(Agents) 개요

Gemini API의 관리형 에이전트(Managed agents)를 쓰면 설정 가능한 에이전트 하네스를 얻을 수 있어요. API 호출 한 번만으로 에이전트가 추론하고, 코드를 실행하고, 파일을 관리하고, 웹을 자율적으로 탐색하는 Linux 샌드박스가 준비됩니다.

출처: 문서

본문

  • Quickstart: 첫 에이전트 호출을 만들고, 응답을 스트리밍하고, 커스텀 에이전트를 구축해 보세요.
  • Antigravity Agent: 기본 에이전트의 기능, 도구, 멀티모달 입력, 가격을 확인하세요.
  • Agents in AI Studio: 코드를 작성하지 않고 에이전트를 프로토타이핑할 수 있는 시각적 플레이그라운드예요.

사용 가능한 관리형 에이전트

  • Antigravity agent: Gemini 3.8 Flash로 만들어진 범용 관리형 에이전트예요. Google이 호스팅하는 안전한 Linux 샌드박스 안에서 코드를 실행하고, 파일을 관리하고, 웹을 검색해요. agent_config를 써서 기본 모델(Gemini 3.7 Flash, Gemini 3.6 Flash, Gemini 3.5 Flash 등)을 설정할 수 있고, 직접 만든 지침·스킬·데이터로 확장해 커스텀 에이전트를 만들 수도 있어요.

  • Deep Research: 시장 분석, 실사(due diligence), 문헌 리뷰 같은 용례를 위해 다단계 연구 작업을 계획하고, 실행하고, 종합하는 자율 연구 에이전트예요.

보안과 모범 사례

참고: 관리형 에이전트는 Public Preview 상태예요. 중요한 워크플로에 의존하기 전에 에이전트의 행동과 출력을 검토하세요.

모든 에이전트는 OS 수준에서 격리된 샌드박스 환경에서 실행돼요. 샌드박스는 기본적으로 제한 없는 아웃바운드 네트워크 접근을 허용해요. allowlist를 사용하면 네트워크 접근을 제한하거나 완전히 끌 수 있어요.

네트워크 접근

기본적으로 환경은 제한 없는 아웃바운드 네트워크 접근을 허용해요. network allowlist를 사용하면 아웃바운드 트래픽을 특정 도메인이나 와일드카드 패턴으로 제한할 수 있어요. 설정 방법은 AI Studio의 Network Allow List 문서나 API의 Network rules 문서를 참고하세요.

외부 도구와 API

에이전트를 확장하기 위해 외부 도구와 API를 연결할 수 있어요. 신뢰할 수 있는 출처의 도구만 사용하고, 권한 범위를 필요한 최소한으로 제한하세요. 비밀 정보는 관리형 자격증명(managed credentials)으로 저장하고 ID로 참조하면, egress 프록시가 요청 시점에 주입해 주므로 샌드박스 안에 노출되지 않아요. 에이전트는 접근 권한이 있는 어떤 자격증명이든 사용할 수 있으므로, 전체 범위를 기꺼이 부여할 수 있는 자격증명만 제공하세요.

  • 최소 권한(least-privilege) 서비스 계정이나 API 키를 사용하세요.
  • 장기 키보다는 단기 만료 토큰을 선호하세요.
  • 전체 범위를 기꺼이 부여할 수 있는 자격증명만 제공하세요.
  • 자격증명을 정기적으로 교체하세요.

자격증명 종류와 관리 작업은 Credentials 문서를 참고하세요. allowlist 규칙에 헤더를 인라인으로 설정할 수도 있는데, Network configuration에서 확인해 보세요.

사람의 감독

생성된 코드, 데이터 변환, 설정 변경 등을 배포하기 전에 항상 출력을 검증하세요. 특히 데이터를 수정하거나 외부 시스템과 상호작용하는 작업은 더 신중해야 해요.

가격

관리형 에이전트는 Gemini 모델 토큰과 도구 사용량에 따라 종량제(pay-as-you-go) 모델을 사용해요. 단일 상호작용이 여러 추론 루프를 유발할 수 있고, 보통 10만~300만 토큰을 소비해요. 환경 컴퓨팅은 프리뷰 기간 동안 청구되지 않아요. 작업별 비용 분해는 예상 비용 문서를 참고하세요. 관리형 에이전트는 무료 요금 한도와 사용량 쿼터가 있는 무료 티어에서도 사용할 수 있어요.

제한

제한 설명
환경 수명(Environment Lifetime) 비활성 상태로 7일이 지나면 환경은 영구적으로 삭제돼요.
VM 스핀다운(VM Spin-down) 리소스를 아끼기 위해 짧은 비활성 기간 후 VM이 종료돼요. 다음 요청이 (콜드 스타트와 함께) 상태를 복원해요.
사전 설치 소프트웨어(Pre-installed Software) Python 3.12와 Node.js 22가 있는 Ubuntu 기반 환경이에요. 환경의 기본 이미지에 대한 자세한 내용은 사전 설치 소프트웨어를 참고하세요.
최대 에이전트 수(Max agents) 관리형 에이전트는 최대 1,000개까지 가질 수 있어요.

에이전트 프레임워크

Gemini로 에이전트를 만들 때는 다음 프레임워크와 SDK를 함께 쓸 수도 있어요.

  • LangChain / LangGraph: 그래프 구조를 사용해 상태를 가진 복잡한 애플리케이션 흐름과 멀티 에이전트 시스템을 만드세요.
  • LlamaIndex: Gemini 에이전트를 프라이빗 데이터에 연결해 RAG 강화 워크플로를 구성하세요.
  • CrewAI: 역할을 맡은 협업형 자율 AI 에이전트를 오케스트레이션하세요.
  • Vercel AI SDK: JavaScript/TypeScript로 AI 기반 사용자 인터페이스와 에이전트를 만드세요.
  • Google ADK: 상호운용 가능한 AI 에이전트를 구축·오케스트레이션하는 오픈소스 프레임워크예요.
  • Antigravity SDK: Google Antigravity를 구동하는 것과 같은 도구, 에이전트 루프, 컨텍스트 관리로 자율 AI 에이전트를 구축하세요. Python으로 프로그래밍할 수 있어요.

더 알아보기 (Learn more)