Articleblog.google·2026년 11월 19일·0

Introducing Tool Retrieval in the Gemini API

Quick Summary

Google이 Gemini Interactions API에서 도구의 매개변수 스키마를 필요할 때 불러오는 Tool Retrieval을 프리뷰로 공개해, 대규모 도구 라이브러리의 입력 토큰·지연 시간·선택 정확도 문제를 줄이도록 했다.

Introducing Tool Retrieval in the Gemini API 관련 대표 이미지

🖼️ 인포그래픽

Introducing Tool Retrieval in the Gemini API 내용을 설명하는 본문 이미지

🖼️ 4컷 인포그래픽

Introducing Tool Retrieval in the Gemini API의 핵심 내용을 4단계로 요약한 인포그래픽
Introducing Tool Retrieval in the Gemini API 핵심 내용을 4단계로 압축한 4컷 인포그래픽

💡 한 줄 요약

Google이 Gemini Interactions API에서 도구의 매개변수 스키마를 필요할 때 불러오는 Tool Retrieval을 프리뷰로 공개해, 대규모 도구 라이브러리의 입력 토큰·지연 시간·선택 정확도 문제를 줄이도록 했다.

📌 핵심 요약

  • Google은 2026년 11월 19일 Tool Retrieval을 소개했다. 전체 도구 스키마를 매 요청에 보내는 부담을 줄이는 기능으로, Interactions API에서 Gemini 3.6 이상과 모든 Gemini 4 모델을 지원한다.
  • 요청에 tool_search를 추가하고 지연 로딩할 도구에 defer_loading: true를 설정하면, 모델은 도구 이름과 설명만 먼저 확인한다. 필요한 도구를 이름으로 요청하면 API가 전체 매개변수 스키마를 불러오고 같은 요청 안에서 함수 호출을 생성한다.
  • 서버 측 검색은 별도 인덱스를 구축하거나 호스팅할 필요가 없다. 자주 쓰는 도구는 미리 로드하고 나머지는 지연 로딩할 수 있으며, prefix caching 및 원격 MCP 서버에도 적용할 수 있다.
  • 자체 도구 레지스트리·임베딩 인덱스·사용자별 권한 필터를 사용하는 경우 execution: client로 클라이언트 측 검색을 구성할 수 있다. 검색마다 왕복 통신이 한 번 추가되지만 도구를 미리 선언할 필요가 없어 대화 도중 새로운 도구를 제공할 수 있다.
  • Tool Retrieval의 별도 이용료는 없고 모델의 표준 입력·출력 토큰 요금이 적용된다. tool_search 자체의 소량 고정 입력 토큰과 로드한 스키마의 후속 대화 입력 비용이 발생하므로, 실제 절감 효과는 자체 트래픽으로 측정해야 한다.

🧩 주요 포인트

  1. 전체 스키마의 상시 전달에서 필요할 때 로딩하는 방식으로 전환 → 사용하지 않는 도구 스키마의 부담을 줄일 수 있지만, 토큰·지연 시간·선택 정확도의 개선 폭은 원문에 정량적으로 제시되지 않았다.
  2. 서버 측 검색과 클라이언트 측 검색 제공 → 별도 검색 인프라 없이 도입하거나 자체 레지스트리·사용자별 권한 필터를 활용할 수 있으며, 클라이언트 방식에는 검색당 추가 왕복 통신이 따른다.
  3. prefix caching·원격 MCP 서버 지원과 사용량 기반 과금 유지 → 기존 도구 연결에 적용할 수 있으나, 자주 쓰는 도구의 사전 로딩 여부와 실제 스키마 로딩량이 비용 판단의 핵심이다.

🧠 상세 정리

1. 대규모 도구 라이브러리의 부담과 프리뷰 공개

Google은 2026년 11월 19일 Gemini API의 Tool Retrieval을 소개하고, Interactions API에서 프리뷰로 사용할 수 있다고 밝혔다. 원문은 에이전트가 수십 개에서 수백 개의 도구에 연결될 때 모든 매개변수 스키마를 매 요청에 포함하면 입력 토큰과 지연 시간이 늘어나고, 후보가 많아지면서 도구 선택 정확도도 낮아진다고 설명한다. Tool Retrieval은 전체 도구 라이브러리를 대기 상태로 두고 현재 작업에 필요한 스키마만 불러오는 방식으로 이 문제에 대응한다. 입력 비용과 지연 시간을 줄이고 선택 정확도를 개선한다는 것이 소개의 핵심이지만, 개선 폭을 입증하는 정량적 비교 결과는 제시하지 않는다.

2. 이름과 설명을 먼저 제공하는 지연 로딩

Tool Retrieval을 활성화하려면 요청에 tool_search 도구를 추가하고, 나중에 불러올 도구에 defer_loading: true를 설정한다. 지연 로딩되는 도구도 이름과 설명은 모델에 보이므로, 모델은 매개변수 스키마 전체를 보지 않은 상태에서도 사용 가능한 도구를 파악할 수 있다. 작업에 특정 도구가 필요하면 모델이 이름으로 요청하고, API가 해당 도구의 전체 스키마를 불러온 뒤 모델이 함수 호출을 생성한다. 검색과 스키마 로딩, 함수 호출 생성은 모두 같은 요청 안에서 진행되며, 핵심은 도구의 존재를 알려 주는 정보와 실제 호출에 필요한 매개변수 정보를 나누어 제공한다는 점이다.

3. 호출 과정 확인과 서버 측 검색의 역할

원문의 환불 예제에서는 모델이 issue_refund를 검색하고, API가 스키마를 제공한 뒤 해당 함수의 호출을 생성하는 과정을 보여 준다. 이때 tool_search_call, tool_search_result, function_call의 세 단계가 interaction.steps에 나타나므로, 개발자는 모델이 어떤 도구를 요청했는지 살펴보고 도구 이름이나 설명을 디버깅할 수 있다. 이후 실제 환불 처리는 애플리케이션 코드가 실행하며, 그 결과를 function_result로 돌려주는 일반적인 함수 호출 흐름이 이어진다. 검색 자체는 Gemini가 서버에서 수행하므로 별도 인덱스를 구축하거나 호스팅할 필요가 없고, 자주 쓰는 도구는 처음부터 로드하면서 나머지 도구만 지연 로딩할 수도 있다.

4. prefix caching과 원격 MCP 서버 연동

Tool Retrieval은 prefix caching과 함께 사용할 수 있으며, 원문은 지연 로딩된 스키마가 프롬프트 앞부분에 포함되지 않는다는 점을 이유로 든다. 모델이 요청한 스키마는 대화의 뒤쪽에 추가되므로, 턴이 바뀌어도 캐시된 접두부가 동일하게 유지된다는 설명이다. 원격 MCP 서버에도 같은 방식이 적용되어, mcp_server 도구에 defer_loading: true를 설정하면 해당 서버가 노출하는 모든 도구를 필요할 때 불러올 수 있다. 따라서 많은 도구를 제공하는 서버에 연결할 때 각각을 일일이 나열할 필요가 없으며, 도구 스키마를 필요한 시점까지 미루는 원칙을 함수 도구와 MCP 서버 양쪽에 적용할 수 있다.

5. 자체 검색 체계를 활용하는 클라이언트 방식

자체 도구 레지스트리나 임베딩 인덱스, 사용자별 권한 필터를 유지하는 애플리케이션은 클라이언트 측 검색을 선택할 수 있다. 이 경우 tool_search에 execution: client를 지정하고 검색 매개변수를 정의하며, 검색 요청을 받은 애플리케이션이 일치하는 함수 스키마를 function_result로 반환한다. 조회를 애플리케이션이 수행하기 때문에 검색 한 번마다 왕복 통신이 한 번 추가된다는 제약이 있다. 대신 도구를 사전에 모두 선언할 필요가 없어, 사용자가 대화 도중 연동을 연결했을 때 새 도구를 제공할 수 있다. 원문은 이를 서버 측 검색과 구분하여 설명하며, 자체 검색·권한 체계를 활용할 수 있는 유연성과 추가 통신 비용을 함께 제시한다.

6. 과금 조건과 지원 모델

Tool Retrieval에는 별도 이용료가 없으며, 호출하는 모델의 표준 입력·출력 토큰 요금이 적용된다. 다만 tool_search를 켜면 소량의 고정 입력 토큰이 추가되고, 한 번 불러온 스키마는 처음부터 선언한 도구와 마찬가지로 남은 대화에서 입력으로 과금된다. 원문은 끝내 불러오지 않는 스키마가 불러오는 스키마보다 많을 때 토큰 절감이 발생하며 대규모 라이브러리에서는 이것이 일반적인 경우라고 설명하지만, 자체 트래픽으로 측정할 것을 권한다. 지원 범위는 Interactions API의 Gemini 3.6 이상이며 모든 Gemini 4 모델이 포함된다. 도입을 위한 후속 자료로는 예제가 포함된 설정 문서, 모델 비교 자료, Discord 논의 채널을 안내한다.

🧾 핵심 주장 / 시사점

  • 지연 로딩에서도 모든 도구의 이름과 설명은 모델에 제공되므로, 도구 선택에서 이 정보의 역할은 유지된다. 원문이 interaction.steps를 통한 이름·설명 디버깅을 강조하는 이유도 여기에 있다.
  • 클라이언트 측 검색은 자체 레지스트리와 사용자별 권한 필터를 활용할 수 있는 선택지이지만, 검색마다 추가 통신이 발생하므로 서버 측 검색과 지연 시간 조건이 다르다.
  • 별도 이용료가 없다는 사실만으로 총비용 감소가 보장되지는 않는다. 검색의 고정 토큰과 로드된 스키마의 지속적인 입력 과금을 함께 고려해야 실제 절감 여부를 판단할 수 있다.

✅ 액션 아이템

  • 자체 트래픽에서 Tool Retrieval 적용 전후의 입력 토큰·지연 시간·선택 정확도 비교.
  • 자주 쓰는 도구의 사전 로딩과 나머지 도구의 defer_loading: true 적용 범위 검토.
  • 자체 레지스트리·사용자별 권한 필터의 필요성과 검색당 추가 왕복 통신을 고려한 서버 측·클라이언트 측 검색 선택.

❓ 열린 질문

  • 자체 트래픽에서 Tool Retrieval의 입력 토큰·지연 시간·선택 정확도는 각각 얼마나 개선되는가?
  • 자주 쓰는 도구 중 무엇을 사전 로딩해야 실제 스키마 로딩량과 입력 비용을 줄일 수 있는가?
  • 자체 레지스트리·사용자별 권한 필터를 활용하는 이점은 클라이언트 측 검색의 추가 왕복 통신 부담을 상쇄하는가?

관련 문서

공통 태그와 주제 흐름을 기준으로 같이 보면 좋은 문서를 이어서 제안합니다.