Gemini API Tool Retrieval 사용법: tool_search, defer_loading, 요금 정리
Gemini Interactions API(v1beta) 프리뷰에서 tool_search와 defer_loading으로 Tool Retrieval을 활성화하는 방법을 정리합니다. 서버 측·클라이언트 측 검색 모드 비교, 공식 블로그와 문서 간 지원 모델 4종 차이 및 400 오류 대응, 원격 MCP와 무상태 재전송 제약, 토큰 과금 필드와 암시적 프리픽스 캐싱의 손익분기점까지 다룹니다.
목차

Gemini Interactions API(v1beta)에서 Tool Retrieval이 프리뷰로 공개되어, 에이전트가 tool_search와 defer_loading으로 도구 파라미터 스키마를 필요할 때만 불러올 수 있습니다. 수십 개의 사용자 정의 함수나 원격 MCP 서버를 Gemini에 연결하는 개발자에게 해당하며, Interactions API에서만 사용할 수 있습니다(generateContent는 지원하지 않습니다). 2026-11-20 기준 바로 테스트하려면 문서에 명시된 4개 모델(gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash, gemini-3.6-flash) 중 하나로 v1beta/interactions를 호출하고, {"type": "tool_search"}를 추가한 뒤 핵심 도구는 미리 로드해 두고 그 외 필요한 때만 쓰는 도구에 defer_loading: true를 설정합니다.
먼저 적합한 API 경로 선택하기
Google은 2026년 11월 19일 Google 공식 블로그에서 Tool Retrieval을 발표하고, AI Studio Tool retrieval 문서에 설정 가이드를 공개했습니다. 이 기능은 Interactions API 프리뷰(v1beta) 전용이므로, 현재 사용하는 엔드포인트에 따라 즉시 도입 가능 여부가 갈립니다.
| 경로 | 계정 및 지원 지역 | 과금 단위 | Tool Retrieval 지원 여부 | 선택 기준 |
|---|---|---|---|---|
공식 Gemini Interactions API(v1beta) | 지원 지역의 Google AI Studio API 키(gemini-4-argon은 Paid Tier 필수) | 입력·캐시·출력 각 1M 토큰 기준(gemini-4-hydrogen, gemini-3.8-flash, gemini-3.6-flash는 Standard Free Tier 이용 가능) | 프리뷰 지원(tool_search, defer_loading, 원격 mcp_server) | 대규모 도구 라이브러리를 운영하며 v1beta/interactions를 직접 호출할 수 있는 경우 |
공식 Gemini generateContent API | 동일한 Google AI Studio 계정 및 지원 지역 | 입력·캐시·출력 각 1M 토큰 기준 | 미지원 | 안정적인 도구가 ~20개 미만이거나, 지원되는 Gemini 3·2.5 모델에서 명시적 캐싱이 필요하거나, 아직 마이그레이션할 수 없는 경우 |
| 종량제 API 게이트웨이(BetterToken 등) | 직접 등록한 BetterToken 계정과 콘솔에서 생성한 API 키 | 각 모델의 현재 과금 단위에 따라 종량제 잔액에서 차감 | Interactions API는 문서화되지 않았으며 Tool Retrieval 지원 여부는 미검증 | 여러 모델에 걸쳐 문서화된 네이티브 Gemini generateContent 또는 OpenAI 호환 Chat Completions 엔드포인트를 유지하는 경우(모델별 도구 지원은 BetterToken 문서 확인) |
Interactions API로 전환하지 않고 표준 Gemini generateContent 또는 OpenAI 호환 Chat Completions를 유지한다면, BetterToken의 Gemini API 레퍼런스 확인하기에서 문서화된 엔드포인트, 모델 ID, 모델별 도구 지원 범위를 확인할 수 있습니다.
지원 모델과 Gemini 4의 400 오류
2026년 11월 19일 Google 발표 블로그는 Tool Retrieval이 모든 Gemini 4 모델을 포함한 Gemini 3.6 이후 모델에서 동작한다고 안내하며 Latest Gemini models 페이지로 연결합니다. 해당 페이지에는 gemini-4-carbon, gemini-4-neon, gemini-4-hydrogen, gemini-4-argon 등 Gemini 4 모델 4종이 나열되어 있습니다.
그러나 2026-11-20 기준 공식 Tool retrieval 지원 모델 목록에 기재된 모델 ID는 다음 4개뿐입니다.
gemini-4-hydrogengemini-4-argongemini-3.8-flashgemini-3.6-flash
2026-11-20 기준 gemini-4-carbon과 gemini-4-neon은 Tool Retrieval 문서에 포함되어 있지 않습니다. 미지원 모델로 defer_loading을 전송하면 deferred loading is not supported for this model 메시지와 함께 HTTP 400 오류가 반환됩니다.
초기 연동은 Google이 Tool Retrieval 예제 전반에서 사용하는 gemini-4-hydrogen으로 시작하는 편이 안전합니다. Flash 모델에서 전환 중이라면 Gemini 4 Hydrogen 요금 및 마이그레이션 가이드를 참고할 수 있습니다. 워크플로가 gemini-4-carbon에 의존한다면 defer_loading을 켜기 전에 v1beta에서 실제 동작을 확인하거나, 정적 도구 로딩을 유지하면서 Gemini 4 Carbon API 요금 및 마이그레이션 가이드를 참고합니다.
서버 측 검색과 클라이언트 측 검색 비교
Interactions API는 서로 배타적인 두 가지 검색 모드를 제공합니다. 기본값인 서버 측 검색과 클라이언트 측 검색(execution: "client")입니다. 두 모드 모두 초기 프롬프트에서 스키마를 제외하지만 지연 시간, 구현 범위, 도구 등록 방식이 다릅니다.
| 항목 | 정적 도구 로딩 | 서버 측 검색 | 클라이언트 측 검색 |
|---|---|---|---|
| 스키마가 모델에 전달되는 방식 | 처음에 전부 전송 | Gemini가 지연된 스키마를 필요 시 로드 | 애플리케이션이 function_result로 스키마 반환 |
| 작성해야 할 검색 코드 | 없음 | 없음 | 자체 검색·순위화·필터링 로직 구현 |
| 도구 사전 선언 여부 | 필요 | 필요 | 불필요 |
| 원격 MCP 지원 | 지원 | 지원(mcp_server에 defer_loading: true) | 해당 없음 |
| 추가 네트워크 왕복 | 없음 | 없음(단일 API 호출 내부에서 처리) | 검색당 1회 왕복 추가 |
| 적합한 환경 | ~20개 미만의 고정 도구 | 대규모 고정 도구 라이브러리 또는 다수 MCP 서버 | 사내 레지스트리, 사용자별 권한, 세션 중 동적 도구 주입 |
요청당 tool_search 항목은 하나만 선언할 수 있습니다. 같은 요청에 서버 측과 클라이언트 측 tool_search를 함께 넣으면 Cannot specify both client-side and server-side tool_search tools. 오류가 반환됩니다.
서버 측 검색 및 원격 MCP 설정하기
서버 측 검색은 v1beta API 버전이 필수입니다. Google 블로그 코드 스니펫에는 api_version이 생략되어 있지만, 공식 Tool retrieval 가이드는 프리뷰 Tool Retrieval에 v1beta가 필요하다고 명시합니다. Python에서는 genai.Client(http_options={"api_version": "v1beta"}), JavaScript에서는 new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } })로 초기화합니다.
Bash에서 Gemini API 키를 터미널에 출력하지 않고 불러온 뒤 https://generativelanguage.googleapis.com/v1beta/interactions로 POST 요청을 보냅니다. 아래 예제는 지연 로딩 로컬 함수(convert_currency)와 Google이 문서화한 데모 날씨 MCP 서버(https://gemini-api-demos.uc.r.appspot.com/mcp)를 함께 연결합니다.
read -rs GEMINI_API_KEY && export GEMINI_API_KEY
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-4-hydrogen",
"input": "Check the temperature in London and convert 100 USD to EUR.",
"tools": [
{"type": "tool_search"},
{
"type": "function",
"name": "convert_currency",
"description": "Convert an amount from one currency to another using live mid-market rates.",
"short_description": "Convert an amount between currencies.",
"defer_loading": true,
"parameters": {
"type": "object",
"properties": {
"amount": {"type": "number"},
"from": {"type": "string"},
"to": {"type": "string"}
},
"required": ["amount", "from", "to"]
}
},
{
"type": "mcp_server",
"name": "weather_service",
"url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
"defer_loading": true
}
]
}'
tools 배열을 구성할 때는 다음 네 가지 규칙을 따릅니다.
- 서버 측
tool_search객체에서는name,description,parameters필드를 지정하지 않고 생략합니다. - 지연 대상인 모든
function에는 완전한parameters스키마를 포함합니다. 로드되지 않은 스키마는 과금되지 않으며, 파라미터 없이 전송한 도구는 검색 후 빈 스키마로 반환되어 모델이 호출할 수 없습니다. - 선택 필드인
short_description은defer_loading: true와 함께 사용할 때만 설정하여, 간략한 지연 목록에서 긴description을 대체합니다. - 원격 MCP 서버는 Remote MCP 문서에 따라 Streamable HTTP 엔드포인트만 연결할 수 있으며(SSE 서버는 미지원), 서버 이름에는
-없이snake_case를 사용합니다. 원격 서버에서 핸드셰이크나 스키마 검증이 실패하면 MCP 서버 연동 트러블슈팅 가이드를 확인합니다.
서버 측 응답 검증하기
서버 측 검색이 성공하면 동일한 API 호출 응답의 steps 내부에 tool_search_call과 tool_search_result 단계가 포함되고, 이어서 실제 도구 호출이 나타납니다. 데모 서버의 get_weather 같은 원격 MCP 도구는 API가 원격 호출까지 실행하여 같은 응답 안에 mcp_server_tool_call과 mcp_server_tool_result 단계를 함께 반환합니다.
직접 구현한 함수의 경우 steps 내부의 function_call 항목을 직접 확인합니다. Google 문서에 따르면 function_call 단계가 존재해도 status가 항상 requires_action으로 설정되지는 않으므로 status == "requires_action"에만 의존하지 않습니다. 로컬에서 함수를 실행한 뒤 다음 턴에 function_result를 전송합니다.
클라이언트 측 검색 설정하기
도구 목록이 사용자 권한, 내부 네임스페이스, 또는 세션 시작 후 추가되는 연동에 따라 달라진다면 execution: "client"를 사용합니다. 클라이언트 측 tool_search 정의에서는 name과 description이 모두 필수이며(어느 하나라도 빠지면 400 오류 발생), 같은 요청의 어떤 도구에도 defer_loading을 설정하면 안 됩니다.
아래 Python 예제는 실제 레지스트리를 조회하는 대신 고정된 함수 선언을 반환하는 최소 프로토콜 예제입니다. 스크립트가 followup.steps에서 {"user_id": 123} 인자를 가진 get_billing_history의 function_call 단계를 출력하면 왕복 흐름이 정상 동작한 것입니다.
from google import genai
client = genai.Client(http_options={"api_version": "v1beta"})
tools = [
{
"type": "tool_search",
"execution": "client",
"name": "search_tool_registry",
"description": "Search internal tool namespaces such as billing and support when needed.",
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string"},
"namespace": {"type": "string"},
},
"required": ["query"],
},
}
]
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Look up the billing history for user 123.",
tools=tools,
)
for step in interaction.steps:
if step.type == "function_call" and step.name == "search_tool_registry":
# Minimal protocol example: replace with your own registry or permission filter.
matches = [
{
"type": "function",
"name": "get_billing_history",
"description": "Retrieve billing history for a given user.",
"parameters": {
"type": "object",
"properties": {"user_id": {"type": "integer"}},
"required": ["user_id"],
},
}
]
followup = client.interactions.create(
model="gemini-4-hydrogen",
previous_interaction_id=interaction.id,
tools=tools,
input=[
{
"type": "function_result",
"name": step.name,
"call_id": step.id,
"result": matches,
}
],
)
for next_step in followup.steps:
if next_step.type == "function_call":
print(next_step.name, next_step.arguments)
function_result.result 배열에는 직렬화된 JSON 문자열이 아니라 완전한 함수 선언 JSON 객체를 담아 반환하고, 검색 function_call과 일치하는 name 및 call_id를 함께 넣습니다. 클라이언트 측 검색 결과가 없을 때는 일치 항목이 없다는 짧은 텍스트와 모델이 검색할 수 있는 대상 목록을 반환해 쿼리를 수정할 수 있게 합니다.
멀티턴 상태 관리, 무상태 재전송, 자주 발생하는 오류
첫 턴 이후 발생하는 대부분의 연동 오류는 프리뷰 단계의 다음 세 가지 제약에서 비롯됩니다.
- 매 요청마다 전체
tools배열을 다시 전송합니다. Interactions API는previous_interaction_id를 전달하면 단계 이력을 저장하지만, 요청 간 도구 선언은 유지하지 않습니다. 후속 턴에서 도구를 빼면 모델이 미선언 도구를 놓치거나 서버 측 모드에서 내부retriever:호출을 출력할 수 있습니다. - 한번 불러온 도구는 해제할 수 없으며, 서버 측 검색 실패는 텍스트로 반환됩니다. 모델이 로드한 도구 스키마는 해당 대화가 끝날 때까지 컨텍스트에 유지됩니다. 서버 측 쿼리가 어떤 지연 도구와도 일치하지 않으면 구조화된 검색 오류 대신 일반 텍스트 응답이 돌아오므로,
tool_search_result로 검색 실패를 판별하지 않습니다. store=false일 때는 모든 단계와 서명을 원본 그대로 되돌려 보냅니다. 무상태 후속 요청에서는input에 전체 단계 이력을 넣고 전체tools배열도 재전송합니다. 응답에서 받은 모든 단계(tool_search_call,tool_search_result,thought,function_call)를 원래 순서와signature를 유지한 채 그대로 추가한 뒤 새로운function_result를 붙입니다.function_result만 보내면 검색 컨텍스트가 사라져400오류가 발생합니다. 구버전 SDK는tool_search_call과tool_search_result를 알 수 없는 단계로 파싱해 필드를 누락시키므로, 이를 인식하는 SDK 버전을 사용합니다. 시스템 지침이나 다른 도구 출력에 이름을 직접 언급한 도구는 지연하지 않고 상시 로드 상태로 두어야 모델이 검색 없이 호출해function_result에서 실패하는 상황을 피할 수 있습니다.
Google 문서는 미지원 모델, defer_loading 사용 시 서버 측 tool_search 누락, defer_loading: true 없는 short_description, 클라이언트 측 name 또는 description 누락, 무상태 단계 누락, signature 제거에 대해 HTTP 400 응답을 명시합니다. 문서화된 오류 메시지별 원인과 해결 방법은 아래 표와 같습니다.
| 문서화된 오류 메시지 | 원인 | 해결 방법 |
|---|---|---|
deferred loading is not supported for this model | 지원 목록에 없는 모델로 defer_loading을 전송함 | gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash, gemini-3.6-flash 중 하나로 전환합니다 |
tool_search tool must be specified when using defer_loading. | function 또는 mcp_server에 defer_loading: true를 설정했으나 요청에 tool_search 도구가 없음 | {"type": "tool_search"}를 추가하거나 defer_loading을 제거합니다 |
When defer_loading is set on a FunctionDeclaration, a Tool with tool_search must also be provided in the request. | 함수에 defer_loading: true가 있지만 서버 측 tool_search가 없음(execution: "client"만 선언했거나 후속 요청에서 tool_search를 빠뜨린 경우 등) | 클라이언트 측 모드에서는 defer_loading을 제거하고, 서버 측 모드에서는 {"type": "tool_search"}를 포함한 전체 tools 배열을 재전송합니다 |
Cannot specify both client-side and server-side tool_search tools. | 요청에 서버 측과 클라이언트 측 tool_search가 동시에 포함됨 | 요청당 tool_search 항목을 정확히 하나만 선언합니다 |
ToolSearch name must not be specified when execution mode is SERVER_SIDE. | 서버 측 tool_search에 name을 지정함(description과 parameters에서도 동일 오류 발생) | 해당 필드를 제거합니다. execution: "client"로 전환할 때는 name과 description을 모두 지정하고 모든 도구에서 defer_loading을 제거합니다 |
short_description can only be set if defer_loading is true | defer_loading: true 없이 함수에 short_description을 지정함 | defer_loading: true를 추가하거나 short_description을 제거합니다 |
Server side tool call context must be circulated when using deferred loading functions. | 무상태 요청 이력에 지연 도구의 function_result는 있지만 이를 불러온 tool_search_call과 tool_search_result 단계가 빠짐 | 모든 tool_search_call 및 tool_search_result 단계를 signature 포함 원본 그대로 다시 전송합니다 |
Server side tool call context must be circulated ... Missing circulated context for functions: FUNCTION_NAME (모든 단계를 재전송한 경우에도 발생) | 대화 내 tool_search로 불러오지 않은 지연 함수를 모델이 호출함(주로 시스템 지침이나 다른 도구 출력에 함수 이름이 등장한 경우) | 이름으로 직접 언급하는 도구는 지연 로딩하지 않습니다 |
Tool call part is missing thought_signature. / Tool response part is missing thought_signature. | 무상태 요청에서 tool_search_call(호출 측) 또는 tool_search_result(응답 측) 단계의 signature 필드를 제외하고 재전송함 | 두 검색 단계 모두 signature 값을 유지한 채 원본 그대로 재전송합니다 |
과금 필드, 프리픽스 캐싱, 손익분기점 계산
Tool Retrieval에는 별도의 기능 수수료가 없습니다. 모든 토큰은 Gemini API 가격 페이지의 표준 입력·캐시·출력 단가로 청구됩니다. 2026-11-20 기준 Paid Tier에서 gemini-4-hydrogen은 1M 토큰당 입력 $1.50, 캐시 입력 $0.075, 출력(사고 토큰 포함) $7.50입니다. gemini-4-hydrogen, gemini-3.8-flash, gemini-3.6-flash는 Standard Free Tier를 지원하며, gemini-4-argon은 Paid Tier 전용으로 2026년 11월 30일까지 1M 토큰당 입력 $2.00·캐시 $0.10·출력 $10.00이고 2026년 12월 1일부터는 $4.00 / $0.20 / $20.00으로 인상됩니다.
토큰 사용량을 추적하려면 각 응답의 usage 객체에서 다섯 개 필드를 확인합니다.
total_input_tokens: 요청 내 첫 번째 모델 호출의 프롬프트입니다. 사용자 입력, 대화 이력, 시스템 지침, 비지연 도구 스키마, 소량의 고정tool_search지침 블록, 그리고 지연 도구 한 줄 목록(name과short_description또는description첫 문장 조합으로 Google 초기 테스트 기준 지연 도구당 약 26토큰)이 포함됩니다.total_tool_use_tokens: 각 서버 측 도구 검색을 포함해 서버 측 도구 실행 후 API가 같은 요청 안에서 추가로 수행하는 모델 호출의 프롬프트 합계입니다. 매 호출마다 전체 컨텍스트와 새로 로드된 스키마를 다시 전송하며 입력 단가로 과금되고, 한 턴에 검색을 여러 번 수행하면 그만큼 패스가 늘어납니다.total_cached_tokens: 암시적 캐시에서 실제로 처리된 입력 토큰 수로, 일반 입력 단가 대신 캐시 단가가 적용됩니다.total_output_tokens: 생성된 응답 토큰이며 출력 단가로 과금됩니다.total_thought_tokens: 생성된 사고 토큰이며 출력 단가로 과금됩니다.
프리픽스 캐싱 최소 토큰 임계값 주의사항
Context caching 문서에 따르면 Interactions API는 암시적 캐싱만 지원하며, 명시적 캐싱은 Interactions API와 Gemini 4 모델 모두에서 지원되지 않습니다. 검색된 스키마는 프롬프트 맨 앞이 아니라 모델이 불러온 시점에 추가되므로, 시스템 지침·도구 목록·이전 턴이 여러 턴에 걸쳐 동일한 프리픽스로 유지됩니다. 이 프리픽스가 모델의 최소 캐싱 가능 크기를 초과하면 각 서버 측 검색이 유발하는 추가 모델 호출을 포함해 이후 요청이 암시적 캐시에서 처리될 수 있으며, 캐시에서 처리된 토큰 수는 total_cached_tokens에 보고됩니다.
다만 2026-11-20 기준 Tool Retrieval을 지원하는 4개 모델 모두 암시적 캐싱에 최소 4,096 입력 토큰이 필요합니다. 전체 도구 스키마 때문에 4,096토큰을 넘겼던 프롬프트라면, 해당 도구를 지연 로딩으로 전환할 때 최소 캐싱 가능 크기 아래로 떨어질 수 있습니다. 또한 Gemini 4 모델의 멀티턴 및 에이전트 루프에서는 새 요청이 최소 2,050토큰을 추가할 때만 이전 요청 전체가 캐싱됩니다(모델 출력, 사고 토큰, 함수 결과가 모두 이 합계에 포함됩니다). 추가 토큰이 이보다 적으면 Gemini는 이전 요청의 마지막 2,050토큰을 표준 입력 단가로 다시 처리합니다.
Tool Retrieval이 토큰을 절약하는 경우와 더 드는 경우
Google 문서에는 2회 요청 기준의 예시 추정치(어림수이며 출력 토큰과 캐싱은 제외)가 제시되어 있습니다. 이 예시에서 모델은 400토큰짜리 도구 2개를 불러온 뒤 첫 번째 요청의 응답으로 function_call을 반환하고, 애플리케이션은 함수를 실행한 다음 두 번째 요청에서 function_result를 전송합니다.
| 예시 시나리오(Google 문서 추정치) | 정적 로딩(입력 토큰) | Tool Retrieval(입력 + 도구 사용 토큰) | 순결과 |
|---|---|---|---|
| 도구 200개(각 400토큰), 컨텍스트 2,000토큰 | 2 × (2,000 + 80,000) = 164,000 | 요청 1: 7,350 + 검색 패스 8,150; 요청 2: 8,150 = ~23,650 | 입력 측 토큰 ~86% 절감 |
| 도구 10개(각 400토큰), 컨텍스트 30,000토큰 | 2 × (30,000 + 4,000) = 68,000 | 요청 1: 30,410 + 검색 패스 31,210; 요청 2: 31,210 = ~92,830 | 입력 측 토큰 ~37% 증가 |
도구 라이브러리가 크고 대부분의 턴에서 소수의 도구만 사용할 때 지연 로딩의 효과가 큽니다. 반대로 도구 집합이 작거나 긴 대화에서 거의 매 턴 검색이 발생하면 서버 측 추가 검색 패스(total_tool_use_tokens)가 절감분을 넘어설 수 있습니다. 사용 빈도가 높은 핵심 도구는 처음부터 로드해 두고 사용 빈도가 낮은 나머지 도구만 지연 로딩으로 설정한 뒤, 전면 도입 전에 실제 트래픽으로 total_input_tokens, total_tool_use_tokens, total_cached_tokens와 실제 청구 금액을 함께 측정합니다.