Llamada a funciones con Gemini 3.8 Flash: call_id, bucles iterativos de herramientas y cómo probarlos

Gemini 3.8 Flash: llamadas iterativas a herramientas con la API de interacciones

Gemini 3.8 Flash se lanzó el 2 de septiembre de 2026. Google lo diseñó para «llamar a herramientas iterativamente»: en tareas complejas, realiza una llamada, verifica el resultado y hace otra si es necesario, en lugar de intentar adivinarlo todo de una vez. Esto beneficia a los agentes, pero puede romper ciclos de herramientas ajustados para Gemini 3.7 Flash. Los dos cambios más importantes son que cada resultado de función debe incluir call_id y name, y que la API de interacciones —no generateContent— es ahora la vía principal para ejecutar el ciclo.

Prueba Apidog hoy

Esta guía muestra el flujo completo de dos turnos, compara la API heredada de generateContent, explica por qué Gemini 3.8 Flash puede consumir más turnos y tokens, y termina con una prueba diaria que simula el backend de una herramienta y verifica el recorrido de call_id.

Todas las solicitudes utilizan HTTP y JSON planos, así que puede construirlas y depurarlas en Apidog antes de integrarlas en su aplicación.

Si necesita una introducción al modelo, consulte qué es Gemini 3.8 Flash.

Gemini 3.8 Flash de un vistazo

Elemento	Gemini 3.8 Flash
ID del modelo	gemini-3.8-flash — estable, sin sufijo de vista previa
API principal	API de interacciones (POST /v1beta/interactions); generateContent es heredada, pero totalmente compatible
Declaración de herramienta	tools: [{"type": "function", "name", "description", "parameters"}]
Llamada del modelo	Paso function_call con id, name y arguments
Resultado de la herramienta	function_result con call_id y name — ambos obligatorios — más previous_interaction_id
Razonamiento	thinking_level: low, medium — predeterminado — o high; minimal devuelve un error de validación
Puntuación de uso de herramientas	Tau3-Banking: 45 %, 12 puntos más que 3.7 Flash, según Artificial Analysis
Consumo	Aproximadamente 48.000 tokens de salida por tarea en el índice de Artificial Analysis, un 30 % más que 3.7 Flash
Precio	0,75 USD de entrada y 3,75 USD de salida por cada millón de tokens hasta el 31/12/2026; el razonamiento se factura como salida

Paso 1: declarar la herramienta

En la API de interacciones, una herramienta es un objeto plano con:

• type: "function"
• name
• description
• Un esquema JSON bajo parameters

La descripción debe ser específica. «Consultar el estado actual de envío de un pedido por su ID» ayuda al modelo a decidir cuándo llamar la herramienta; «ayudante de pedidos» es demasiado ambiguo.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-[REDACTED CREDENTIAL] \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Where is order A1029 right now?",
    "generation_config": {"thinking_level": "low"},
    "tools": [{
      "type": "function",
      "name": "get_order_status",
      "description": "Look up the current shipping status of an order by its ID.",
      "parameters": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"]
      }
    }]
  }'

Dos opciones son deliberadas:

• thinking_level es low porque una consulta sencilla no necesita el valor predeterminado medium. Consulte la guía de niveles de razonamiento para decidir cuándo aumentarlo.
• No se especifica temperature. La guía de Gemini 3 de Google recomienda conservar el valor predeterminado 1.0, porque reducirlo puede provocar bucles dentro del ciclo de herramientas.

Paso 2: leer el paso function_call

La API de interacciones devuelve el ID de la interacción y una lista de pasos de ejecución: pensamientos del modelo, llamadas a herramientas y, finalmente, un paso model_output.

Cuando el modelo necesita una herramienta, la respuesta contiene un paso como este:

{
  "type": "function_call",
  "id": "call_8f2d...",
  "name": "get_order_status",
  "arguments": {"order_id": "A1029"}
}

Los tres campos son necesarios:

• id es el identificador que debe enviar de vuelta como call_id.
• name indica qué función debe ejecutar y también debe repetirse en la respuesta.
• arguments ya está parseado como JSON. Valídelo contra sus propias reglas antes de ejecutar la operación. El modelo conoce el esquema, pero no sabe necesariamente que sus IDs de pedido deben tener cinco caracteres.

Guarde también el ID de la interacción que aparece en la parte superior de la respuesta. Lo necesitará como previous_interaction_id en el siguiente turno.

Paso 3: devolver function_result con call_id y name

Ejecute la función y envíe una segunda solicitud cuyo input sea un function_result. En Gemini 3.8 Flash, call_id y name son obligatorios:

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-[REDACTED CREDENTIAL] \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "previous_interaction_id": "<interaction id from step 2>",
    "input": [{
      "type": "function_result",
      "name": "get_order_status",
      "call_id": "call_8f2d...",
      "result": [{"type": "text", "text": "{\"status\":\"in_transit\",\"eta\":\"2026-09-05\"}"}]
    }]
  }'

Si omite cualquiera de los dos campos, la llamada falla. Este es uno de los errores más comunes al migrar ciclos escritos para modelos anteriores.

result es una lista de partes de contenido y la parte de texto contiene el JSON como cadena. Como previous_interaction_id apunta al turno anterior, el servidor ya conserva el prompt original, la declaración de la herramienta y el razonamiento del modelo.

La respuesta vuelve a ser una lista de pasos:

• Si termina en model_output, el ciclo finalizó. El SDK expone el texto mediante interaction.output_text.
• Si contiene otra function_call, vuelva a ejecutar los pasos 2 y 3.

En Python, el patrón es:

client.interactions.create(
    model="gemini-3.8-flash",
    input=...,
    ...
)

client.interactions.create(
    model="gemini-3.8-flash",
    previous_interaction_id=interaction.id,
    input=[function_result],
)

El tutorial de la API de Gemini 3.8 Flash cubre las claves, el streaming y la lectura del consumo de tokens.

Equivalente heredado con generateContent

La mayoría del código existente todavía llama a:

models/gemini-3.8-flash:generateContent

Google indica que esta API «sigue siendo totalmente compatible» y no tiene fecha de finalización. El vocabulario cambia, pero el contrato es el mismo:

• Las herramientas se declaran bajo functionDeclarations.
• El modelo responde con una parte functionCall.
• La aplicación responde con una parte functionResponse.
• El functionCall del modelo incluye un id.
• Su functionResponse debe repetir ese id junto con name y response.

Es el mismo identificador que call_id en la API de interacciones, pero con otro nombre de campo. La documentación de llamada a funciones de Google especifica que tanto el ID como el nombre son obligatorios.

Hay dos diferencias prácticas:

1. generateContent no conserva estado. Debe reenviar el historial completo de contents en cada turno, incluida la llamada del modelo y cualquier firma de pensamiento devuelta.
2. El razonamiento se configura bajo generationConfig.thinkingConfig.thinkingLevel:

{
  "generationConfig": {
    "thinkingConfig": {
      "thinkingLevel": "low"
    }
  }
}

Los tokens de razonamiento aparecen como usageMetadata.thoughtsTokenCount y se facturan como tokens de salida.

Para un proyecto nuevo, prefiera la API de interacciones: el estado del lado del servidor evita errores causados por historiales reenviados sin una firma o un ID de llamada.

Por qué Gemini 3.8 Flash usa herramientas iterativamente

La publicación de lanzamiento de Google afirma que el modelo «trabaja más duro»: en tareas complejas ejecuta pasos de razonamiento adicionales, realiza llamadas iterativas y verifica su trabajo mediante pasos más pequeños. Google también advierte que puede utilizar más tokens en tareas largas y complejas.

Artificial Analysis midió estos efectos:

• Unos 48.000 tokens de salida por tarea en su índice, un 30 % más que 3.7 Flash.
• Coste aproximado por tarea de 0,58 USD en high, frente a 0,40 USD para 3.7 Flash con los mismos precios por token.
• Coste aproximado de 0,41 USD en medium y 0,24 USD en low.
• Tau3-Banking aumentó 12 puntos, hasta el 45 %.

La ventaja es una mejor capacidad de uso de herramientas. La desventaja es que un ciclo sin límites puede tardar más que con 3.7 Flash.

Cuatro controles para producción

Aplíquelos en este orden:

1. Límite de turnos en el arnés

Cuente los pasos function_call por tarea y deténgase al alcanzar un límite. Entre 6 y 10 turnos es un buen punto de partida para búsquedas; las tareas de codificación agéntica pueden necesitar más. Al alcanzar el límite, envíe un turno final sin herramientas o devuelva un error. El modelo no se limitará por sí solo.

1. thinking_level por ruta

• low para búsquedas y herramientas de un solo salto.
• medium para trabajo de varios pasos.
• high cuando la verificación adicional lo justifique.
• No use minimal: Gemini 3.8 Flash devuelve un error de validación.

1. Tiempo de espera en ambos niveles

Configure un timeout para cada solicitud a Gemini y otro timeout de pared para toda la tarea. Las ejecuciones high de Artificial Analysis promediaron 2,5 minutos por tarea, frente a 0,8 minutos en low.

1. Herramientas idempotentes

Un modelo iterativo puede reintentar una llamada. get_order_status debe poder ejecutarse dos veces sin efectos adversos. Las operaciones con efectos secundarios, como reembolsos o envíos, deben requerir confirmación explícita.

Si no puede asumir los turnos adicionales, consulte la guía de migración de Gemini 3.7 a 3.8 Flash para mantener 3.7 Flash detrás de un indicador de configuración.

Firmas de pensamiento, llamadas paralelas y salidas estructuradas

Firmas de pensamiento

Los modelos Gemini 3 adjuntan firmas a su razonamiento. Con el flujo almacenado predeterminado, previous_interaction_id las gestiona automáticamente.

Si usa store: false o generateContent, debe reenviar los bloques de pensamiento y sus firmas exactamente como fueron recibidos en cada tipo de parte. No los recorte, reordene ni vuelva a serializar: una firma es opaca y cualquier modificación la invalida.

Consulte la documentación de la API de interacciones para conocer las diferencias entre los modos almacenado y sin estado.

Llamadas paralelas

La respuesta es una lista y puede contener varios pasos function_call cuando el modelo necesita búsquedas independientes. Cada llamada tiene un ID único y los resultados pueden devolverse en cualquier orden.

Envíe un function_result por llamada dentro del mismo array input, haciendo coincidir cada resultado con su propio call_id:

[
  {
    "type": "function_result",
    "name": "get_order_status",
    "call_id": "call_1",
    "result": [{"type": "text", "text": "..."}]
  },
  {
    "type": "function_result",
    "name": "get_order_status",
    "call_id": "call_2",
    "result": [{"type": "text", "text": "..."}]
  }
]

No haga la correspondencia solo por name: dos llamadas a la misma función tienen dos call_id distintos.

Salidas estructuradas

Gemini 3.8 Flash admite salidas estructuradas y llamadas a funciones en el mismo modelo. Un patrón práctico es usar:

• Herramientas para el ciclo de ejecución.
• Un esquema JSON para la respuesta final.

Así, el model_output que cierra el ciclo es legible por máquina en lugar de ser prosa libre. Consulte la documentación de llamadas a funciones y salidas estructuradas.

No simule una salida estructurada declarando una herramienta ficticia y leyendo sus arguments: el patrón falla cuando el modelo decide que no necesita llamar ninguna herramienta.

Google también enumera el uso de computadoras —en vista previa— para Gemini 3.8 Flash. Para decidir cuándo una API estructurada es preferible a un agente que controla la pantalla, consulte uso de computadoras frente a APIs estructuradas.

Probar el ciclo de herramientas en Apidog

Un ciclo de herramientas tiene tres puntos críticos:

1. La declaración de la herramienta.
2. El recorrido de ida y vuelta del ID.
3. La respuesta final.

Puede probarlos en Apidog sin conectar el backend real.

1. Simule el backend

Defina GET /orders/{order_id} y active el servidor simulado. Use siempre esta respuesta:

{
  "status": "in_transit",
  "eta": "2026-09-05"
}

Una respuesta fija garantiza que cualquier cambio en la salida final provenga del modelo y no de la base de datos. En el entorno de pruebas, el arnés apunta a la URL simulada; en producción, al servicio real.

2. Encadene los dos turnos

Guarde GEMINI_API_KEY como variable de entorno y úsela en el encabezado:

{{GEMINI_API_KEY}}

Construya un escenario de tres pasos:

• Paso A: haga POST /v1beta/interactions con el prompt y la declaración get_order_status. Extraiga el ID de interacción y los campos id, name y arguments.order_id del paso function_call.
• Paso B: haga GET al endpoint simulado usando {{order_id}}. Este paso representa la ejecución de la función.
• Paso C: envíe otro POST con function_result:
  • call_id: {{call_id}}
  • name: {{tool_name}}
  • previous_interaction_id: {{interaction_id}}
  • El cuerpo del paso B como parte de texto.

3. Añada aserciones

Verifique lo siguiente:

• El paso A devuelve 200 y contiene un paso function_call cuyo name es get_order_status.
• arguments.order_id es A1029.
• El paso C devuelve 200 y termina en model_output, sin un segundo function_call.
• El texto final contiene in_transit.
• Si prueba también generateContent, establezca un límite para usageMetadata.thoughtsTokenCount según thinking_level.

Estas aserciones confirman que el modelo interpretó el prompt, respetó el esquema, aceptó call_id y name, y utilizó el resultado de la herramienta.

Programe el escenario para ejecutarlo diariamente. Las actualizaciones silenciosas pueden cambiar el comportamiento del modelo: un ciclo que terminaba en una ronda la semana pasada podría necesitar dos esta semana.

La guía de pruebas de APIs para agentes de IA profundiza en las aserciones de varios pasos. También puede descargar Apidog y construir el escenario con el nivel gratuito.

Preguntas frecuentes

¿Es obligatorio call_id en Gemini 3.8 Flash?

Sí. En la API de interacciones, cada function_result necesita call_id y name. En generateContent, cada functionResponse necesita el id y el name de la llamada. El código antiguo que enviaba solo el nombre falla con los modelos Gemini 3.

¿Por qué mi ciclo ejecuta más turnos en 3.8 Flash que en 3.7?

Es intencional. Google indica que Gemini 3.8 Flash llama a herramientas de forma iterativa y puede utilizar más tokens en tareas largas y complejas. Establezca un límite de turnos y reduzca thinking_level cuando sea apropiado.

¿Todavía puedo usar generateContent para llamadas a funciones?

Sí. Google la considera una API heredada, pero sigue siendo totalmente compatible y no tiene fecha de finalización. Debe conservar usted mismo el historial, incluidas las firmas de pensamiento. El ID de llamada —id en esta API— y name siguen siendo obligatorios.

¿Funciona thinking_level: "minimal" con herramientas?

No. Gemini 3.8 Flash devuelve un error de validación. Use low.

¿Cuánto cuesta una tarea intensiva en herramientas?

Hasta el 31 de diciembre de 2026, el precio es de 0,75 USD por millón de tokens de entrada y 3,75 USD por millón de tokens de salida. El razonamiento se factura como salida.

Artificial Analysis midió aproximadamente:

• 0,58 USD por tarea en high.
• 0,41 USD en medium.
• 0,24 USD en low.

Sus tareas pueden diferir. Registre los recuentos de tokens y mida el coste real.

Despliegue el ciclo con límites

El contrato esencial es:

1. Declare la herramienta.
2. Lea el paso function_call.
3. Devuelva function_result con call_id y name mediante previous_interaction_id.

Lo que cambia con Gemini 3.8 Flash es la disposición del modelo a iterar. Antes de pasar a producción, añada un límite de turnos, seleccione thinking_level por ruta y configure timeouts. Simule el backend, encadene los dos turnos, afirme el recorrido del ID y programe la prueba diaria.

Consulte las Novedades de Gemini 3.8 Flash para las notas de migración y la documentación de llamadas a funciones para el contrato completo.