Guía para desarrolladores de Gemini 3.5 Flash

Gemini 3.5 Flash es un modelo potente, rentable y de alta velocidad de la familia Gemini 3. Diseñado para ofrecer capacidades agénticas casi de nivel Pro sin comprometer el rendimiento ni el valor, el modelo ya está disponible de forma general (DG) para los desarrolladores que usan la API de Gemini y para las empresas que usan Gemini Enterprise Agent Platform.

En este documento, se describen las novedades de 3.5 Flash, cuándo debes usarlo, cómo migrar a 3.5 Flash y se proporciona una guía de inicio rápido para usar 3.5 Flash.

¿Cómo se integra en la familia de Gemini?

En la siguiente tabla, se comparan algunas de las especificaciones entre 3.5 Flash, 3.1 Pro y 3.1 Flash-Lite:

	Gemini 3.5 Flash	Gemini 3.1 Pro	Gemini 3.1 Flash-Lite
ID de modelo	gemini-3.5-flash	gemini-3.1-pro-preview	gemini-3.1-flash-lite
Etapa de lanzamiento	DG	Vista previa	DG
Tipos de entrada	Texto, imagen, audio y video	Texto, imagen, audio y video	Texto, imagen, audio y video
Tipos de salida	Texto	Texto	Texto
Ventana de contexto	1,048,576	1,048,576	1,048,576
Longitud máxima de los tokens de salida	65,536	65,536	65,536
Regiones admitidas	Global, Multirregión, América, Europa, Asia-Pacífico	Global	Global, multirregional
Niveles de pensamiento admitidos	MINIMAL, LOW, MEDIUM, HIGH (Predeterminado: MEDIUM)	LOW, MEDIUM, HIGH (Predeterminado: HIGH)	MINIMAL, LOW, MEDIUM, HIGH (Predeterminado: MINIMAL)
Enfoque principal	Tareas equilibradas, llamadas a herramientas y razonamiento intermedio	Tareas de razonamiento profundo y alta complejidad	Tareas de gran volumen, sensibles a los costos y a la latencia

Consulta la página del modelo 3.5 Flash para obtener la lista completa de las capacidades, las herramientas y las opciones de consumo compatibles.

Desglose de casos de uso

La estrategia recomendada para los flujos de trabajo de agentes usa un enfoque por niveles para optimizar la calidad, la velocidad y el costo:

• Gemini Pro: Se reserva para tareas cognitivas de alta complejidad que requieren un razonamiento profundo, como la planificación inicial de la raíz, la resolución de problemas complejos, la programación difícil y la toma de decisiones críticas.
• Gemini Flash: Úsalo como el "caballo de batalla" principal para las tareas de ejecución, las llamadas a herramientas y los pasos de razonamiento intermedios, ya que ofrece el mejor equilibrio entre rendimiento y eficiencia.
• Gemini Flash-Lite: Implementa para tareas estructurales y de procesamiento previo de gran volumen y baja latencia en las que la velocidad y el costo son fundamentales, como el enrutamiento de intents, la extracción de datos, el etiquetado y la clasificación.

¿Qué novedades hay en Gemini 3.5 Flash?

Gemini 3.5 Flash aporta los siguientes cambios y mejoras a la línea de modelos de Gemini:

• Rendimiento de vanguardia sostenido: Es nuestro modelo de Gemini Flash más inteligente, optimizado para tareas de agentes y programación a gran escala.
• Ejecución de agentes: Implementación de agentes secundarios, resolución de problemas y bucles de agentes rápidos a gran escala.
• Programación mejorada: Ciclos de programación iterativos, exploración rápida y creación de prototipos para probar rutas alternativas y explorar soluciones de forma dinámica.
• Largo horizonte: Flujos de trabajo de varios pasos y uso de herramientas a gran escala.
• Preservación de pensamientos: El modelo mantiene el razonamiento intermedio en conversaciones de varios turnos de forma automática. No se necesitan cambios en la API.
• Nuevo nivel de pensamiento predeterminado: El nivel de pensamiento predeterminado cambió de HIGH a MEDIUM.
• Razonamiento mejorado de LOW: El nivel de razonamiento bajo ahora se mejoró significativamente para las tareas de código y de agentes que requieren menos pasos, lo que ofrece una calidad sólida con una latencia y un costo más bajos.

Puedes encontrar más detalles en la sección Cambios clave.

Nota: Es posible que notes un aumento en los recuentos de tokens informados. La infraestructura actualizada cuenta con precisión todos los componentes de la solicitud, incluidos los metadatos complejos, como los esquemas de respuesta y las llamadas a funciones, que se contaron de forma insuficiente en las versiones anteriores.

Guía de inicio rápido

Antes de comenzar, debes autenticarte en Agent Platform con las credenciales predeterminadas de la aplicación (ADC) o una clave de API. Consulta Comienza a usar Gemini Enterprise Agent Platform para obtener más información.

En los siguientes bloques de código, reemplaza PROJECT_ID por el ID de tu proyecto.

Instalación

Asegúrate de usar el SDK de google-genai más reciente:

pip install --upgrade google-genai

Solicitud básica

Python

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
  model="gemini-3.5-flash",
  contents="How does AI work?",
)
print(response.text)

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent \
-d '{
  "contents": {
    "role": "USER",
    "parts": { "text": "Why is the sky blue?" },
  },
}'

Cambios clave

En esta sección, se describen con más detalle los siguientes cambios que se introdujeron en Gemini 3.5 Flash:

• Nuevo nivel de razonamiento predeterminado (MEDIUM)
• Preservación de pensamientos
• Obsoleto: Parámetros de muestreo
• Obsoleto: thinking_budget

Nuevo nivel de razonamiento predeterminado

El nivel de razonamiento predeterminado para los modelos de Gemini 3 ahora es MEDIUM, que cambió de HIGH en la versión preliminar de Gemini 3 Flash. El nivel de razonamiento MEDIUM genera resultados sólidos en una amplia variedad de tareas, a la vez que es más rápido y rentable.

Los niveles de razonamiento admitidos son los siguientes:

• MINIMAL: Coincide con el parámetro de configuración "sin razonamiento" para la mayoría de las consultas. El modelo puede pensar muy poco para tareas complejas, como la programación. Minimiza la latencia para aplicaciones de chat o de alta capacidad de procesamiento.
• LOW: Razonamiento ligero para la mayoría de las tareas con alta velocidad y menor costo.
• MEDIUM: (Predeterminado) Configuración equilibrada para la mayoría de las tareas que requieren razonamiento.
• HIGH: Maximiza el razonamiento para optimizar el rendimiento de las tareas. Es posible que el modelo tarde más que el parámetro de configuración MEDIUM en generar el primer token, pero el resultado será más completo.

Por ejemplo, usa HIGH para acertijos lógicos, problemas matemáticos con palabras o situaciones complicadas en las que el modelo deba razonar a través de varios pasos:

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
   model="gemini-3.5-flash",
   contents="A farmer has chickens and rabbits. There are 35 heads and 94 legs. How many chickens and how many rabbits does he have? Show your step-by-step logic.",
   config=types.GenerateContentConfig(
       thinking_config=types.ThinkingConfig(
           thinking_level=types.ThinkingLevel.HIGH
       )
   ),
)
print(response.text)

El parámetro thinking_level es opcional. Si se omite, 3.5 Flash usará su configuración predeterminada (MEDIUM).

Nota: El parámetro thinking_level y el parámetro heredado thinking_budget son excluyentes entre sí. Si usas ambos en una solicitud, se mostrará un error 400.

Preservación de pensamientos

El modelo mantiene el razonamiento intermedio en las conversaciones de varios turnos automáticamente. Cuando está presente en el historial de conversaciones, el contexto de razonamiento se transfiere automáticamente, lo que mejora el rendimiento en tareas complejas de varios pasos, como la depuración iterativa y la refactorización de código. No se necesitan cambios en la API.

Los pensamientos de los turnos anteriores ahora se conservan de forma predeterminada. El servicio ya no borra el historial de pensamientos del contexto de la conversación antes de pasarlo al modelo.

Cuando envíes el historial de conversaciones, sé coherente con los turnos anteriores: incluye el contexto completo (pensamientos, llamadas a funciones y respuestas) o omítelo por completo. El contexto parcial puede degradar el rendimiento del modelo.

Nota: La preservación de pensamientos puede aumentar el uso de tokens y el tiempo de respuesta. En el caso de las consultas simples e independientes, puede ser útil borrar los pensamientos entre turnos.

Obsoleto: Parámetros de muestreo

Los siguientes parámetros de muestreo ya no se recomiendan para los modelos de Gemini 3:

• temperature
• top_p
• top_k

El modelo administra su propio muestreo para obtener resultados óptimos. Quita estos parámetros de todas las solicitudes. Para garantizar el determinismo, define una instrucción del sistema con reglas explícitas para tu caso de uso específico.

Obsoleto: thinking_budget

El parámetro numérico sin procesar thinking_budget ya no se admite en todos los modelos de Gemini 3. En su lugar, usa la enumeración de cadenas thinking_level.

# ⚠️ Before (not recommended)
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_budget=7500)
)

# ✅ After
config = types.GenerateContentConfig(
    thinking_config=types.ThinkingConfig(thinking_level="MEDIUM")
)

Prácticas recomendadas

En esta sección, se describen las siguientes prácticas recomendadas para usar 3.5 Flash:

• Usa la coincidencia estricta de respuestas para las llamadas a funciones
• Incluye contenido multimodal en la respuesta de la función parts
• Usa instrucciones intercaladas en la respuesta de la función
• Reduce las llamadas a herramientas innecesarias

Usa la coincidencia de respuestas estricta para las llamadas a función

Las respuestas que no coinciden hacen que el modelo devuelva respuestas vacías con finish_reason: STOP en la mayoría de los casos. Sigue siempre estas convenciones:

• Incluye id: Cada FunctionResponse debe incluir el id del FunctionCall correspondiente.
• Coincidencia de name: El name de la respuesta debe coincidir con el name de la llamada.
• Recuentos de coincidencias: Se devuelve exactamente un FunctionResponse por cada FunctionCall recibido.

El siguiente código es un ejemplo de una llamada a función correcta:

# ✅ Include matching id and name in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result},
                id=tool_call.id,
            )
        ]),
    ],
)

Incluye contenido multimodal en la respuesta de la función parts

Proporcionar imágenes fuera de la respuesta de la función puede provocar un comportamiento inesperado del modelo, como la filtración de pensamientos, y generar una calidad inferior. Sigue la recomendación que se incluye en Introducción a la llamada a funciones y, luego, incluye contenido multimodal en las partes de la respuesta de la función que envías al modelo. El modelo puede procesar este contenido multimodal en su siguiente turno para producir una respuesta más informada.

Por ejemplo:

# ✅ Include multimodal content in the function response
final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={
                    "result": "instrument.jpg",
                    "image": base64_image_data,
                },
                id=tool_call.id,
            )
        ]),
    ],
)

Usa instrucciones intercaladas en la respuesta de la función

Proporcionar instrucciones de la plataforma junto con las respuestas de las funciones como parts posteriores puede generar un comportamiento inesperado del modelo, como la filtración de pensamientos, y dar como resultado una calidad inferior. En su lugar, agrégalo al final del texto de respuesta de la función separado por dos saltos de línea.

Por ejemplo:

# ✅ Append inline instructions to the end of the function response separated by two newlines
result_text = f"{json.dumps(result)}\n\n<your inline instructions>"

final_response = client.models.generate_content(
    model="gemini-3.5-flash",
    config=config,
    contents=[
        *previous_contents,
        response.candidates[0].content,
        types.Content(role="user", parts=[
            types.Part.from_function_response(
                name=tool_call.name,
                response={"result": result_text},
                id=tool_call.id,
            )
        ]),
    ],
)

Reduce las llamadas a herramientas innecesarias

Si experimentas un uso excesivo de las llamadas a herramientas, hay dos técnicas que ayudan a minimizarlas:

1. Reduce el nivel de razonamiento: Los niveles de razonamiento más altos alientan al modelo a usar más herramientas para explorar y verificar, por lo que bajar el nivel puede reducir las llamadas a herramientas.

2. Agrega una instrucción del sistema: Si el uso excesivo persiste después de ajustar el nivel de razonamiento, considera usar una instrucción que restrinja el uso de herramientas. Por ejemplo:

   You have a limited action budget of <n> tool calls. Use them efficiently.
   

Migra a 3.6 Flash desde 3.5 Flash o 3.1 Pro

Para migrar a 3.6 Flash desde 3.5 Flash o 3.1 Pro, sigue estos pasos:

1. Actualiza el ID del modelo: Cambia la cadena del modelo en tus llamadas a la API a gemini-3.6-flash.
2. Adapta tu código a las nuevas reglas de la API de la familia Gemini 3: Gemini 3.6 Flash aplica de forma estricta las reglas de parámetros y las convenciones de la API establecidas en toda la familia Gemini 3:
   • Quita la temperatura, el top-K y el top-P: Quita estos parámetros personalizados de tu carga útil. Si bien no arrojarán un error, el modelo los ignorará por completo. En su lugar, usa el parámetro thinking_level o los resultados estructurados de json_schema para controlar el determinismo de los resultados.
   • Quita las penalizaciones de frecuencia y presencia: Quita cualquier configuración personalizada para las penalizaciones de frecuencia o presencia para evitar que tus llamadas a la API arrojen errores de tiempo de ejecución.
   • Asegúrate de que tu integración de chat no intente completar previamente el modelo: Revisa tus arrays de historial de mensajes para asegurarte de que la carga útil de tu API no termine con un turno de usuario o de modelo vacío. Si el último objeto de tu array de historial es un rol "model" (API de GenerateContent) o un tipo "model_output" (API de Interactions), reestructura la secuencia para evitar que se active un error de validación estricto.
   • Usa thinking_level: Quita las instancias del parámetro thinking_budget obsoleto y, en su lugar, usa thinking_level.
   • Aplica convenciones estrictas de llamada a funciones: El FunctionResponse debe coincidir estrictamente con el id, el name y el recuento de ejecuciones del FunctionCall anterior. Si necesitas agregar instrucciones intercaladas, colócalas directamente dentro del texto de respuesta de la función separadas por dos saltos de línea (\n\n).
3. Considera los cambios en el flujo de trabajo:
   • Si tu aplicación se basa en bucles de conversación de varios turnos, prueba tus flujos de trabajo para asegurarte de que la nueva concisión de pasos del modelo no active salidas prematuras.
   • Si compilas agentes de frontend o de secuencias de comandos básicas, supervisa las llamadas a execute_code exploratorias innecesarias debido al nuevo sesgo del modelo hacia la inspección programática inicial.

Soluciones alternativas para los requisitos de texto previos a la herramienta

Si tu instrucción requiere que el modelo genere texto estructurado (XLM, YAML, JSON, etc.) (por ejemplo, <UPDATE>...</UPDATE>) justo antes de realizar una llamada a la herramienta, esta puede fallar de forma ocasional con un error Malformed_Function_Call. Puedes usar una de las siguientes soluciones alternativas para resolver este problema:

• (Recomendado) Indica al modelo que coloque sus notas previas a la herramienta dentro de una llamada a función update() dedicada en lugar de texto sin procesar. Consulta la siguiente sección para obtener instrucciones detalladas sobre la implementación.
• Indícale al modelo que escriba notas como encabezados de Markdown (por ejemplo, # UPDATE, ## PLAN) en lugar de texto estructurado.
• No exijas que el modelo genere texto antes de las llamadas a la herramienta.

Solución recomendada: Une las notas de trabajo en una llamada a función dedicada

En lugar de la instrucción original:

Before calling a tool, in every response you MUST first output a single
`<UPDATE>` part as specified, don't skip this part or any of required sub-tags
within `<UPDATE>`.

Usa esta instrucción actualizada:

Before calling any other tool, in every response you MUST first call `update`
with all required parameters (previous_step, plan, next_step, external).

Actualiza todas las referencias al formato XML de <UPDATE> anterior en la solicitud del cliente. Luego, agrega la declaración de la función correspondiente para la función de actualización:

{
  "name": "update",
  "description": "Update working notes (previous step analysis, plan, next step, external note).",
  "parameters": {
    "type": "OBJECT",
    "properties": {
      "previous_step": {
        "type": "STRING",
        "description": "Key findings and outcomes since the previous step."
      },
      "plan": {
        "type": "STRING",
        "description": "The current status of the plan."
      },
      "next_step": {
        "type": "STRING",
        "description": "Brief explanation of the immediate next action according to the plan."
      },
      "external": {
        "type": "STRING",
        "description": "A short, plain-language note shown to the User about what you are ABOUT TO DO next."
      }
    },
    "required": [
      "previous_step",
      "plan",
      "next_step",
      "external"
    ]
  }
}

El modelo realizará dos llamadas en el mismo paso: la llamada a update() que reemplaza el XML estructurado y la llamada a función real que desea realizar.

Recursos adicionales

• Página del modelo Gemini 3.5 Flash
• Notebook introductorio