본문으로 건너뛰기
블로그로 돌아가기
AI 도구

제미나이 API 툴 검색 프리뷰: 토큰 아끼는 조건과 설정법

제미나이 API 툴 검색이 2026년 11월 19일 Interactions API에 프리뷰로 추가됐다. defer_loading 설정, 도구 200개와 10개에서 입력 토큰이 줄고 느는 계산, 400 오류, 클로드·OpenAI 비교를 정리했다.

6분 소요AI 도구
제미나이 API 툴 검색Gemini API tool retrievaldefer_loading제미나이 Interactions APIAI 에이전트MCP
제미나이 API 툴 검색 프리뷰: 토큰 아끼는 조건과 설정법

제미나이 API 툴 검색 프리뷰, 도구가 많은 앱만 토큰이 줄어든다

제미나이 API의 툴 검색(tool retrieval)은 도구 정의를 매 요청에 전부 싣지 않고, 모델이 필요할 때 검색해 불러오게 하는 기능이다. 구글은 2026년 11월 19일 변경 기록에서 Interactions API에 프리뷰로 추가됐다고 밝혔다. 도구가 수십 개 이상이고 요청마다 몇 개만 쓰는 앱은 입력 토큰이 크게 줄 수 있다. 도구가 10개쯤이고 대화가 긴 앱은 오히려 늘 수 있어서, 켜기 전에 계산부터 해 봐야 한다.

2026년 11월 19일, 제미나이 Interactions API에 도구 정의를 필요할 때만 불러오는 툴 검색이 프리뷰로 들어왔다.

추가 요금은 없고 모델의 기본 입력·출력 요금을 따르며, 구글 문서의 예시에서 도구 200개 앱은 입력 토큰이 약 164,000에서 23,650으로 줄지만 도구 10개에 긴 대화 앱은 68,000에서 92,830으로 는다.

generateContent에서는 쓸 수 없고 v1beta Interactions API 전용이며, 지원 모델은 문서 기준 gemini-4-hydrogen·gemini-4-argon·gemini-3.8-flash·gemini-3.6-flash다.

제미나이 API 툴 검색 프리뷰를 나타내는 종이 공구 카드와 돋보기 그림

정적 로딩, 서버 검색, 클라이언트 검색 중 무엇을 고를까

구글 툴 검색 문서는 도구를 모델에 전하는 방식을 세 가지로 나눈다. 지금까지는 모든 도구 정의를 매 요청에 보내는 정적 로딩이 기본이었다.

도구 전달 방식 세 가지 (구글 공식 문서 기준)
구분정적 로딩서버 검색클라이언트 검색
도구가 모델에 닿는 방식매 요청에 전부 전송제미나이가 보류된 도구를 필요할 때 로드우리 앱이 필요할 때 도구를 돌려줌
직접 짜는 검색 코드없음없음검색·순위·필터 로직
검색 한 번당 추가 왕복없음없음(API 호출 한 번 안에서 처리)한 번
잘 맞는 경우안정적인 도구 약 20개 미만크지만 고정된 도구 목록자체 도구 레지스트리, 사용자별 도구 세트

그림 1은 문서의 비교표 원본이다. 서버 검색이 기본값이라 설정이 가장 간단하고, 클라이언트 검색은 사용자가 새 연동을 붙인 뒤 도구를 대화 도중에 추가하는 식의 구성에 쓴다. 문서에서 정적 로딩은 도구가 약 20개 미만으로 안정적일 때 맞는다고 하므로, 그 아래 규모라면 지금 방식을 유지해도 된다. 출처: 구글 Gemini API 문서 캡처(2026년 11월 20일).

제미나이 API 툴 검색 문서의 정적 로딩, 서버 검색, 클라이언트 검색 비교표

제미나이 툴 검색 설정 순서와 확인 방법

서버 검색은 tools 배열에 {"type": "tool_search"}를 하나 넣고, 보류할 함수에 defer_loading: true를 붙이면 된다. 문서는 mcp_server 항목에 붙이면 그 서버의 도구 전체가 보류된다고 설명한다. 모델은 보류된 도구의 이름과 설명만 보고, 필요하면 검색 단계를 내보내며 API가 전체 스키마를 돌려준다.

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})
tools = [
    {"type": "tool_search"},
    {"type": "function", "name": "convert_currency",
     "description": "Convert an amount between currencies.",
     "defer_loading": True,
     "parameters": {"type": "object",
       "properties": {"amount": {"type": "number"}, "to": {"type": "string"}},
       "required": ["amount", "to"]}},
]
interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Convert 100 USD to EUR.",
    tools=tools,
)
for step in interaction.steps:
    print(step.type, getattr(step, "name", ""))

위 코드는 구글 문서의 예시를 줄인 것이다. 제대로 동작하면 steps에 검색 단계와 검색 결과 단계가 먼저 보이고, 그 뒤 function_call이 나온다. 검색 단계는 API 호출 한 번 안에서 처리되므로 우리 코드가 응답할 필요는 없고, function_call만 실행해 function_result로 돌려주면 된다. 문서는 status 값에 기대지 말고 function_call 단계가 있는지로 판단하라고 안내한다.

제미나이 API 툴 검색이 도구 이름만 전달하고 필요한 스키마를 불러와 함수를 호출하는 흐름

그림 2는 요청이 도는 순서다. 구글 문서는 넓게 켜기 전에 자기 트래픽으로 재 보라고 안내한다. 같은 모델에 정적 로딩 요청과 툴 검색 요청을 따로 보내고 응답의 total_tool_use_tokens와 입력 토큰을 비교하면 이득인지 알 수 있다. 이 비교 방법은 문서 예시를 응용한 맥피의 제안이다.

요청마다 도구 배열을 다시 보내야 하는 이유와 400 오류

도구 선언은 요청 사이에 저장되지 않는다. 툴 검색 문서에 따르면 previous_interaction_id를 써도 tool_search 항목, 보류된 도구, 보류하지 않은 도구를 모두 매번 다시 보내야 한다. 빼먹으면 모델이 이전 도구를 계속 호출하려 할 수 있다. store=false로 상태를 직접 관리하면 검색 호출과 결과 단계를 signature까지 그대로 순서대로 돌려보내야 한다. 저장 기본값이 바뀐 배경은 제미나이 API 요청 저장 기본값 글에서 볼 수 있다.

툴 검색에서 자주 나오는 400 오류 (구글 공식 문서 기준)
오류 문구고치는 방법
tool_search tool must be specified when using defer_loading.tool_search 항목을 넣거나 defer_loading을 뺀다
Cannot specify both client-side and server-side tool_search tools.한 종류만 선언한다
deferred loading is not supported for this model지원 모델로 바꾼다
short_description can only be set if defer_loading is truedefer_loading을 켜거나 short_description을 뺀다
Server side tool call context must be circulated when using deferred loading functions.상태 비저장 흐름에서 빠뜨린 검색 단계를 그대로 다시 보낸다
Tool call part is missing thought_signature.검색 단계에서 지워진 signature를 복구한다

토큰이 줄어드는 앱과 늘어나는 앱

구글은 툴 검색 문서의 청구 항목에서 별도 요금 없이 모델의 기본 입력·캐시·출력 요금을 적용한다고 밝혔다. 다만 보류된 도구마다 이름과 짧은 설명이 한 줄씩 입력에 들어가고, 초기 테스트 기준 도구당 약 26토큰이다. 서버 검색이 일어날 때마다 같은 요청 안에서 전체 대화에 불러온 스키마까지 더한 모델 호출이 한 번 더 돌고, 그 프롬프트 전체가 total_tool_use_tokens로 잡힌다. 불러온 스키마는 대화가 끝날 때까지 남아 이후 호출에서 입력으로 계산되며, 한 번 불러온 도구를 내릴 방법은 없다.

구글 문서 예시의 입력 토큰 비교 (토큰, 대화 2회 요청)
시나리오정적 로딩툴 검색
도구 200개, 도구당 400토큰164,00023,650
도구 10개, 대화 30,000토큰68,00092,830

그림 3의 계산을 풀면 이렇다. 도구 200개 예시는 첫 요청이 2,000토큰 대화, 보류 목록 5,200토큰(200개×26), 지시문 150토큰을 합쳐 7,350이고, 검색 호출이 8,150을 더하며, 두 번째 요청이 8,150이라 약 23,650이다. 도구 10개 예시는 대화가 30,000토큰이라 검색 호출이 그 대화를 한 번 더 보내서 정적 로딩의 68,000보다 많은 약 92,830이 된다. 두 예시는 구글이 반올림한 숫자로 만든 설명용 계산이고 측정값이 아니며, 출력 토큰과 캐시는 빠져 있다. 출처: 구글 Gemini API 문서 캡처(2026년 11월 20일).

제미나이 API 툴 검색과 정적 로딩의 입력 토큰을 비교한 구글 문서의 계산 예시표

구글 문서의 절감 조건 설명을 정리하면 도구 정의가 큰 비중을 차지하고 요청 대부분이 검색을 안 하거나 한 번만 하는 앱에서 이득이다. 도구가 적거나 대화가 길어 거의 모든 요청이 검색하는 앱은 반대다. 도구를 보류하면 프롬프트가 작아져 모델의 최소 캐시 크기 아래로 떨어질 수도 있다.

도구 200개 예시에서 툴 검색 입력 토큰 구성 (토큰, 구글 문서 계산)
구성토큰
첫 요청의 대화2,000
보류 도구 목록(200개)5,200
툴 검색 지시문150
검색 호출(대화+목록+불러온 스키마)8,150
두 번째 요청8,150

세로로 보면 보류 목록과 검색 호출이 입력의 대부분을 차지한다. 불러온 스키마 2개(800토큰)는 작은 몫이라, 도구가 늘어도 목록은 도구당 약 26토큰씩만 늘어난다.

쓰기 전에 알아 둘 제한과 설계 요령

툴 검색 문서의 제한 목록에 따르면 툴 검색은 v1beta의 Interactions API에서만 되고 generateContent에서는 지원하지 않는다. 서버 검색과 클라이언트 검색은 한 요청에서 섞을 수 없고, defer_loading은 서버 검색 전용이다. 맞는 검색 결과가 없으면 구조화된 오류 대신 텍스트로 답이 와서, 검색 결과 단계만으로 검색 실패를 판단하면 안 된다. 문서는 정식 출시 전에 API 형태가 바뀔 수 있다고도 적었다.

모델 지원은 문서의 지원 모델 절과 변경 기록의 표현이 조금 다르다. 변경 기록은 Gemini 3.6 이후 모델이며 Gemini 4 전체가 포함된다고 쓰지만, 툴 검색 문서의 지원 목록은 gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash, gemini-3.6-flash 네 개다. 지원하지 않는 모델에 defer_loading을 쓰면 400 오류가 나므로 쓰려는 모델이 목록에 있는지 먼저 본다. 하이드로젠의 가격과 무료 티어는 제미나이 4 하이드로젠 정식 출시 글, 3.8 플래시의 교체 일정은 제미나이 API 모델 변경 정리에 있다.

문서의 설계 권고는 자주 쓰는 도구는 보류하지 않고 긴 꼬리만 보류하라는 것이다. 이름으로 직접 부르는 도구는 보류하지 말고, 보류하는 함수에도 전체 파라미터 스키마를 넣어야 한다. 이름과 짧은 설명만 보내면 검색이 빈 스키마를 돌려줘 모델이 호출하지 못한다. 비슷한 함수 이름에는 서비스 이름을 접두어로 붙이고, 언제 검색할지 시스템 지시에 적는다.

클로드·GPT에도 있는 기능이다

앤트로픽은 같은 이름의 툴 검색 도구를 안정(stable) 상태로 제공하고, 정규식과 BM25 두 가지 검색 방식과 요청당 보류 도구 최대 10,000개를 지원한다. OpenAI도 tool_search와 defer_loading을 두며, Responses API에서는 gpt-5.4 이후 모델만 지원한다고 문서에 적었다. 같은 아이디어가 세 회사에 모두 있어도 구현은 다르다.

세 회사의 툴 검색 비교 (각 사 공식 문서 기준, 2026년 11월 20일)
구분제미나이 API클로드 APIOpenAI API
검색 도구 이름tool_searchtool_search_tool_regex_20251119, tool_search_tool_bm25_20251119tool_search
쓸 수 있는 APIInteractions API 전용(v1beta, 프리뷰)Messages API 등(안정)Responses API
지원 모델gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash, gemini-3.6-flash클로드 오퍼스 4.5 이후 현행 모델(오퍼스 4.1 이하 제외)gpt-5.4 이후 모델
보류 지정 방식함수와 mcp_server 항목에 defer_loading도구 정의에 defer_loading, MCP는 mcp_toolset 설정함수와 MCP 서버 도구에 defer_loading, 네임스페이스 지원
별도 요금없음, 모델 기본 요금별도 서버 도구 요금 없음, 불러온 정의는 입력 토큰문서에 가격 언급 없음

도구 검색이 필요한지 판단하는 기준은 비슷하다. 클로드 문서는 도구가 10개 이상이거나 정의가 1만 토큰을 넘으면 쓰라고 권하는데, 제미나이 문서의 약 20개 미만 기준과 숫자가 다르다. 다만 각 문서의 기준이 서로 다른 모델과 계산에서 나온 값이라, 숫자를 그대로 비교하지 말고 자기 앱의 정의 토큰 수를 직접 재서 정하는 편이 낫다.

자주 묻는 질문

툴 검색을 쓰면 요금이 따로 붙나요?

구글 문서는 별도 요금이 없고 모델의 입력·캐시·출력 요금을 그대로 적용한다고 밝혔다. 다만 검색할 때마다 모델 호출이 한 번 더 돌아 입력 토큰은 늘 수 있다.

MCP 서버 도구도 보류할 수 있나요?

원격 mcp_server 항목에 defer_loading을 붙이면 그 서버가 내놓는 도구 전체가 보류된다. 여러 서버에 도구가 많을 때 유용하다고 문서에 적혀 있다.

generateContent로 만든 앱에도 쓸 수 있나요?

쓸 수 없다. 툴 검색은 Interactions API 전용이라, 기존 앱에 쓰려면 먼저 Interactions API로 옮겨야 한다.

이 글이 도움이 되었다면 공유해주세요

최신 인사이트

관련 프로젝트

새 글을 이메일로 받아보세요

마케팅, 분석, 개발 인사이트를 정리해서 보내드려요.