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

Gemini 3.8 Flash se lanzó el 2 de septiembre de 2026, y Google lo construyó para "llamar a herramientas iterativamente": en una tarea difícil, realiza una llamada, verifica el resultado y realiza otra, en lugar de adivinar todo de una sola vez. Eso es una buena noticia para los agentes y un nuevo dolor de cabeza para cualquiera cuyo ciclo de herramientas estuviera ajustado para 3.7 Flash. Dos detalles de la API importan más que cualquier otra cosa. Cada resultado de función debe llevar tanto call_id como name, y la API de interacciones, no generateContent, es ahora la forma principal de ejecutar el ciclo.

Esta guía explica el flujo completo de dos turnos en la API de interacciones, muestra la forma heredada de generateContent que probablemente aún esté ejecutando, explica por qué el nuevo modelo dedica más turnos y tokens a las herramientas, y finaliza con una configuración de prueba que puede ejecutar todos los días: simule el backend de la herramienta, encadene ambos turnos y afirme que el call_id realiza viajes de ida y vuelta. Si primero necesita una descripción general del modelo, comience con qué es Gemini 3.8 Flash. Los nombres de los campos a continuación provienen de los documentos de llamada a funciones de Google.

Cada solicitud aquí es HTTP plano con JSON, por lo que puede construirla y depurarla en Apidog antes de que pase al código de la aplicación.

Llamada a funciones en Gemini 3.8 Flash de un vistazo

Paso 1: declarar la herramienta

En la API de interacciones, una herramienta es un objeto plano: un type de function, un name, una description que el modelo lee para decidir cuándo llamarla, y un JSON Schema bajo parameters. Mantenga la descripción específica. "Consultar el estado actual de envío de un pedido por su ID" se llama en el momento adecuado; "ayudante de pedidos" se llama al azar.

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-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 en esta solicitud son deliberadas. thinking_level es bajo porque una sola consulta no necesita el valor predeterminado medium; la guía de niveles de razonamiento cubre cuándo aumentarlo. Y no hay temperature. La guía de Gemini 3 de Google es dejarlo en el valor predeterminado 1.0, porque bajarlo puede causar bucles, que es lo último que se desea dentro de un ciclo de herramientas.

Paso 2: leer el paso function_call

La API de interacciones no responde con un solo mensaje. Devuelve el id propio de la interacción más una lista de pasos de ejecución: pensamientos del modelo, llamadas a herramientas y, finalmente, un paso model_output una vez que el modelo tiene una respuesta. Cuando el modelo decide que necesita su herramienta, la lista contiene un paso function_call en lugar de un model_output:

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

Tres campos, y los necesita los tres. id es el identificador que envía de vuelta como call_id. name le dice qué función ejecutar y también debe ser devuelto. arguments ya es JSON parseado, así que valídelo contra sus propias reglas antes de ejecutar cualquier cosa; el modelo llena la forma que declaró, pero no sabe que sus IDs de pedido tienen cinco caracteres de longitud.

Guarde el id de interacción de la parte superior de la respuesta al mismo tiempo. Se convierte en previous_interaction_id en el siguiente turno.

Paso 3: devolver el resultado con call_id y name

Ejecute su función, luego envíe una segunda solicitud cuya input sea un function_result. Tanto call_id como name son obligatorios en Gemini 3.8 Flash. Si omite cualquiera de ellos, la llamada falla, lo cual es el error más común cuando los equipos migran bucles escritos para modelos más antiguos.

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-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\"}"}]
    }]
  }'

result es una lista de partes de contenido, y la parte de texto lleva su JSON como una cadena. Debido a que previous_interaction_id apunta al turno anterior, el servidor ya contiene el prompt original, la declaración de la herramienta y el razonamiento del modelo; no reenvía nada de eso. La respuesta es otra lista de pasos. Si termina en model_output, ha terminado, y el SDK expone el texto como interaction.output_text. Si contiene otra function_call, vuelva al paso 2. Ese bucle es todo el patrón.

En Python, el flujo es client.interactions.create(model="gemini-3.8-flash", input=..., ...) con los mismos campos JSON como argumentos de palabra clave, luego un segundo create con previous_interaction_id y la lista function_result como input. El tutorial de la API de Gemini 3.8 Flash cubre claves, streaming y lectura del uso de tokens si el endpoint es nuevo para usted.

El equivalente heredado de generateContent

La mayoría del código existente de Gemini todavía llama a models/gemini-3.8-flash:generateContent, y Google dice que "sigue siendo totalmente compatible" sin fecha de finalización. El vocabulario es diferente; la regla es la misma. Las herramientas se declaran bajo functionDeclarations, el modelo responde con una parte functionCall, y usted responde con una parte functionResponse. En la forma heredada, la parte functionCall del modelo lleva un id, y su parte functionResponse debe replicar ese mismo valor en su propio campo id junto con name y response. Es el mismo contrato que call_id en la API de interacciones bajo un nombre de campo diferente, y la guía de Gemini 3 de Google es explícita en que tanto el id como el name son obligatorios.

Dos diferencias prácticas. Primero, generateContent no tiene estado, por lo que usted mismo lleva la conversación: el historial completo de contents se devuelve en cada turno, incluyendo la parte functionCall del modelo y cualquier firma de pensamiento que haya devuelto. Segundo, el razonamiento se configura bajo generationConfig.thinkingConfig.thinkingLevel en lugar de generation_config.thinking_level:

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

Los tokens de razonamiento aparecen como usageMetadata.thoughtsTokenCount en la respuesta y se facturan como salida. Si está eligiendo entre las dos APIs para un nuevo proyecto, elija Interacciones: el estado del lado del servidor elimina la clase de errores donde un historial reenviado carece de una firma o un call_id.

Por qué 3.8 Flash llama a herramientas iterativamente y cómo limitar el ciclo

La publicación de lanzamiento de Google dice que el modelo "trabaja más duro": en tareas complejas "ejecuta pasos de razonamiento adicionales y llama a herramientas de forma iterativa", realizando "pasos de razonamiento más pequeños" y verificando su trabajo a lo largo del camino. Google también dice que "puede usar más tokens en tareas más largas y complejas, por diseño". Artificial Analysis midió el efecto: aproximadamente 48k tokens de salida por tarea en su índice, +30% sobre 3.7 Flash, y un costo por tarea de 0,58 $ en el nivel high frente a 0,40 $ para 3.7 Flash con los mismos precios por token. Medium se situó en 0,41 $ y low en 0,24 $.

Para un bucle de herramientas, esto significa más pasos function_call por tarea. La ventaja es real: Tau3-Banking, la evaluación de uso de herramientas de AA, subió 12 puntos hasta el 45%. La desventaja es que un bucle sin límite ahora se ejecuta durante más tiempo que en agosto. Cuatro controles, en el orden en que deben aplicarse:

• Máximo de turnos en su arnés. Cuente los pasos function_call por tarea y deténgase en un límite que elija; de 6 a 10 es un rango de inicio sensato para búsquedas, más alto para codificación agentic. Cuando se alcance el límite, envíe un turno final sin herramientas o devuelva un error al usuario. El modelo no se limitará a sí mismo.
• thinking_level por ruta. low para búsquedas y herramientas de un solo salto, medium (el predeterminado) para trabajo de varios pasos, high solo donde la verificación adicional lo justifique. No envíe minimal; 3.8 Flash devuelve un error de validación.
• Tiempos de espera en ambos lados. Un tiempo de espera por solicitud en la llamada a Gemini y un reloj de pared por tarea en el bucle. Las ejecuciones de razonamiento alto de AA promediaron 2,5 minutos por tarea, 0,8 minutos en el nivel low.
• Herramientas idempotentes. Un modelo iterativo reintenta. Haga que get_order_status sea seguro de llamar dos veces, y haga que cualquier cosa con efectos secundarios (reembolsos, envíos) requiera un paso de confirmación.

Si su presupuesto no puede absorber los turnos adicionales, la guía de migración de 3.7 a 3.8 Flash cubre cómo mantener 3.7 Flash, que sigue siendo totalmente compatible, 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 de interacciones almacenadas predeterminado, previous_interaction_id las maneja por usted. Si establece store: false para una configuración sin estado, o si usa generateContent, debe enviar los bloques de pensamiento y las firmas exactamente como se recibieron, en cada tipo de parte. No los recorte, reordene ni vuelva a serializar; una firma es opaca y cualquier edición la invalida. Los documentos de la API de interacciones de Google cubren el equilibrio entre estado almacenado y sin estado.

Llamadas paralelas. La respuesta es una lista, por lo que puede contener más de un paso function_call cuando el modelo desea varias búsquedas independientes a la vez. Los documentos de llamada a funciones de Google confirman que los modelos Gemini 3 devuelven un id único con cada llamada precisamente para que los resultados puedan regresar en cualquier orden. Manéjelo devolviendo un function_result por llamada en el mismo array de input, cada uno coincidiendo con su propio call_id. Coincidir solo por name no es suficiente; dos llamadas a la misma función necesitan dos valores de call_id diferentes.

Salidas estructuradas. 3.8 Flash admite salidas estructuradas y llamadas a funciones en el mismo modelo. El patrón limpio son herramientas para el bucle y un esquema JSON para la respuesta final, de modo que el model_output que cierra el bucle sea legible por máquina en lugar de prosa. Las páginas de llamada a funciones y salidas estructuradas de Google documentan la configuración. No lo falsifique declarando una herramienta ficticia y leyendo sus arguments; eso se rompe en el momento en que el modelo decide que no tiene nada que llamar.

Todo lo anterior asume que el modelo llega a su sistema a través de funciones declaradas. Google también enumera el uso de computadoras (Vista previa) para 3.8 Flash; para cuando una API estructurada supera a un agente que controla la pantalla, vea uso de computadoras vs APIs estructuradas.

Probando el ciclo de herramientas en Apidog

Un ciclo de herramientas tiene tres puntos de ruptura: la declaración, el viaje de ida y vuelta del id y la respuesta final. Puede cubrir los tres en Apidog sin tocar su backend real.

• 1. Simule el backend de la herramienta. Defina GET /orders/{order_id} como un endpoint y active su servidor simulado. Déle un cuerpo de respuesta fijo, {"status": "in_transit", "eta": "2026-09-05"}, para que cada ejecución reciba la misma entrada y cualquier cambio en la respuesta final del modelo sea obra del modelo, no de su base de datos. Su arnés apunta a la URL simulada en el entorno de prueba y al servicio real en producción.
• 2. Encadene ambos turnos en un escenario de prueba. Almacene GEMINI_API_KEY como una variable de entorno y haga referencia a ella como {{GEMINI_API_KEY}} en el encabezado x-goog-api-key. Luego construya un escenario con tres pasos:
  • Paso A: POST a /v1beta/interactions con el prompt y la declaración get_order_status. Extraiga el id de interacción y el id, name y arguments.order_id del paso function_call en variables.
  • Paso B: GET el endpoint simulado con {{order_id}}. Este es su paso de "ejecutar la función".
  • Paso C: POST el function_result con call_id establecido en {{call_id}}, name establecido en {{tool_name}}, previous_interaction_id establecido en {{interaction_id}} y el cuerpo del Paso B como parte de texto.
• 3. Afirme lo que importa.
  • El Paso A devuelve 200 y contiene un paso cuyo type es function_call con name igual a get_order_status.
  • El arguments.order_id extraído es igual a A1029, lo que prueba que el modelo analizó el prompt y respetó el esquema.
  • El Paso C devuelve 200 y termina en un paso cuyo type es model_output sin un segundo function_call, lo que prueba que el call_id y el name que envió fueron aceptados y el ciclo se cerró en una ronda.
  • El texto final contiene in_transit, lo que prueba que el modelo utilizó el resultado de la herramienta en lugar de su propia suposición.
  • Si ejecuta el mismo escenario contra generateContent, agregue un límite en usageMetadata.thoughtsTokenCount por thinking_level. Esto detecta el aumento de costos de "trabajo más duro" antes de que llegue a su factura.

Programe el escenario para que se ejecute diariamente. El comportamiento del modelo puede variar con las actualizaciones silenciosas, y un bucle que se cerró en una ronda la semana pasada puede empezar a necesitar dos. La guía de prueba de API de agentes de IA profundiza en las aserciones de varios pasos, y puede descargar Apidog para construir el escenario contra el nivel gratuito antes de gastar un céntimo.

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 name de la llamada. El código antiguo que enviaba solo el nombre falla en los modelos Gemini 3.

¿Por qué mi bucle de herramientas ejecuta más turnos en 3.8 Flash que en 3.7? Por diseño. Google dice que el modelo "llama a herramientas de forma iterativa" y "puede usar más tokens en tareas más largas y complejas". Limite los turnos en su arnés y baje thinking_level; la guía de niveles de razonamiento tiene el costo medido por nivel.

¿Todavía puedo usar generateContent para la llamada a funciones? Sí. Google lo llama heredado pero dice que "sigue siendo totalmente compatible" sin fecha de finalización. Usted mismo lleva el historial, incluidas las firmas de pensamiento, y el id de llamada (escrito id en esta API) más el name aún se aplican.

¿Funciona thinking_level "minimal" con herramientas? No. Devuelve un error de validación en 3.8 Flash. Use low.

¿Cuánto cuesta una tarea intensiva en herramientas? El precio por token es de 0,75 $ de entrada y 3,75 $ de salida por 1 millón de tokens hasta el 31 de diciembre de 2026, con el razonamiento facturado como salida. Artificial Analysis midió 0,58 $ por tarea en high, 0,41 $ en medium y 0,24 $ en low en su índice. Sus tareas diferirán, así que afirme los recuentos de tokens y mida.

Despliegue el bucle con un límite

Declare la herramienta, lea el paso function_call y devuelva function_result con call_id y name bajo previous_interaction_id. Ese es todo el contrato. Lo que cambió con Gemini 3.8 Flash es la voluntad del modelo de iterar, por lo que el arnés necesita un límite de turnos, un thinking_level por ruta y un tiempo de espera antes de pasar a producción. Simule el backend, encadene los dos turnos, afirme los viajes de ida y vuelta del id y programe la ejecución. La página Novedades de Gemini 3.8 Flash de Google tiene las notas de migración; la guía fundamental tiene todo lo demás sobre el modelo.