저널 Uncategorized

Gemini API 도구 검색(Tool Retrieval) 정리: 필요한 도구만 불러오는 방식, 요금 계산법과 제약

AI 어시스턴트가 닫힌 서랍 여러 개 가운데 하나만 열어 도구 카드를 꺼내는 모습을 그린 AI 생성 설명용 일러스트
AI로 생성한 설명용 일러스트이며 실제 사건의 사진이 아닙니다.

AI 에이전트에 연결하는 도구가 늘어나면 고민이 하나 생깁니다. 환불, 배송 조회, 일정 등록, 사내 문서 검색처럼 기능을 붙일 때마다 각 도구의 설명과 입력 형식(파라미터 스키마)을 모델에 매번 보내야 하기 때문입니다. 도구가 수십 개를 넘으면 실제 질문보다 도구 설명이 더 길어지기도 합니다.

구글이 2026년 11월 19일(현지 시각) Gemini API에 ‘Tool Retrieval’을 프리뷰로 추가했습니다. 도구 목록은 이름과 짧은 설명만 보여 주고, 모델이 필요하다고 판단한 도구의 상세 스키마만 그때 불러오는 방식입니다. 아래에서는 구글 공식 발표와 Gemini API 공식 문서를 기준으로 작동 방식, 요금 구조, 지원 모델과 제약을 정리했습니다.

이 글은 문서와 보도를 읽고 정리한 것이며, 직접 성능이나 비용 절감 폭을 측정한 결과는 아닙니다.

1. Tool Retrieval은 무엇을 바꾸나요

기존 함수 호출 방식에서는 에이전트가 쓸 수 있는 모든 함수의 이름, 설명, 파라미터 스키마를 요청마다 함께 보냅니다. 구글은 발표에서 도구가 많아질수록 입력 토큰이 늘고, 응답이 느려지고, 후보가 많아 도구 선택 정확도도 떨어진다고 설명했습니다.

Tool Retrieval을 켜면 도구를 두 부분으로 나눠 다룹니다.

  • 항상 보이는 부분: 도구 이름과 짧은 설명
  • 필요할 때만 불러오는 부분: 전체 파라미터 스키마

모델은 어떤 도구가 있는지는 알고 있다가, 작업에 필요한 도구를 이름으로 요청합니다. 그러면 API가 해당 스키마를 불러오고, 모델이 그 함수를 호출합니다. 공식 문서에 따르면 이 검색, 스키마 로드, 함수 호출 단계가 한 번의 API 요청 안에서 처리됩니다.

2. 켜는 방법: 검색 도구 하나와 보류 표시

공식 문서가 안내하는 설정은 비교적 단순합니다.

  1. tools 배열에 type이 tool_search인 항목을 하나 추가합니다.
  2. 당장 쓰지 않을 도구에 defer_loading 값을 true로 표시합니다.
  3. 응답의 steps를 확인해 function_call 단계가 오면 평소처럼 함수를 실행하고 결과를 돌려줍니다.

응답에는 tool_search_call, tool_search_result, function_call 단계가 차례로 기록됩니다. 구글은 이 기록을 보면 모델이 어떤 도구를 검토했는지 확인할 수 있어, 도구 이름이나 설명을 다듬을 때 참고하라고 설명합니다. 별도 검색 인덱스를 만들거나 호스팅할 필요는 없습니다.

자주 쓰는 핵심 도구는 보류하지 않고 처음부터 불러 두고, 가끔 쓰는 긴 꼬리 도구만 보류하는 구성이 권장됩니다. 원격 MCP 서버 항목에 defer_loading을 켜면 그 서버가 제공하는 도구 전체를 필요할 때만 불러옵니다. 설명이 긴 함수에는 검색 단계에서만 보여 줄 short_description을 따로 붙일 수 있습니다.

3. 서버 검색과 클라이언트 검색, 무엇을 고를까

검색 방식은 두 가지입니다. 기본값은 구글 서버가 검색하는 방식이고, 직접 검색 로직을 쓰는 클라이언트 방식도 있습니다.

  • 서버 검색(기본): 도구를 미리 선언하고 보류 표시만 하면 됩니다. 검색이 한 요청 안에서 끝나므로 지연에 민감한 앱에 맞다고 문서는 설명합니다.
  • 클라이언트 검색: tool_search의 실행 위치를 client로 지정하고 이름, 설명, 검색 파라미터를 정의합니다. 모델이 검색을 요청하면 우리 앱이 자체 레지스트리에서 찾아 함수 선언을 돌려줍니다. 검색마다 왕복이 한 번 더 생기지만, 처음에 도구를 선언하지 않아도 되고 대화 도중 새 도구를 넣을 수 있습니다.
  • 기존 정적 로딩: 문서의 비교표는 20개 미만의 안정적인 도구라면 모든 스키마를 매번 보내는 방식이 적합하다고 봅니다.

사용자별 권한에 따라 쓸 수 있는 도구가 달라지는 서비스라면 클라이언트 방식이 관리하기 쉽습니다. 어떤 도구를 누구에게 보여 줄지 우리 앱이 결정하기 때문입니다. 다만 한 요청 안에서 두 방식을 섞을 수는 없습니다.

4. 요금: 별도 요금은 없지만 무조건 절약도 아니다

구글은 Tool Retrieval 자체에 별도 요금이 없고, 호출한 모델의 일반 입력·캐시·출력 단가로 과금된다고 밝혔습니다. 비용 구조는 문서에 다음과 같이 나뉘어 있습니다.

  • 보류한 도구는 이름과 short_description(없으면 description의 첫 문장)만 입력 토큰으로 잡힙니다. 파라미터 스키마는 불러오기 전까지 과금되지 않습니다.
  • 서버 검색을 할 때마다 요청 안에서 전체 컨텍스트와 불러온 스키마를 읽는 추가 모델 호출이 일어납니다. 이 토큰은 total_tool_use_tokens로 따로 보고되고 입력 단가로 청구됩니다.
  • 한 번 불러온 스키마는 대화가 끝날 때까지 컨텍스트에 남고 내릴 수 없습니다.

그래서 문서도 도구가 많고 요청마다 일부만 쓰는 경우에 절약 효과가 난다고 설명합니다. 도구 수가 적거나, 컨텍스트가 매우 긴 대화에서 매 턴 검색이 일어난다면 기존 정적 로딩이 더 저렴할 수 있다고 적었습니다. 독립 매체 PPC Land도 구글이 구체적인 절감 수치나 벤치마크를 제시하지 않았고, 검색 한 번마다 별도 과금 단계가 추가된다는 점을 지적했습니다. 구글 역시 실제 트래픽으로 직접 측정해 보라고 권합니다.

캐시와의 관계도 확인할 부분입니다. 불러온 스키마는 프롬프트 앞부분이 아니라 대화 뒤쪽에 붙기 때문에 암묵적 캐싱이 계속 적용된다고 구글은 설명합니다. 반대로 도구를 보류해 프롬프트가 짧아지면 모델별 최소 캐시 크기 아래로 내려갈 수 있다는 점도 문서에 적혀 있습니다.

5. 쓸 수 있는 곳과 지원 모델

현재 상태는 프리뷰이며 v1beta API 버전에서만 동작합니다. 정식 출시 전 API 형태가 바뀔 수 있다고 문서에 명시돼 있고, 정식 출시 일정은 발표되지 않았습니다.

  • 지원 API: Interactions API만 지원합니다. 기존 generateContent 메서드는 지원하지 않습니다.
  • 지원 모델(2026년 11월 21일 문서 기준): gemini-4-carbon, gemini-4-neon, gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash, gemini-3.6-flash
  • 지원하지 않는 모델에 보류 표시를 하면 오류가 반환됩니다.

발표문은 ‘Gemini 3.6 이후 모델, 모든 Gemini 4 모델’이라고 넓게 표현했습니다. 한편 PPC Land는 발표 당일 문서의 지원 목록이 이와 달랐다고 보도했습니다. 지원 목록이 바뀌고 있을 수 있으니, 도입 전에 공식 문서의 지원 모델 항목을 다시 확인하는 편이 안전합니다. PPC Land는 비슷한 방식의 기능을 앤트로픽과 OpenAI도 앞서 내놓았다고 전했습니다.

6. 도입 전 주의할 점

문서의 제약과 권장 사항 가운데 실제 구현에서 문제가 되기 쉬운 항목을 모았습니다.

  • 도구 배열은 매번 전체 전송: 이전 대화 ID로 이어 가더라도 API가 도구 선언을 저장하지 않습니다. 후속 요청에도 tool_search와 보류 도구를 포함한 전체 tools 배열을 보내야 합니다.
  • 직접 대화 기록을 관리한다면: 검색 단계 기록을 순서대로, signature 값을 그대로 유지해 돌려보내야 합니다. 검색 호출 기록을 빼거나 signature를 지우면 400 오류가 납니다.
  • 시스템 지시문에 이름을 적은 도구는 보류 금지: 모델이 검색 없이 바로 호출해 오류가 날 수 있습니다.
  • 검색 실패는 조용히 처리: 일치하는 도구가 없으면 구조화된 오류가 아니라 일반 텍스트 응답이 돌아옵니다.
  • 상태값만 믿지 않기: 함수 호출이 있어도 status가 항상 requires_action은 아니므로 steps를 직접 확인하라고 문서는 권합니다.
  • 이름 짓기: billing_get_customer, crm_get_customer처럼 서비스 이름을 앞에 붙이면 비슷한 도구를 구분하기 쉽다고 안내합니다.

보류한 도구도 파라미터 스키마는 빠짐없이 선언해야 합니다. 스키마가 없으면 검색으로 찾아도 모델이 호출할 수 없습니다.

정리

Tool Retrieval은 도구가 많은 Gemini 에이전트에서 매번 보내던 스키마를 줄이는 프리뷰 기능입니다. 별도 요금은 없지만 검색마다 추가 입력 토큰이 생기므로, 절약 여부는 도구 수와 대화 패턴에 따라 달라집니다.

  • 도구가 20개 미만이고 거의 바뀌지 않는다면 기존 방식 유지도 합리적입니다.
  • 도입한다면 자주 쓰는 도구는 그대로 두고 드물게 쓰는 도구만 보류해 total_input_tokens와 total_tool_use_tokens를 비교해 보세요.
  • Interactions API v1beta 전용이며 정식 출시 전 변경 가능성이 있습니다.

출처

자료 확인일: 2026년 11월 21일(한국 시간). 요금과 지원 모델은 이후 바뀔 수 있습니다.

AI로 생성한 설명용 일러스트이며 실제 사건의 사진이 아닙니다.