Gemini API Tool Retrieval: tool_search, defer_loading y facturación

Activa Tool Retrieval en vista previa en la Gemini Interactions API (v1beta) con tool_search y defer_loading. Compara los modos de servidor y cliente, revisa los cuatro modelos documentados frente al blog de Google, gestiona MCP remoto y el reenvío sin estado, corrige errores frecuentes y evalúa la facturación de tokens y la caché implícita de prefijos.

Índice
Gemini API Tool Retrieval: tool_search, defer_loading y facturación

Tool Retrieval ya está en vista previa en la Gemini Interactions API (v1beta) y permite que tus agentes carguen bajo demanda los esquemas de parámetros de las herramientas con tool_search y defer_loading. Afecta a desarrolladores que conectan decenas de funciones personalizadas o servidores MCP remotos a Gemini, y solo funciona en la Interactions API (no en generateContent). Según el estado verificado al 2026-11-20, para probarlo llama a v1beta/interactions con uno de los cuatro modelos documentados (gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash o gemini-3.6-flash), añade {"type": "tool_search"} y configura defer_loading: true en las herramientas que quedan fuera de tu conjunto principal.

Elige primero la ruta de API adecuada

Google anunció Tool Retrieval el 19 de noviembre de 2026 en el blog de Google y publicó las instrucciones de configuración en la documentación de Tool retrieval de AI Studio. Como la función está limitada a la vista previa de la Interactions API (v1beta), tu endpoint actual define si puedes adoptarla de inmediato.

RutaCuenta y regiónUnidad de facturaciónSoporte de Tool RetrievalCuándo elegirla
Gemini Interactions API oficial (v1beta)Clave de API de Google AI Studio en una región admitida; gemini-4-argon requiere Paid TierPor cada 1M de tokens de entrada, en caché y de salida (Standard Free Tier disponible en gemini-4-hydrogen, gemini-3.8-flash y gemini-3.6-flash)Compatible en vista previa (tool_search, defer_loading, mcp_server remoto)Tienes una biblioteca grande de herramientas y puedes llamar directamente a v1beta/interactions
API oficial generateContent de GeminiMisma cuenta de Google AI Studio y región admitidaPor cada 1M de tokens de entrada, en caché y de salidaNo compatibleTienes menos de ~20 herramientas estables, necesitas caché explícita en modelos Gemini 3 o 2.5 compatibles, o aún no puedes migrar
Pasarela API de pago por uso (como BetterToken)Cuenta propia de BetterToken registrada por ti y clave de API creada en la consolaSaldo de pago por uso cobrado según la unidad de facturación vigente de cada modeloLa Interactions API no está documentada; el soporte de Tool Retrieval no está verificadoMantienes endpoints documentados de Gemini nativo generateContent o Chat Completions compatibles con OpenAI entre varios modelos (revisa el soporte de herramientas por modelo en la documentación de BetterToken)

Si prefieres seguir usando el endpoint estándar generateContent de Gemini o Chat Completions compatible con OpenAI en lugar de migrar a la Interactions API, puedes consultar la referencia de la API de Gemini en BetterToken para revisar los endpoints documentados, los ID de modelo y el soporte de herramientas de cada modelo.

Modelos compatibles y el error 400 en Gemini 4

El blog de anuncio de Google del 19 de noviembre de 2026 afirma que Tool Retrieval funciona con Gemini 3.6 y modelos posteriores, incluidos todos los modelos Gemini 4, y enlaza a la página de últimos modelos Gemini. Esa página enumera cuatro modelos Gemini 4: gemini-4-carbon, gemini-4-neon, gemini-4-hydrogen y gemini-4-argon.

Sin embargo, al 2026-11-20, la lista oficial de modelos compatibles con Tool retrieval solo incluye cuatro ID de modelo:

  • gemini-4-hydrogen
  • gemini-4-argon
  • gemini-3.8-flash
  • gemini-3.6-flash

gemini-4-carbon y gemini-4-neon no figuran en la página de documentación de Tool Retrieval al 2026-11-20. Si envías defer_loading a un modelo no compatible, la API devuelve un error HTTP 400 con el mensaje deferred loading is not supported for this model.

Empieza tu integración con gemini-4-hydrogen, el modelo que Google utiliza en los ejemplos de Tool Retrieval; consulta nuestra guía de precios y migración de Gemini 4 Hydrogen si migras desde modelos Flash. Si tu flujo depende de gemini-4-carbon, comprueba el comportamiento real en v1beta antes de activar defer_loading, o revisa la guía de precios y migración de la API de Gemini 4 Carbon manteniendo la carga estática de herramientas.

Recuperación en el servidor frente a recuperación en el cliente

La Interactions API admite dos modos de recuperación mutuamente excluyentes: recuperación en el servidor (el modo predeterminado) y recuperación en el cliente (execution: "client"). Ambos mantienen los esquemas fuera del prompt inicial, pero se diferencian en latencia, configuración y registro de herramientas.

DimensiónCarga estática de herramientasRecuperación en el servidorRecuperación en el cliente
Cómo llegan los esquemas al modeloTodos se envían al principioGemini carga los esquemas diferidos bajo demandaTu aplicación devuelve los esquemas en function_result
Código de búsqueda que debes escribirNingunoNingunoBúsqueda, clasificación y filtrado propios
Herramientas declaradas al principioSíSíNo
Soporte de MCP remotoSíSí (defer_loading: true en mcp_server)No aplica
Ida y vuelta adicional de redNingunaNinguna (se ejecuta dentro de la misma llamada a la API)Una ida y vuelta por búsqueda
Mejor ajusteMenos de ~20 herramientas establesBibliotecas grandes pero fijas o varios servidores MCPRegistros propios, permisos por usuario, herramientas dinámicas a mitad de sesión

Solo puedes declarar una entrada tool_search por solicitud. Si combinas entradas tool_search de servidor y de cliente en la misma solicitud, recibirás el error Cannot specify both client-side and server-side tool_search tools..

Configura la recuperación en el servidor y MCP remoto

La recuperación en el servidor exige la versión v1beta de la API. Aunque el fragmento publicado en el blog de Google omite api_version, la guía oficial de Tool retrieval indica que la vista previa requiere v1beta: en Python, inicializa genai.Client(http_options={"api_version": "v1beta"}); en JavaScript, inicializa new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } }).

En Bash, carga tu clave de API de Gemini sin mostrarla en la terminal y envía una solicitud POST a https://generativelanguage.googleapis.com/v1beta/interactions. El ejemplo siguiente combina una función local diferida (convert_currency) con el servidor MCP de clima documentado por Google para demostraciones (https://gemini-api-demos.uc.r.appspot.com/mcp):

read -rs GEMINI_API_KEY && export GEMINI_API_KEY

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-4-hydrogen",
    "input": "Check the temperature in London and convert 100 USD to EUR.",
    "tools": [
      {"type": "tool_search"},
      {
        "type": "function",
        "name": "convert_currency",
        "description": "Convert an amount from one currency to another using live mid-market rates.",
        "short_description": "Convert an amount between currencies.",
        "defer_loading": true,
        "parameters": {
          "type": "object",
          "properties": {
            "amount": {"type": "number"},
            "from": {"type": "string"},
            "to": {"type": "string"}
          },
          "required": ["amount", "from", "to"]
        }
      },
      {
        "type": "mcp_server",
        "name": "weather_service",
        "url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
        "defer_loading": true
      }
    ]
  }'

Aplica cuatro reglas al construir el arreglo tools:

  • Deja sin definir name, description y parameters en un objeto tool_search del lado del servidor.
  • Envía el esquema parameters completo en cada function diferida. Los esquemas que aún no se cargan no se facturan, y una herramienta enviada sin parámetros regresa de una búsqueda con un esquema vacío que el modelo no puede invocar.
  • Usa el campo opcional short_description solo junto con defer_loading: true para reemplazar una description extensa en la lista compacta de herramientas diferidas.
  • Para servidores MCP remotos, conecta únicamente endpoints Streamable HTTP (los servidores SSE no están admitidos) y usa nombres en snake_case sin -, como documenta Remote MCP. Si tu servidor remoto falla en el intercambio inicial o en la validación de esquemas, revisa nuestra guía de resolución de problemas de integración con servidores MCP.

Verifica la respuesta del lado del servidor

Una respuesta correcta de recuperación en el servidor incluye pasos tool_search_call y tool_search_result dentro de steps en la misma llamada a la API, seguidos de la llamada real a la herramienta. En el caso de herramientas MCP remotas como get_weather en el servidor de demostración, la API también ejecuta la llamada remota y devuelve pasos mcp_server_tool_call y mcp_server_tool_result en la misma respuesta.

Para tus propias funciones, busca los elementos function_call directamente dentro de steps. No confíes únicamente en status == "requires_action", porque Google advierte que status no siempre toma el valor requires_action cuando hay un paso function_call. Ejecuta la función en tu entorno local y envía un function_result en el siguiente turno.

Configura la recuperación en el cliente

Usa execution: "client" cuando tu catálogo de herramientas depende de permisos de usuario, espacios de nombres internos o integraciones que se añaden después de iniciar la sesión. Tanto name como description son obligatorios en una definición tool_search del lado del cliente (omitir cualquiera devuelve un error 400), y no debes incluir defer_loading en ninguna herramienta de la solicitud.

El siguiente fragmento en Python es un ejemplo mínimo de protocolo que devuelve una declaración fija en lugar de consultar un registro en vivo. Confirma que el ciclo completo funciona cuando el script imprime un paso function_call para get_billing_history con {"user_id": 123} desde followup.steps:

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

tools = [
    {
        "type": "tool_search",
        "execution": "client",
        "name": "search_tool_registry",
        "description": "Search internal tool namespaces such as billing and support when needed.",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string"},
                "namespace": {"type": "string"},
            },
            "required": ["query"],
        },
    }
]

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Look up the billing history for user 123.",
    tools=tools,
)

for step in interaction.steps:
    if step.type == "function_call" and step.name == "search_tool_registry":
        # Minimal protocol example: replace with your own registry or permission filter.
        matches = [
            {
                "type": "function",
                "name": "get_billing_history",
                "description": "Retrieve billing history for a given user.",
                "parameters": {
                    "type": "object",
                    "properties": {"user_id": {"type": "integer"}},
                    "required": ["user_id"],
                },
            }
        ]
        followup = client.interactions.create(
            model="gemini-4-hydrogen",
            previous_interaction_id=interaction.id,
            tools=tools,
            input=[
                {
                    "type": "function_result",
                    "name": step.name,
                    "call_id": step.id,
                    "result": matches,
                }
            ],
        )
        for next_step in followup.steps:
            if next_step.type == "function_call":
                print(next_step.name, next_step.arguments)

Devuelve declaraciones completas de funciones como objetos JSON dentro del arreglo function_result.result, nunca como una cadena JSON serializada, e incluye los valores name y call_id que coinciden con la llamada function_call de búsqueda. Si tu búsqueda en el cliente no encuentra coincidencias, devuelve un resultado breve de texto indicando que no hubo coincidencias y qué categorías puede buscar el modelo para ajustar su consulta.

Estado multiturno, reenvío sin estado y errores frecuentes

Tres restricciones de la vista previa provocan la mayoría de los fallos de integración a partir del primer turno:

  • Reenvía el arreglo tools completo en cada solicitud. La Interactions API guarda el historial de pasos cuando pasas previous_interaction_id, pero no conserva las declaraciones de herramientas entre solicitudes. Omitir herramientas en turnos posteriores hace que el modelo pase por alto funciones no declaradas o emita llamadas internas retriever: en modo servidor.
  • Las herramientas cargadas no se pueden descargar y una búsqueda sin resultados devuelve texto. Una vez que el modelo carga una herramienta, su esquema permanece en el contexto durante el resto de la conversación. Si una consulta del servidor no coincide con ninguna herramienta diferida, la API responde con texto plano en vez de un error estructurado de recuperación, por lo que no debes depender de tool_search_result para detectar ausencias.
  • Reenvía los pasos y las firmas tal cual cuando store=false. En cada seguimiento sin estado, envía el historial completo de pasos en input y reenvía el arreglo tools completo en el nivel superior de la solicitud. Añade cada paso de la respuesta (tool_search_call, tool_search_result, thought y function_call) sin modificar, en su orden original y con su signature intacta, seguido del nuevo function_result. Enviar solo function_result descarta el contexto de recuperación y provoca un error 400. Usa una versión del SDK que reconozca tool_search_call y tool_search_result, ya que las versiones anteriores los interpretan como pasos desconocidos y eliminan sus campos. Mantén sin diferir cualquier herramienta nombrada en las instrucciones del sistema o en la salida de otra herramienta; de lo contrario, el modelo puede invocarla sin buscarla y fallar al recibir function_result.

Google documenta respuestas HTTP 400 para modelos no compatibles, falta de tool_search de servidor al usar defer_loading, uso de short_description sin defer_loading: true, omisión de name o description en modo cliente, pasos sin estado omitidos y valores signature eliminados. Usa la siguiente tabla para asociar cada mensaje documentado con su causa y solución:

Mensaje de error documentadoCausaSolución
deferred loading is not supported for this modelSe envió defer_loading a un modelo fuera de la lista compatibleCambia a gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash o gemini-3.6-flash
tool_search tool must be specified when using defer_loading.Una herramienta function o mcp_server establece defer_loading: true sin ninguna herramienta tool_search en la solicitudAñade {"type": "tool_search"} o quita defer_loading
When defer_loading is set on a FunctionDeclaration, a Tool with tool_search must also be provided in the request.Una función tiene defer_loading: true sin un tool_search del lado del servidor (por ejemplo, solo se declaró execution: "client" o una solicitud posterior omitió tool_search)Quita defer_loading en modo cliente o reenvía el arreglo tools completo incluyendo {"type": "tool_search"}
Cannot specify both client-side and server-side tool_search tools.La solicitud incluye tanto un tool_search de servidor como uno de clienteDeclara exactamente una entrada tool_search por solicitud
ToolSearch name must not be specified when execution mode is SERVER_SIDE.Un tool_search del lado del servidor define name (se devuelve el mismo error para description y parameters)Elimina el campo; si cambias a execution: "client", incluye tanto name como description y quita defer_loading de todas las herramientas
short_description can only be set if defer_loading is trueUna función define short_description sin defer_loading: trueAñade defer_loading: true o elimina short_description
Server side tool call context must be circulated when using deferred loading functions.En una solicitud sin estado, el historial incluye un function_result de una herramienta diferida sin los pasos tool_search_call y tool_search_result que la cargaronReenvía sin cambios cada paso tool_search_call y tool_search_result, incluida su signature
Server side tool call context must be circulated ... Missing circulated context for functions: FUNCTION_NAME (incluso reenviando todos los pasos)El modelo invocó una función diferida que ningún tool_search cargó, por lo general porque su nombre apareció en las instrucciones del sistema o en la salida de otra herramientaMantén sin diferir las herramientas mencionadas por su nombre
Tool call part is missing thought_signature. / Tool response part is missing thought_signature.En una solicitud sin estado, se reenvió un paso tool_search_call (llamada) o tool_search_result (respuesta) sin su campo signatureReenvía ambos pasos de recuperación sin cambios y con sus valores signature intactos

Campos de facturación, caché de prefijos y punto de equilibrio

Tool Retrieval en sí no tiene ningún cargo separado. Cada token se factura según las tarifas estándar de entrada, caché y salida del modelo que llamas, publicadas en la página de precios de la Gemini API. Según las tarifas verificadas al 2026-11-20, gemini-4-hydrogen cuesta $1.50 por 1M de tokens de entrada, $0.075 por 1M de tokens de entrada en caché y $7.50 por 1M de tokens de salida (incluidos los tokens de pensamiento) en Paid Tier. gemini-4-hydrogen, gemini-3.8-flash y gemini-3.6-flash cuentan con Standard Free Tier, mientras que gemini-4-argon solo está disponible en Paid Tier a $2.00 de entrada, $0.10 en caché y $10.00 de salida por 1M de tokens hasta el 30 de noviembre de 2026, subiendo a $4.00 / $0.20 / $20.00 a partir del 1 de diciembre de 2026.

Revisa cinco campos dentro de usage en cada respuesta de interacción para controlar el consumo de tokens:

  • total_input_tokens: el prompt de la primera llamada al modelo dentro de la solicitud, incluidos tu entrada, el historial de conversación, las instrucciones del sistema, los esquemas de herramientas no diferidas, el pequeño bloque fijo de instrucciones de tool_search y las entradas de una línea de herramientas diferidas (name más short_description o la primera oración de description, alrededor de 26 tokens por herramienta diferida en las pruebas iniciales de Google).
  • total_tool_use_tokens: los prompts de las llamadas adicionales al modelo que la API ejecuta dentro de la misma solicitud tras correr una herramienta del servidor, incluida cada búsqueda en el servidor. Cada llamada reenvía el contexto completo junto con los esquemas recién cargados y se cobra a tarifa de entrada; varias búsquedas en un mismo turno suman varias pasadas.
  • total_cached_tokens: la parte del prompt servida desde la caché implícita, facturada a la tarifa de caché en lugar de la tarifa de entrada.
  • total_output_tokens: tokens de respuesta generados, facturados a tarifa de salida.
  • total_thought_tokens: tokens de pensamiento generados, facturados a tarifa de salida.

Advertencia sobre el umbral de la caché de prefijos

Según Context caching, la Interactions API solo admite caché implícita; la caché explícita no está disponible ni en la Interactions API ni en los modelos Gemini 4. Como los esquemas recuperados se insertan en el punto donde el modelo los carga y no al inicio del prompt, tus instrucciones del sistema, la lista de herramientas y los turnos anteriores mantienen un prefijo estable entre solicitudes. Cuando ese prefijo supera el tamaño mínimo almacenable en caché del modelo, las solicitudes posteriores de la conversación, incluida la llamada adicional de cada búsqueda en el servidor, pueden servirse desde la caché implícita y aparecer en total_cached_tokens.

Sin embargo, según lo verificado al 2026-11-20, los cuatro modelos compatibles con Tool Retrieval exigen un mínimo de 4,096 tokens de entrada para activar la caché implícita. Si tu prompt solo superaba los 4,096 tokens debido a los esquemas completos de herramientas, diferir esas herramientas puede dejar la solicitud por debajo del mínimo cacheable. En conversaciones multiturno y bucles de agentes con modelos Gemini 4, Gemini guarda en caché toda la solicitud anterior solo si la nueva añade al menos 2,050 tokens (cuentan la salida del modelo, el pensamiento y los resultados de funciones); con incrementos menores, Gemini reprocesa los últimos 2,050 tokens de la solicitud previa a la tarifa estándar de entrada.

Cuándo Tool Retrieval ahorra tokens y cuándo cuesta más

La documentación de Google incluye una estimación ilustrativa de dos solicitudes (con cifras redondeadas y sin contar tokens de salida ni caché) en la que el modelo carga dos herramientas de 400 tokens y devuelve un function_call en la respuesta de la solicitud 1, seguido del envío de function_result por tu aplicación en la solicitud 2:

Escenario ilustrativo (estimación en documentación de Google)Carga estática (tokens de entrada)Tool retrieval (tokens de entrada + uso de herramientas)Resultado neto
200 herramientas (400 tokens cada una), contexto de 2,000 tokens2 × (2,000 + 80,000) = 164,000Solicitud 1: 7,350 + pasada de búsqueda 8,150; Solicitud 2: 8,150 = ~23,650Ahorra ~86% de los tokens del lado de entrada
10 herramientas (400 tokens cada una), contexto de 30,000 tokens2 × (30,000 + 4,000) = 68,000Solicitud 1: 30,410 + pasada de búsqueda 31,210; Solicitud 2: 31,210 = ~92,830Cuesta ~37% más en tokens del lado de entrada

Diferir herramientas compensa cuando tu biblioteca es grande y la mayoría de los turnos solo usan unas pocas funciones. Con un conjunto pequeño de herramientas o en conversaciones largas que buscan casi en cada turno, la pasada adicional de búsqueda en el servidor (total_tool_use_tokens) puede superar el ahorro. Mantén cargadas desde el principio tus herramientas más frecuentes, difiere el resto y mide total_input_tokens, total_tool_use_tokens y total_cached_tokens en tu tráfico real junto con el gasto facturado antes de desplegar el cambio a gran escala.

¿Quieres optimizar tu flujo de trabajo con LLM?

Conecta modelos mediante una API, gestiona claves y controla el gasto en IA.

Empezar gratis