Gemini API, Tool Retrieval 프리뷰 출시: 도구 스키마를 필요할 때만 로드, Gemini 3.6 이상 모델 지원

Google이 Gemini Interactions API의 Tool Retrieval 프리뷰를 발표했습니다. 에이전트가 필요할 때만 도구 파라미터 스키마를 불러와 입력 토큰과 지연 시간을 줄이며, Gemini 3.6 이상 모델에서 추가 요금 없이 쓸 수 있습니다.

뉴스 날짜: 읽는 데 약 7분

LINE 공유
목차
  1. 1. Tool Retrieval은 무엇을 바꾸나요?
  2. 2. 어떻게 켜나요? 서버 측과 클라이언트 측 검색은 무엇이 다른가요?
  3. 3. 지원 모델과 요금은 어떻게 되나요?
  4. 4. 개발 흐름에는 어떤 영향이 있나요?
  5. 5. 시작하려면 어떻게 하나요?

Google은 2026년 11월 19일 Gemini API의 Interactions API에 Tool Retrieval을 선보였다고 발표했습니다. 현재는 프리뷰(preview)이며 정식으로 전면 제공되는 것은 아닙니다. 이 기능은 'AI 에이전트', 즉 주문 조회나 환불처럼 외부 기능을 스스로 호출해 작업을 처리하는 AI 프로그램을 겨냥합니다. 호출 가능한 기능마다 필요한 입력 필드를 설명하는 '파라미터 스키마'(schema)를 붙여야 하는데, 도구가 많아지면 이 설명이 토큰(모델이 텍스트량을 세고 과금하는 단위)을 많이 차지합니다. Google은 Tool Retrieval이 요청당 토큰 부담과 지연 시간을 줄이고, 도구가 늘어났을 때 엉뚱한 도구를 고르는 문제를 막기 위한 기능이라고 설명합니다.

Tool Retrieval은 무엇을 바꾸나요?

Google은 에이전트가 수십, 수백 개의 도구에 연결되면 매 요청마다 전체 파라미터 스키마를 보내느라 입력 토큰 수와 지연 시간이 늘고, 후보 목록이 길어질수록 도구 선택 정확도도 떨어진다고 지적합니다. Tool Retrieval은 에이전트가 전체 도구 라이브러리를 '대기' 상태로 두고, 현재 작업에 필요할 때만 해당 파라미터 스키마를 불러오게 합니다.

Google 설명에 따르면 모델은 로드를 미룬 각 도구의 이름과 설명을 계속 볼 수 있어 어떤 도구가 있는지 알고 있습니다. 필요하면 모델이 이름으로 요청하고, API가 전체 스키마를 불러오면 모델이 같은 요청 안에서 함수 호출을 보냅니다. 이 세 단계는 모두 interaction.steps에 나타나므로 디버깅할 때 모델이 어떤 도구를 검토했는지 확인할 수 있습니다.

어떻게 켜나요? 서버 측과 클라이언트 측 검색은 무엇이 다른가요?

Google에 따르면 요청에 tool_search 도구를 추가하고, 로드를 미루려는 도구에 defer_loading: true를 설정하면 됩니다. 가장 자주 쓰는 도구는 미리 로드해 두고 사용 빈도가 낮은 도구만 미룰 수 있습니다. MCP 서버는 한 묶음의 도구를 AI 모델에 제공하는 연결 방식인데, 원격 MCP 서버를 쓴다면 mcp_server 도구에 defer_loading: true를 설정하는 것만으로 그 서버가 공개하는 모든 도구가 필요할 때 로드되며 하나씩 나열할 필요가 없습니다.

Google이 설명한 두 가지 검색 모드 비교
항목서버 측 검색클라이언트 측 검색
설정 방법tool_search를 추가하고 도구에 defer_loading: true 설정tool_search를 "execution": "client"로 선언하고 검색 파라미터를 직접 정의
인덱스Google에 따르면 인덱스를 만들거나 호스팅할 필요 없음. 검색은 Gemini가 서버에서 실행자체 도구 레지스트리, 임베딩 인덱스, 사용자별 권한 필터를 운영하는 경우에 적합
추가 왕복Google에 따르면 검색과 함수 호출이 한 요청 안에서 완료애플리케이션이 쿼리를 실행하므로 검색마다 왕복 한 번 추가
도구 선언로드를 미룬 도구도 이름과 설명을 포함해 선언해야 함도구를 미리 선언할 필요 없고 대화 도중 추가 가능

지원 모델과 요금은 어떻게 되나요?

Google에 따르면 Interactions API의 Tool Retrieval은 Gemini 3.6 이상 모델에서 쓸 수 있으며 모든 Gemini 4 모델이 포함됩니다. 이 기능에는 별도 요금이 없고, 입력·출력 토큰은 호출하는 모델의 표준 요율로 과금됩니다.

Google은 또한 tool_search를 켜면 소량의 고정 입력 토큰이 추가되고, 모델이 로드한 각 스키마는 미리 선언한 도구와 마찬가지로 대화의 나머지 구간에서 입력 토큰으로 과금된다고 설명합니다. 로드되지 않은 스키마가 로드된 스키마보다 많을 때만 토큰이 절약되므로, 자신의 트래픽으로 직접 평가해 볼 것을 권합니다.

개발 흐름에는 어떤 영향이 있나요?

이미 대규모 도구 라이브러리를 가진 팀이라면 검색 시스템을 새로 만드는 대신 요청에 도구 하나와 플래그 하나를 추가하는 것이 주된 변경입니다. 프리픽스 캐싱은 프롬프트 앞부분이 같을 때 그 부분을 재사용해 반복 처리를 아끼는 방식입니다. Google에 따르면 미룬 스키마는 프롬프트 앞부분에 없고 로드된 스키마는 대화 후반에 붙기 때문에 프리픽스 캐싱과 호환되며, 캐시된 프리픽스는 턴이 바뀌어도 그대로 유지됩니다.

시작하려면 어떻게 하나요?

  1. 요청의 tools에 tool_search 도구를 추가합니다.
  2. 로드를 미루려는 도구에 defer_loading: true를 설정합니다(원격 MCP 서버는 mcp_server 도구에 설정).
  3. 자체 검색이 필요하면 tool_search를 선언할 때 "execution": "client"를 설정하고 검색 파라미터를 정의합니다.
  4. Google이 제공하는 전체 설정 문서와 모델 비교를 참고하고, Discord에서 팀에 피드백을 남길 수 있습니다.

자주 묻는 질문

Tool Retrieval은 현재 정식 버전인가요?

아닙니다. Google은 Gemini Interactions API에서 프리뷰로 제공된다고 밝혔습니다.

코드를 얼마나 고쳐야 하나요?

Google에 따르면 서버 측 검색은 tool_search 도구를 추가하고 미룰 도구에 defer_loading 플래그를 붙이면 되며, 인덱스를 만들거나 호스팅할 필요가 없습니다. 자체 도구 레지스트리나 권한 필터를 쓰고 싶다면 클라이언트 측 검색을 쓸 수 있지만 검색마다 왕복이 한 번 늘어납니다.

켜면 항상 더 저렴한가요?

아닙니다. Google에 따르면 별도 요금은 없지만 tool_search가 소량의 고정 입력 토큰을 더하고 로드된 스키마도 입력 토큰으로 과금됩니다. 로드되지 않은 스키마가 로드된 스키마보다 많을 때만 토큰이 절약됩니다.

모델이 어떤 도구를 골랐는지 어떻게 확인하나요?

Google에 따르면 검색 도구, 스키마 로드, 함수 호출의 세 단계가 모두 interaction.steps에 나타나므로 모델이 검토한 도구를 확인하고 도구 이름이나 설명을 조정할 수 있습니다.

MCP 서버와 함께 쓸 수 있나요?

네. Google에 따르면 mcp_server 도구에 defer_loading: true를 설정하면 그 서버의 모든 도구가 필요할 때 로드됩니다.

이 주제의 최신 뉴스 보기

이 정리가 도움이 되셨나요? 필요한 분께 공유해 보세요

LINE 공유

출처

위에 기재된 참고 자료와 확인일 기준 정보를 바탕으로 정리했습니다. 요금, 시간표, 기능, 이용 약관은 바뀔 수 있으므로 여행, 예약 또는 구매 전에 해당 공식 사이트에서 최신 정보를 확인해 주세요.

라이프스타일