Gemini API 토큰 비용이 늘었는데, 연결한 기능을 매번 전부 쓰는 건 아니라면요? 제미나이(Gemini)의 툴 리트리벌(Tool Retrieval)은 필요한 상세 입력 규칙만 불러오므로 이런 경우에 비용을 아낄 여지가 있어요.
구글은 2026년 11월 19일 Tool Retrieval을 프리뷰로 공개했어요.
외부 기능을 많이 연결한 에이전트가 대상입니다. 일반 제미나이 앱의 설정이 아니라 개발자가 API 요청에 넣는 옵션이에요.
기능을 늘릴수록
설명도 매번 보내야 할까요?
기존처럼 모든 기능의 상세 설명을 요청마다 보내면, 쓰지 않는 기능도 입력을 차지해요. 고객 정보 조회, 재고 확인, 환불 같은 기능을 붙여 둔 상담 에이전트를 생각해 볼게요. 재고만 묻는 질문에도 환불에 필요한 주문 번호와 금액 형식까지 함께 보내는 식입니다.
AI가 외부 기능을 부르는 방식을 함수 호출이라고 해요. 이때 기능 이름만 알려 줘서는 부족합니다. 어떤 값을 넣어야 하는지, 숫자인지 문자인지, 반드시 필요한 값은 무엇인지도 알려 줘야 해요.
이런 입력 규칙을 적은 것이 스키마예요. 연결한 기능이 많아질수록 모델이 읽을 스키마도 길어집니다. 구글은 이로 인해 입력 토큰과 지연이 늘고, 기능을 고르는 정확도도 떨어질 수 있다고 설명했어요. 토큰은 모델이 글과 데이터를 처리하고 요금을 계산할 때 쓰는 단위입니다.
필요한 스키마만
불러온다는 건 무슨 뜻일까요?
Tool Retrieval은 전체 스키마의 로딩을 미뤄요. 처음에는 미뤄 둔 기능들의 이름과 설명을 보여 주고, 모델이 필요하다고 고른 기능의 상세 입력 규칙을 나중에 불러옵니다.
환불 기능을 선택했다면 그때 주문 번호와 금액의 입력 형식을 받는 식이에요. 기능이 있다는 사실까지 감추는 방식은 아닙니다. 이름과 설명이 남아 있어야 모델도 무엇을 찾을지 알 수 있어요.
구글의 발표 예시에서는 모델이 환불 함수를 찾고, API가 스키마를 불러온 뒤, 모델이 실제 함수 호출을 내보냅니다. 환불 실행은 개발자 코드의 몫이에요. 스키마를 찾아 주는 과정과 실제 업무를 처리하는 과정은 구분해야 합니다.
구글 공식 발표의 issue_refund 함수와 order_id, amount 입력 규칙 선언
환불 함수 선언 화면. 출처: 구글 공식 발표, 캡처: 2026-11-20.
검색은 제미나이에 맡기거나
앱에서 직접 처리해요
기본인 서버 방식은 제미나이가 스키마를 찾아 줘요. 검색과 스키마 로딩은 1개 API 요청 안에서 진행돼요.
별도의 검색 인덱스를 만들지 않아도 됩니다. 자주 쓰는 기능은 처음부터 두고, 가끔 쓰는 기능만 나중에 불러오도록 설정할 수 있어요.
직접 관리하는 기능 목록이나 사용자별 권한 필터가 있다면 클라이언트 방식을 쓸 수 있어요. 여기서 클라이언트는 개발자가 만든 앱을 뜻합니다. 모델의 검색 요청을 받아 앱이 알맞은 스키마를 돌려주기 때문에, 검색할 때마다 앱과 API 사이에 추가 왕복이 생겨요.
클라이언트 방식은 처음 요청에 없던 기능도 대화 중에 전달할 수 있습니다. 사용자가 새 서비스를 연결했을 때 기능 목록을 추가하는 식이에요. 서버 방식과 클라이언트 방식은 한 요청에 함께 넣을 수 없습니다.
지원 모델과 API는
어디까지인가요?
적용 범위는 Interactions API예요. 일반적인 generateContent 호출에는 이 옵션을 붙여 쓸 수 없습니다. 기존 코드가 어느 API를 쓰는지부터 확인해야 해요.
2026년 11월 20일 설정 문서의 지원 목록에 적힌 모델은 4개입니다. 아래 표기는 API 요청에 넣는 모델 ID예요.
gemini-4-hydrogengemini-4-argongemini-3.8-flashgemini-3.6-flash
지원하지 않는 모델에서 지연 로딩을 켜면 400 오류가 납니다. 발표문의 넓은 세대 구분만 보고 다른 모델에 적용하지 말고, 실제 사용할 ID를 지원 목록과 대조하세요.
Tool Retrieval 공식 문서의 지원 모델 ID와 미지원 모델의 400 오류 안내
출처: 구글 공식 문서, Supported models. 캡처: 2026-11-20.
설정을 맡았다면
이 항목을 확인하세요
이 구간은 에이전트 코드를 수정하는 개발자용이에요. 설정을 맡기려는 분은 다음 비용 구간으로 넘어가도 괜찮습니다.
서버 방식의 설정은 검색 도구와 지연 로딩 표시가 핵심이에요. 공식 설정 예시는 환율 변환 함수와 날씨 서버를 연결합니다. 다음 항목을 기존 코드와 대조해 보세요.
요청의
tools배열에{"type": "tool_search"}를 추가합니다.나중에 불러올 함수에
defer_loading: true를 넣되, 전체parameters스키마도 함께 선언해요. 이 값은 JSON 표기이며 파이썬에서는True를 씁니다.MCP는 AI 프로그램을 외부 기능과 연결하는 규격이에요.
mcp_server에 같은 표시를 넣으면 그 서버의 기능들을 지연 로딩합니다.문서 예시는
v1beta를 지정한 클라이언트에서client.interactions.create(...)를 호출해요. 검색 도구는 요청당 1개만 선언합니다.
tool_search와 defer_loading을 함께 설정하고 Interactions API를 호출하는 구글의 파이썬 예시
출처: 구글 공식 문서, Server-side tool retrieval. 캡처: 2026-11-20.
후속 요청에도 전체 tools 배열을 다시 보내야 해요. 스키마를 모델이 읽는 시점을 미루는 것이지, 개발자 요청에서 스키마를 지우는 설정은 아닙니다. 대화 기록을 직접 관리한다면 검색 단계와 signature도 받은 그대로 되돌려 보내야 해요. 기록 누락은 다음 호출의 오류로 이어질 수 있습니다.
별도 요금이 없어도
토큰은 과금돼요
Tool Retrieval은 별도 기능 요금 없이 제공해요. 다만 API 사용까지 무료라는 뜻은 아닙니다. 공식 요금표의 Tool retrieval 항목은 미뤄 둔 기능 목록, 검색 지침, 불러온 스키마를 모델의 입력 토큰 요율로 청구한다고 안내해요.
특히 서버 검색은 같은 요청 안에서 추가 모델 호출을 일으킵니다. 그 호출의 프롬프트도 입력 요율로 과금돼요. 상세 스키마를 덜 읽게 된 이득과 검색 때문에 추가된 비용을 함께 봐야 합니다.
사용량 응답에서는 total_input_tokens뿐 아니라 total_tool_use_tokens도 확인하세요. 뒤쪽 항목에 서버 검색 이후 추가 모델 호출의 프롬프트가 잡힙니다. 캐시로 처리 된 부분은 total_cached_tokens에 표시되며 캐시 요율이 적용돼요.
Tool Retrieval의 별도 요금 없음과 입력·도구 사용·캐시 토큰의 청구 기준
출처: 구글 공식 문서, Token usage and billing. 캡처: 2026-11-20.
한 번 불러온 스키마는 이후 대화에도 남습니다. 기능이 적거나, 긴 대화에서 매번 검색한다면 비용이 오히려 늘 수 있어요. 모든 에이전트가 같은 비율로 저렴해지는 설정은 아닙니다.
우리 에이전트에는
언제 켜는 게 좋을까요?
기능은 많고 실제로 쓰는 것은 적을 때 먼저 시험해 볼 만해요. 자주 쓰는 기능은 그대로 두고 드물게 쓰는 기능부터 미루는 방식입니다. 기능이 몇 개 없고 늘 비슷하게 쓴다면, 설정을 바꾸기 전에 현재 입력에서 스키마가 차지하는 양부터 보세요.
설정을 맡길 때는 비용만 보지 말고 기능을 제대로 찾는지도 비교해 달라고 요청하세요. 개발자나 코드를 함께 보는 AI에 이렇게 물어볼 수 있어요.
이 호출 로그에서 자주 쓰는 기능과 드물게 쓰는 기능을 나눠 줘. 같은 질문으로 Tool Retrieval을 켰을 때와 껐을 때의 토큰 사용량, 응답 시간, 선택한 기능을 비교해 줘.
시험할 질문과 결과를 대조할 담당자를 정한 뒤, 실제 요청 일부에서부터 확인해 보세요.
글쓴이 강지인. AI 커뮤니티 지피터스(GPTers)에서 1인 마케팅을 맡고 있고, 매일 AX와 AI 뉴스, 에이전트에 관한 글을 씁니다.
확인일 2026-11-20
- 발표: Introducing Tool Retrieval in the Gemini API (구글, 2026-11-19)
- 설정·지원·과금: Tool retrieval
- 요금표: Gemini API pricing