Gemini API에서 도구(Tools) 사용하기

도구는 Gemini 모델의 능력을 확장해서, 모델이 실제 세계에서 동작을 수행하고 실시간 정보에 접근하며 복잡한 계산을 처리할 수 있게 해줘요. 표준 요청-응답 상호작용과 Live API를 통한 실시간 스트리밍 세션 양쪽에서 사용할 수 있어요.

출처: 원문

본문

도구는 모델이 쿼리에 답할 때 사용할 수 있는 특정 기능(예: Google 검색, 코드 실행)이에요. Gemini API는 완전히 관리되는 내장 도구 모음을 제공하며, 함수 호출로 커스텀 도구를 정의할 수도 있어요.

다중 단계·목표 지향 시스템을 만들려면 Agents 개요를 참고하세요.

도구	설명	사용 사례
Google 검색	최신 사건과 웹의 사실에 답을 접지(ground)해서 환각을 줄여요.	최근 사건에 대한 질문, 다양한 출처로 사실 확인
Google Maps	장소를 찾고 길찾기와 풍부한 로컬 컨텍스트를 제공하는 위치 인식 어시스턴트를 만들어요.	다중 정류장 여행 일정 계획, 사용자 기준에 따른 로컬 업체 찾기
코드 실행	모델이 Python 코드를 작성·실행해 수학 문제를 풀거나 데이터를 정확히 처리하게 해요.	복잡한 수학 방정식 풀기, 텍스트 데이터 정밀 처리·분석
URL 컨텍스트	특정 웹 페이지나 문서의 콘텐츠를 읽고 분석하도록 모델을 지시해요.	특정 URL·문서 기반 질문, 여러 웹 페이지에 걸친 정보 검색
컴퓨터 사용 (Preview)	Gemini가 화면을 보고 웹 브라우저 UI와 상호작용하는 동작을 생성하게 해요 (클라이언트 측 실행).	반복 웹 워크플로 자동화, 웹 애플리케이션 UI 테스트
파일 검색	자체 문서를 인덱싱·검색해서 RAG(검색 증강 생성)를 가능하게 해요.	기술 매뉴얼 검색, 독점 데이터에 대한 질의응답

특정 도구와 관련된 비용에 대한 자세한 내용은 가격 페이지를 참고하세요.

도구는 모델이 대화 중에 동작을 요청할 수 있게 해줘요. 흐름은 도구가 내장형(Google이 관리)인지 커스텀(사용자가 관리)인지에 따라 달라져요.

내장 도구(Google 검색, Google Maps, URL 컨텍스트, 파일 검색, 코드 실행)의 경우 전체 프로세스가 단일 API 호출 안에서 일어나요:

커스텀 도구와 컴퓨터 사용의 경우 여러분의 애플리케이션이 실행을 처리해요:

여러분이 함수(도구) 선언과 함께 프롬프트를 보내요.
Gemini가 특정 함수를 호출하라는 구조화 JSON을 보내줄 수 있어요 (예: {"name": "get_order_status", "args": {"order_id": "123"}}). 항상 고유한 id가 포함돼요.
여러분이 애플리케이션이나 환경에서 함수를 실행해요.
여러분이 함수 호출과 동일한 id를 가진 함수 결과를 Gemini에 다시 보내요.
Gemini가 결과를 사용해 최종 응답이나 또 다른 도구 호출을 생성해요.

Preview: bash와 커스텀 도구를 섞어 빌드하는 경우, Gemini 3.1 Pro Preview는 gemini-3.1-pro-preview-customtools라는 별도 엔드포인트를 API로 제공해요.

자세한 내용은 함수 호출 가이드에서 확인하세요.

Preview: Gemini 3 시리즈 모델은 한 턴 안에 내장 도구와 커스텀 도구를 결합하는 옵션을 지원해요.

내장 도구와 커스텀 도구(함수 호출)를 결합하는 요청에서 모델은 도구 컨텍스트 순환을 사용해 서로 다른 환경 간 실행을 조정해요:

여러분이 프롬프트를 보내고 활성화할 내장 도구와 커스텀 함수를 선언하며, 결합 지원을 켜는 플래그를 설정해요.
Gemini가 내장 도구를 실행하고, 클라이언트 측 함수 호출이 생성되면 사용자에게 양보해요 (무엇이 먼저 실행될지는 프롬프트와 모델 결정에 따라 달라져요). 다음을 포함한 응답을 보내줘요:
1. 도구 호출 확인
2. 도구 응답 결과 (모델이 병렬 함수 호출을 생성했다면 JSON 다음에 올 수 있어요)
3. 함수를 호출하기 위한 구조화 JSON
4. 컨텍스트를 보존하는 암호화된 생각 서명(thought signature)
여러분이 애플리케이션이나 환경에서 함수를 실행해요.
여러분이 Gemini 응답의 모든 부분과 함수 호출 결과를 반환해요.
Gemini가 결합된 모든 컨텍스트로 최종 응답을 생성해요.

내장·커스텀 도구 결합 지원을 켜는 방법과 컨텍스트 순환 예시는 도구 결합 가이드를 참고하세요.

Gemini는 구조화 출력을 생성하는 두 가지 방법을 제공해요. 모델이 여러분의 도구나 데이터 시스템에 연결해 중간 단계를 수행해야 한다면 함수 호출을, 커스텀 UI 렌더링처럼 모델의 최종 응답이 특정 스키마를 엄격히 따라야 한다면 구조화 출력을 사용하세요.

Preview: 이 기능은 Gemini 3 시리즈 모델에서만 사용할 수 있어요.

구조화 출력을 내장 도구와 결합해서, 외부 데이터나 계산에 접지된 모델 응답도 엄격한 스키마를 따르도록 보장할 수 있어요.