Gemini API Tool Retrieval 사용법: tool_search, defer_loading, 요금 정리

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

목차
Gemini API Tool Retrieval 사용법: tool_search, defer_loading, 요금 정리

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-hydrogen
  • gemini-4-argon
  • gemini-3.8-flash
  • gemini-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 truedefer_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와 실제 청구 금액을 함께 측정합니다.

LLM 워크플로를 최적화할 준비가 되셨나요?

하나의 API로 모델을 연결하고 키와 AI 비용을 관리하세요.

무료로 시작하기