Gemini Tool Retrieval을 연동하려면 세 가지 작업이 필요해요. 첫째, tools 배열에 {"type": "tool_search"}를 추가하고, 호출 빈도가 낮은 업무 함수에 defer_loading: True를 설정해요. 둘째, v1beta 버전의 Interactions API로 요청을 보낸 뒤 interaction.steps에서 function_call을 찾아요. 셋째, 로컬에서 함수를 실행하고 call_id를 기준으로 function_result를 구성한 다음, 전체 tools 배열을 함께 담아 되돌려 보내요. 이 과정에서 도구 검색기를 직접 작성할 필요는 없어요. 서버 측에서 도구 검색과 파라미터 스키마 로딩을 처리해 주거든요.
먼저 분명히 해둘게요: Tool Retrieval은 ‘도구 파라미터 정의가 언제 모델 컨텍스트에 들어가는지’만 바꿀 뿐, 함수는 여전히 개발자가 실행해야 해요. 비용 절감을 보장하지도 않아요. 도구 수가 적고 컨텍스트가 긴 상황에서는 오히려 토큰 소비가 늘어날 수 있어요.
이 글을 읽고 무엇을 알 수 있나요?
- Gemini Tool Retrieval이 어떤 모델을 지원하는지, 어떤 SDK 버전이 필요한지, 그리고 왜
v1beta를 명시해야 하는지 - 변수명이 앞뒤로 일관된 Python 전체 예제: 재고와 주문 두 개의 지연 로딩 도구를 검색부터 최종 답변까지
tool_search_call,tool_search_result,function_call,function_result를 각각 누가 처리하는지- 원격 MCP 지연 로딩, 클라이언트 검색, 자체 Tool Registry라는 세 가지 확장 경로의 차이
- HTTP 400 등 흔한 오류를 한곳에서 점검하는 방법, 그리고 도입 전에 비용 효율을 판단하는 방법
구성 안내: 먼저 To Know 표로 핵심 필드를 설명하고, 이어서 ‘영향 요약’에서 이 프리뷰 기능이 각 역할에 어떤 의미인지 짚어요. ‘객관적 사실’ 부분은 연동 순서대로 펼쳐요: 환경 준비, 도구 정의, 검색 단계 확인, 함수 결과 반환, 마지막으로 MCP와 클라이언트 검색으로 확장하고, 오류 점검은 이 부분 끝에 모아 두었어요. ‘분석과 판단’ 부분에서는 Google이 제시한 두 가지 가상 계산 예시를 바탕으로 Tool Retrieval이 적합한 상황과 그렇지 않은 상황을 논의해요.

Gemini Tool Retrieval 핵심 개념 (To Know)
| 개념 | 간단한 설명 |
|---|---|
| google-genai | Google 공식 Python SDK 패키지 이름. 임포트 방식은 from google import genai예요 |
| v1beta | 프리뷰 API 버전으로, Tool Retrieval에서 반드시 사용해야 해요. 이 글에서는 클라이언트 초기화 시 명시적으로 지정합니다 |
| Interactions API | Google이 Agent 워크플로를 위해 제공하는 API로, 상태를 유지하는 대화와 관찰 가능한 실행 단계를 지원해요 |
tool_search |
도구 검색 활성화를 선언하는 특수 도구 유형으로, 요청당 최대 하나만 사용할 수 있어요 |
defer_loading |
지정한 함수나 MCP 서버의 전체 파라미터 정의가 모델 컨텍스트에 늦게 들어가도록 지연시키는 옵션이에요 |
short_description |
모델이 처음에 볼 수 있는 지연 함수의 간단한 설명으로, 지연 함수에만 사용할 수 있어요 |
tool_search_call |
서버 측 검색 과정에서 모델이 시작하는 검색 단계예요 |
tool_search_result |
서버가 일치하는 도구의 전체 Schema를 반환하는 단계예요 |
function_call |
모델이 개발자 코드에 특정 함수 실행을 요청하면서 파라미터를 함께 제공하는 것이에요 |
function_result |
애플리케이션이 함수 실행 결과를 모델에 돌려줄 때 사용하는 입력 유형이에요 |
call_id |
함수 실행 결과를 원래 function_call.id와 연결해 주는 식별자예요 |
previous_interaction_id |
이후 요청이 서버에 저장된 상호작용 기록을 이어받도록 하는 식별자예요 |
signature |
상태 없는 세션에서 이전 단계를 재생할 때, 원래 단계와 함께 그대로 되돌려 보내야 하는 서명 필드예요 |
Gemini Tool Retrieval 영향 한눈에 보기
| 대상 | 실제 영향 |
|---|---|
| Agent 개발자 | 도구가 많은 Agent는 롱테일 도구를 지연 로딩할 수 있어 벡터 검색을 직접 구축할 필요가 없지만, Interactions API로 전환해야 해요 |
| 이미 generateContent를 쓰는 팀 | 기존 방식은 Tool Retrieval을 지원하지 않아 인터페이스와 응답 구조 파싱을 마이그레이션해야 해요 |
| MCP 통합 담당자 | mcp_server 계층에서 defer_loading을 일괄 설정할 수 있어 도구를 하나하나 선언할 필요가 없어요 |
| 비용 책임자 | 별도 기능 요금은 없지만 서버 측 검색마다 추가 과금 모델 호출이 발생하므로 total_tool_use_tokens를 주의 깊게 봐야 해요 |
| 소규모 도구 라이브러리 프로젝트 | 도구가 십여 개 수준이고 컨텍스트가 긴 시나리오라면 오히려 손해일 수 있어 정적 로딩이 더 절약될 수 있어요 |
Gemini Tool Retrieval 객관적 사실: 출시 정보와 연동 절차
Gemini Tool Retrieval 출시 상태와 지원 모델
2026년 11월 19일(베이징 시간 11월 20일 새벽), Google은 공식 블로그에 《Introducing Tool Retrieval in the Gemini API》를 게시하고 Interactions API에서 Tool Retrieval 프리뷰를 오픈했어요. 글쓴이는 Gemini API 제품 매니저 Lucia Loher와 Google DeepMind 연구 과학자 Nora Kassner예요. 현재 이 기능은 Preview 상태로, 정식 출시 전에 인터페이스가 조정될 수 있어요.
공지의 표현은 다소 넓어요. “Gemini 3.6 및 최신 모델, 모든 Gemini 4 모델 포함”. 하지만 개발 문서는 2026년 11월 20일 기준으로 4개 모델 ID만 명확히 나열하고 있어요: gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash, gemini-3.6-flash. 연동할 때는 문서 목록을 기준으로 삼아야 해요. 지원하지 않는 모델에 defer_loading을 설정하면 HTTP 400이 바로 반환돼요.
Gemini Tool Retrieval 연동 전 준비: SDK와 v1beta
Google 공식 Python SDK googleapis/python-genai는 2026년 11월 18일 v3.6.0을 출시하며 Tool Retrieval 및 함수 결과 관련 공개 Schema를 새로 추가했어요. 설치 명령은 다음과 같아요:
pip install -U "google-genai>=3.6.0"
export GEMINI_API_KEY="your-key" # 실제 키를 코드에 직접 작성하지 마세요
버전 번호에는 쉽게 빠지는 함정이 하나 있어요. SDK는 v3.0.0부터 Gemini Developer API 클라이언트가 기본적으로 v1을 사용하는데, Tool Retrieval은 v1beta를 요구해요. 그래서 초기화할 때 반드시 명시적으로 지정해야 해요:
from google import genai
client = genai.Client(
http_options={"api_version": "v1beta"}
)
SDK는 환경 변수 GEMINI_API_KEY에서 자격 증명을 읽어요. REST를 사용한다면 해당 Endpoint는 POST https://generativelanguage.googleapis.com/v1beta/interactions이고, 인증 헤더는 x-goog-api-key예요.
1단계: tool_search와 defer_loading으로 Gemini 도구 정의하기
데모 시나리오에는 비즈니스 도구가 딱 두 개예요. get_inventory는 상품 재고를 조회하고, get_order_status는 주문 상태를 조회하며, 둘 다 지연 로딩(defer_loading)으로 설정해요. tools 배열에서 각 필드의 역할은 다음과 같아요:
{"type": "tool_search"}: 서버 측 검색을 켜고, 기본execution은server예요. 이게 없이defer_loading을 설정하면defer_loading requires tool_search오류가 나요.defer_loading: True: 전체parameters가 초기 컨텍스트에 들어가지 않고, 모델은 처음에 이름과 간단한 설명만 보게 돼요.short_description: 초기 목록에 표시되는 짧은 설명이에요. 입력하지 않으면description의 첫 문장을 사용해요. 지연 로딩이 아닌 함수에 입력하면 유효하지 않은 것으로 판정돼요.parameters: 여전히 전체를 제출해야 해요. 지연되는 건 스키마가 모델 컨텍스트에 들어가는 시점이고, 서버는 여전히 완전한 정의를 받아야 해요.
어떤 도구가 지연 로딩에 적합할까요? Google은 혼합 사용을 권장해요. 빈도가 높은 도구는 직접 로딩을 유지하고, 빈도가 낮고 전문적인 롱테일 도구는 지연 로딩해요. 또한 시스템 지시에서 직접 이름을 언급하는 도구는 지연 로딩으로 설정하지 마세요. 그러지 않으면 모델이 검색을 우회해 바로 호출해서 로딩 컨텍스트가 빠진 채 오류가 날 수 있어요. 이름이 비슷한 도구에는 비즈니스 네임스페이스를 붙이는 것을 권장해요. 예를 들어 billing_get_customer와 crm_get_customer로 구분하고, 둘 다 get_customer라고 부르지 마세요.
2단계: 요청 보내기 및 Gemini 도구 검색 단계 확인
아래는 전체 데모 코드예요. 재고 “12개”와 주문 상태 demo_pending은 모두 로컬 시뮬레이션 데이터이며 실제 시스템을 조회하지 않아요. 코드를 실행하려면 유효한 Gemini API 키와 모델 접근 권한이 필요해요.
import json
from google import genai
MODEL = "gemini-4-hydrogen"
client = genai.Client(
http_options={"api_version": "v1beta"}
)
tools = [
{"type": "tool_search"},
{
"type": "function",
"name": "get_inventory",
"description": "Retrieve the available inventory for a product SKU.",
"short_description": "Check product inventory by SKU.",
"defer_loading": True,
"parameters": {
"type": "object",
"properties": {"sku": {"type": "string"}},
"required": ["sku"]
}
},
{
"type": "function",
"name": "get_order_status",
"description": "Retrieve the status of a customer order.",
"short_description": "Check an order's current status.",
"defer_loading": True,
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"]
}
}
]
def execute_demo_tool(name, arguments):
"""로컬 시뮬레이션용 비즈니스 함수로, 실제 재고나 주문을 조회하지 않아요."""
if name == "get_inventory":
return {"sku": arguments["sku"], "available": 12, "data_source": "local_demo"}
if name == "get_order_status":
return {"order_id": arguments["order_id"], "status": "demo_pending", "data_source": "local_demo"}
raise ValueError(f"Unknown tool: {name}")
# 첫 번째 요청: 모델이 필요한 도구를 찾아 선택합니다.
interaction = client.interactions.create(
model=MODEL,
input="查询商品 SKU-42 的可用库存。",
tools=tools
)
print("执行步骤:")
for step in interaction.steps:
print(step.type, getattr(step, "name", ""))
출력된 interaction.steps는 보통 다음 순서로 나타나요. 구체적인 순서와 검색 결과는 모델이 결정하며, 한 번의 실행에서 검색이 여러 번 일어날 수도 있어요.
tool_search_call: 모델이 현재 로드된 도구 중 적합한 것이 없다고 판단하면 서버 측 검색을 시작해요.tool_search_result: API가 일치하는get_inventory의 전체 파라미터 스키마를 반환해요.function_call: 모델이 스키마를 읽은 뒤get_inventory(sku="SKU-42")같은 호출을 생성해요.
이 세 단계는 같은 외부 API 요청 안에서 일어나요. 애플리케이션에서 별도의 검색기를 작성하거나 검색 요청을 다시 보낼 필요가 없어요. 처음 두 단계는 그저 관찰하고 기록하면 되고, 로컬에서 검색을 반복 실행하지 마세요. 그런데 “같은 요청”이라고 해서 “추론을 한 번만 실행한다”는 뜻은 아니에요. 서버 측 검색이 일어날 때마다 추가 모델 호출이 발생하고, 이 토큰은 평소처럼 과금돼요. 디버깅할 때 주의할 점도 있어요. interaction.status만 보고 판단하면 안 돼요. 상태가 requires_action이 아니더라도 steps 안에 실행 대기 중인 function_call이 들어 있을 수 있어요.

세 번째 단계: 함수 실행 및 function_result 반환
Tool Retrieval은 도구를 찾고 매개변수를 채우는 역할만 담당하며, 실제 비즈니스 함수는 여전히 애플리케이션이 실행합니다. 이 부분은 표준 Function Calling 메커니즘을 그대로 따릅니다. 앞선 코드에 이어서 작성해 볼게요:
# 실제 비즈니스 함수 호출만 실행하고, 애플리케이션 측에서는 tool_search_call을 실행하지 않습니다
function_results = []
for step in interaction.steps:
if step.type != "function_call":
continue
result = execute_demo_tool(step.name, step.arguments)
function_results.append({
"type": "function_result",
"name": step.name,
"call_id": step.id,
"result": [{"type": "text", "text": json.dumps(result, ensure_ascii=False)}]
})
# 로컬 함수 결과를 Gemini로 다시 전송합니다
if function_results:
followup = client.interactions.create(
model=MODEL,
previous_interaction_id=interaction.id,
tools=tools,
input=function_results
)
print("最终回答:", followup.output_text)
else:
print("当前回答:", interaction.output_text)
이 코드에서 주의할 점은 세 가지입니다. 첫째, call_id는 반드시 원본 function_call의 step.id에서 가져와야 합니다. 한 라운드에 여러 호출이 있을 때 모델은 이 값으로 각 결과를 대응시킵니다. 둘째, previous_interaction_id=interaction.id는 서버 측이 이미 저장된 상호작용 기록을 이어가도록 하며, 여기에는 이미 검색된 도구도 포함됩니다. 셋째, 두 번째 라운드에서도 전체 tools 배열을 전달해야 합니다. API는 단계 이력을 보존하지만 도구 선언은 보존하지 않으므로, tool_search, 모든 지연·비지연 도구, MCP 설정을 매 라운드마다 다시 제출해야 합니다.
이 예시는 한 번의 함수 호출 폐쇄 루프만 보여주며, 범용적인 다중 라운드 Agent 스케줄러는 포함하지 않습니다. 만약 followup에 여전히 function_call이 있다면 같은 방식으로 계속 처리하면 됩니다.
🎯 기술 제안: Tool Retrieval 자체는 Google 공식
v1betaInteractions API에 의존합니다. 만약 표준 Function Calling으로 먼저 비즈니스 함수를 실행해 보고, 여러 모델이 도구 선택과 매개변수 채우기에서 보이는 성능을 비교하고 싶다면, APIYI apiyi.com에서 동일한 키로 Gemini, Claude, GPT 등의 모델을 전환하며 베이스라인 테스트를 진행할 수 있습니다.
확장: 원격 MCP와 Gemini 클라이언트 검색
원격 MCP 서버는 서버 계층에서 지연 로딩을 설정할 수 있으며, 노출되는 도구는 필요에 따라 로드돼요:
mcp_tools = [
{"type": "tool_search"},
{
"type": "mcp_server",
"name": "weather_service",
"url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
"defer_loading": True
}
]
커스텀 함수와 달리, 원격 MCP 도구는 API가 대신 실행하며, steps에 나타나는 것은 mcp_server_tool_call과 mcp_server_tool_result이고, 애플리케이션은 결과를 다시 전송할 필요가 없어요. 공식 문서에는 현재 ‘최대 지연 가능 도구 수’가 제시되어 있지 않아요.
기업이 이미 자체 도구 레지스트리, 벡터 검색 또는 사용자 수준 권한 필터링을 갖추고 있다면 클라이언트 검색으로 전환할 수 있어요: "execution": "client"로 설정하고, 완전한 name, description, parameters를 제공하세요. 이때 첫 번째 라운드에서 반환되는 것은 search_tool_registry에 대한 일반 function_call이에요. 애플리케이션이 검색한 후, function_result.result에 완전한 도구 선언 객체 배열을 반환해야 하며, 하나의 JSON 문자열로 직렬화하지 마세요. 클라이언트 모드에서는 defer_loading을 사용하지 않으며, 동일한 요청에서 두 가지 모드를 혼용할 수 없어요.

| 차원 | 서버 측 검색 | 클라이언트 측 검색 (Gemini) | 자체 Tool Registry (범용 방안) |
|---|---|---|---|
| 검색 실행 주체 | Gemini API | 개발자 애플리케이션 | 개발자 애플리케이션 |
| 핵심 설정 | tool_search + defer_loading |
tool_search + execution: client |
일반 Function Calling |
| 모든 도구를 미리 선언해야 하는지 | 필요 | 불필요 | 불필요 |
| 추가 네트워크 왕복 | 없음 | 검색마다 +1 라운드 | 검색마다 +1 라운드 |
| 동적 도구 추가 | 불편 | 지원 | 지원 |
| 전형적 시나리오 | 대형·상대적으로 고정된 도구 라이브러리 | 멀티테넌트, 프라이빗 레지스트리 | 크로스 모델 재사용, 다중 벤더 전환 |
| 사용 가능 플랫폼 | Google 공식 v1beta | Google 공식 v1beta | APIYI apiyi.com 등 OpenAI 호환 인터페이스 |
마지막 열은 Gemini Tool Retrieval이 아니라, 사고방식이 유사한 엔지니어링 구현이에요: 먼저 검색 함수 하나만 노출하고, 검색에 맞으면 해당 Schema를 tools에 추가하는 방식이에요. 이는 여러 모델 사이를 전환해야 하는 팀에 적합해요. 최소 작성법은 다음과 같아요:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["APIYI_API_KEY"],
base_url="https://api.apiyi.com/v1" # APIYI OpenAI 호환 인터페이스
)
MODEL = "your-model-name" # 플랫폼 모델 목록 기준
search_tool = {"type": "function", "function": {
"name": "search_tool_registry",
"description": "Search internal business tools by keyword.",
"parameters": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}}}
자체 Tool Registry의 전체 2단계 호출 보기
import json, os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["APIYI_API_KEY"],
base_url="https://api.apiyi.com/v1"
)
MODEL = "your-model-name" # 플랫폼 모델 목록을 기준으로 함
TOOL_REGISTRY = {
"get_inventory": {"type": "function", "function": {
"name": "get_inventory",
"description": "Retrieve the available inventory for a product SKU.",
"parameters": {"type": "object", "properties": {"sku": {"type": "string"}}, "required": ["sku"]}}},
"get_order_status": {"type": "function", "function": {
"name": "get_order_status",
"description": "Retrieve the status of a customer order.",
"parameters": {"type": "object", "properties": {"order_id": {"type": "string"}}, "required": ["order_id"]}}},
}
search_tool = {"type": "function", "function": {
"name": "search_tool_registry",
"description": "Search internal business tools (inventory, orders) by keyword.",
"parameters": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}}}
def search_registry(query):
q = query.lower()
return [name for name, t in TOOL_REGISTRY.items()
if any(w in t["function"]["description"].lower() for w in q.split())]
def execute_demo_tool(name, args):
if name == "get_inventory":
return {"sku": args["sku"], "available": 12, "data_source": "local_demo"}
if name == "get_order_status":
return {"order_id": args["order_id"], "status": "demo_pending", "data_source": "local_demo"}
raise ValueError(name)
messages = [{"role": "user", "content": "查询商品 SKU-42 的可用库存。"}]
tools = [search_tool]
for _ in range(4): # 간단한 루프 상한, 무한 루프 방지
resp = client.chat.completions.create(model=MODEL, messages=messages, tools=tools)
msg = resp.choices[0].message
if not msg.tool_calls:
print("最终回答:", msg.content)
break
messages.append(msg)
for call in msg.tool_calls:
args = json.loads(call.function.arguments)
if call.function.name == "search_tool_registry":
names = search_registry(args["query"])
tools += [TOOL_REGISTRY[n] for n in names if TOOL_REGISTRY[n] not in tools]
content = json.dumps({"loaded_tools": names})
else:
content = json.dumps(execute_demo_tool(call.function.name, args), ensure_ascii=False)
messages.append({"role": "tool", "tool_call_id": call.id, "content": content})
💡 선택 가이드: 레지스트리 방식의 검색 품질은 여러분이 작성한 검색 함수에 달려 있어요. 예시에 나온 키워드 매칭은 데모용일 뿐이에요. APIYI apiyi.com에서 모델을 바꿔 가며 같은 작업 세트를 실행해 보고, “올바른 도구를 찾았는지”와 “파라미터를 제대로 채웠는지”를 비교해 보면 어떤 모델이 여러분의 도구 라이브러리에 더 잘 맞는지 금방 알 수 있어요.
Gemini Tool Retrieval 자주 발생하는 오류 집중 점검
| 현상 | 원인 | 처리 |
|---|---|---|
defer_loading requires tool_search |
지연 함수를 선언했지만 서버 쪽 tool_search가 없음 |
tools에 {"type": "tool_search"} 추가 |
short_description이 유효하지 않음 |
지연 함수가 아닌 함수에 작성함 | defer_loading=True인 함수에만 사용 |
| HTTP 400 unsupported model | 모델이 지원 목록에 없음 | 문서에 나온 4개 모델 ID로 변경 |
| 요청이 적용되지 않거나 버전 오류 발생 | SDK가 기본으로 v1을 사용하거나 generateContent를 호출함 |
api_version="v1beta"를 명시하고 Interactions API로 전환 |
| 두 번째 요청 HTTP 400 | store=False일 때 검색 단계나 signature를 누락함 |
tool_search_call/result와 모든 signature를 그대로 재생 |
| 모델이 이전 도구를 잘못 사용하거나 도구를 사용할 수 없음 | 후속 요청에 tools를 빠뜨림 |
매 라운드 전체 tools 배열을 다시 제출 |
| 검색 후 파라미터가 비어 있음 | 지연 도구에 이름과 간단한 설명만 제출함 | 지연 도구에도 전체 parameters를 제출 |
| 클라이언트 검색 구성 실패 | name, description 등 필드 누락 |
클라이언트 검색 함수 정의를 보완 |
무상태 모드(store=False)는 별도로 설명해야 해요. 이때는 previous_interaction_id에 의존할 수 없고, 앱이 사용자 입력, tool_search_call, tool_search_result, function_call, function_result 및 모든 signature를 직접 저장한 뒤 그대로 재생해야 해요. 이 중 어느 한 단계라도 삭제하거나 수정하면 서버가 검색 컨텍스트를 재구성하지 못할 수 있어요. 또한 서버가 일치하는 도구를 찾지 못하면 구조화된 오류 대신 텍스트를 바로 반환할 수 있어요. 따라서 ‘요청에 오류가 없었다’가 ‘검색에 성공했다’를 의미하지는 않아요. 검증할 때는 steps에 예상한 검색 단계와 함수 호출이 나타나는지 항목별로 확인해야 해요.
Gemini Tool Retrieval 분석과 판단: 언제 도입할 가치가 있을까
판단 1: 효과는 도구 라이브러리 규모와 컨텍스트 길이에 달려 있어요. 켠다고 무조건 절약되는 건 아니에요. Google 문서는 서로 반대 방향의 가상 계산 예시 두 가지를 제시하면서, 이게 프로덕션 벤치마크가 아니라고 분명히 밝히고 있어요. 첫 번째는 도구 200개, 각 400 토큰, 기본 컨텍스트 2,000 토큰, 요청 2회를 가정한 경우로, 정적 로딩이 약 164,000 토큰, Tool Retrieval이 약 23,650 토큰이니 약 85.6% 감소한다고 계산했어요. 두 번째는 도구 10개, 기본 컨텍스트 30,000 토큰으로, 정적 로딩이 68,000 토큰인데 Tool Retrieval은 오히려 92,830 토큰이 되어 약 36.5% 늘어나요. 이유는 추가 검색 추론이 긴 컨텍스트 전체를 다시 처리해야 하기 때문이에요. Google의 엔지니어링 권고는 “안정적인 도구가 약 20개 미만이면 보통 정적 로딩으로 충분하다”는 거예요.

판단 2: 비용 평가는 total_tool_use_tokens를 봐야 해요. 첫 턴 입력만 보면 안 돼요. 공식 초기 테스트에서 지연 로딩 도구 하나의 간략 설명은 평균 약 26 토큰을 차지했고, 도구 100개면 약 2,600 토큰이에요. 이건 근사치예요. 정말로 주시해야 할 것은 검색이 유발하는 추가 모델 호출과, 세션 안에서 이미 로딩된 스키마가 누적되는 부분이에요. 현재 문서에는 검색된 도구를 언로드하는 메커니즘이 없어요. 긴 세션에서 검색한 도구가 많아질수록 컨텍스트는 커져요. 캐시도 무조건 이득은 아니에요. 초기 프롬프트가 짧아지면 암시적 캐시의 최소 임계값 아래로 내려갈 수 있거든요.
판단 3: 필요할 때 도구를 로딩하는 방식은 이미 업계 합의지만, 각 사 데이터를 가로로 적용할 수는 없어요. Anthropic은 2025년 11월에 Tool Search Tool을 출시했고, OpenAI는 2026년 3월에 GPT-5.4와 함께 Tool Search를 선보였어요. 두 회사 모두 자사 조건에서 측정한 절감 데이터를 공개했죠. 이번 Google은 가상 계산 예시만 내놓았어요. 2026년 11월 20일 기준으로 검증 가능한 Gemini Tool Retrieval 독립 프로덕션 실측은 아직 없어요. 그래서 “Gemini 실측 85% 절감” 같은 주장은 현재 근거가 없어요.
개발자를 위한 제안: 먼저 기존 에이전트의 도구를 호출 빈도로 계층화하세요. 고빈도 도구는 직접 로딩하고 롱테일 도구는 지연 로딩하는 식이에요. 그다음 같은 작업 묶음으로 정적 로딩과 Tool Retrieval의 총 토큰, 엔드투엔드 소요 시간, 도구를 올바르게 선택한 비율, 파라미터 정확도를 비교해 보세요. 기능은 아직 프리뷰 단계이고 정식 출시 시점도 정해지지 않았으니, 프로덕션에서는 정적 로딩으로 되돌릴 수 있는 스위치를 남겨두는 게 좋아요. 모델 선정 단계에서는 APIYI apiyi.com의 통합 인터페이스로 표준 Function Calling 베이스라인을 저비용으로 먼저 돌려보고, 그다음 공식 v1beta로 옮겨 Tool Retrieval의 순이익을 검증할 수 있어요.
도구가 많을수록 어떤 도구를 언제 꺼낼지 먼저 생각해야 해요. 《논어·위령공》에서 말했듯이 “일을 잘하려면 먼저 도구를 잘 벼려야 한다”고 하잖아요.
📚 참고 자료
-
Introducing Tool Retrieval in the Gemini API: Google 공식 발표 공지
- 링크:
blog.google/innovation-and-ai/technology/developers-tools/gemini-api-tool-retrieval - 설명: 발표일, 설계 목표, MCP 및 두 가지 검색 모드
- 링크:
-
Tool Retrieval 공식 문서: 설정, 제한, 과금 및 산출 예시
- 링크:
aistudio.google.com/docs/tool-retrieval - 설명: 이 문서의 코드, 오류 규칙, 무상태 재생 및 Token 산출 예시의 주요 근거
- 링크:
-
Function Calling 공식 문서: 함수 실행 및 결과 반환
- 링크:
aistudio.google.com/docs/function-calling - 설명:
function_result와call_id의 표준 사용법
- 링크:
-
Interactions API 공식 문서: 인터페이스 구조 및 실행 단계
- 링크:
aistudio.google.com/docs/interactions-overview - 설명: 상태 저장 대화, steps 와 generateContent 의 차이
- 링크:
-
python-genai v3.6.0 / v3.0.0 Release: SDK 버전 기록
- 링크:
github.com/googleapis/python-genai/releases - 설명: Tool Retrieval Schema 지원 및 기본 API 버전 변경
- 링크:
작성자: APIYI 기술 팀
기술 교류: 멀티 모델 Function Calling 비교 테스트는 APIYI apiyi.com 에서 확인할 수 있으며, 더 많은 연동 자료는 docs.apiyi.com 문서 센터에서 확인하세요
