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 casi profesionales sin comprometer el rendimiento ni el valor, el modelo ahora está disponible de forma general (GA) para los desarrolladores que usan la API de Gemini y para las empresas que usan Gemini Enterprise Agent Platform.

En este documento, se explica qué novedades incluye 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:

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

Desglose del caso de uso

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

• Gemini Pro: Resérvalo 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: Se usa como el "caballo de batalla" principal para las tareas de ejecución, las llamadas a herramientas y los pasos de razonamiento intermedio, y ofrece el mejor equilibrio entre rendimiento y eficiencia.
• Gemini Flash-Lite: Implementa el modelo para tareas estructurales y de preprocesamiento de gran volumen y baja latencia en las que la velocidad y el costo son fundamentales, como el enrutamiento de intención, la extracción de datos, el etiquetado y la clasificación.

¿Cuáles son las novedades de Gemini 3.5 Flash?

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

• Rendimiento de vanguardia sostenido: Nuestro modelo Flash más inteligente, optimizado para tareas de agentes y programación a gran escala.
• Ejecución agentica: Implementación de subagentes, resolución de problemas y bucles agenticos rápidos a gran escala.
• Mejora en la programación: 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 plazo: Flujos de trabajo de varios pasos y uso de herramientas a gran escala
• Conservación del pensamiento: El modelo mantiene el razonamiento intermedio en las 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.
• Mejora del pensamiento LOW: El nivel de pensamiento 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 menor latencia y costo.

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

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

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)

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 pensamiento predeterminado (MEDIUM)
• Preservación de pensamientos
• Obsoleto: Parámetros de muestreo
• Obsoleto: thinking_budget

Nuevo nivel de razonamiento predeterminado

El nivel de pensamiento 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 pensamiento MEDIUM produce resultados sólidos en una amplia variedad de tareas y, al mismo tiempo, 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 pensar" para la mayoría de las búsquedas. El modelo puede pensar de forma muy mínima para tareas complejas, como la programación. Minimiza la latencia para las 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) Es el parámetro de configuración equilibrado para la mayoría de las tareas que requieren razonamiento.
• HIGH: Maximiza el razonamiento para optimizar el rendimiento de la tarea. El modelo puede tardar 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 verbales de matemáticas o situaciones difíciles en las que el modelo debe 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).

Preservación de pensamientos

El modelo mantiene el razonamiento intermedio en las conversaciones de varios turnos de forma automática. 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 turnos anteriores ahora se conservan de forma predeterminada. El servicio ya no borra el historial de pensamiento del contexto de la conversación antes de pasarlo al modelo.

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

Obsoleto: Parámetros de muestreo

Ya no se recomiendan los siguientes parámetros de muestreo 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 thinking_budget numérico sin procesar ya no se admite en todos los modelos de Gemini 3. En su lugar, usa la enumeración de cadena 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
• Cómo usar instrucciones intercaladas en la respuesta de la función
• Cómo reducir las llamadas innecesarias a herramientas

Usa la concordancia estricta de respuestas para las llamadas a funciones

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: 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 generar un comportamiento inesperado del modelo, como filtración de pensamientos, y dar como resultado una calidad inferior. Sigue la recomendación incluida en Introducción a las llamadas a funciones y agrega 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 fundamentada.

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,
            )
        ]),
    ],
)

Usar 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 cambio, agrégalo al final del texto de respuesta de la función, separado por dos líneas nuevas.

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 innecesarias a herramientas

Si experimentas un uso excesivo de las llamadas a herramientas, puedes usar dos técnicas para minimizarlo:

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 reducir el nivel puede disminuir las llamadas a herramientas.

2. Agrega una instrucción del sistema: Si el uso excesivo persiste después de ajustar el nivel de pensamiento, 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 de 3.5 Flash o 3.1 Pro a 3.6 Flash

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 estrictamente las reglas de parámetros y las convenciones de la API establecidas en toda la familia Gemini 3:
   • Quita los parámetros de temperatura, Top-K y Top-P: Quita estos parámetros personalizados de tu carga útil. Si bien no generarán un error, el modelo los ignorará por completo. En su lugar, usa el parámetro thinking_level o las salidas estructuradas json_schema para controlar el determinismo de la salida.
   • Quita las penalizaciones por frecuencia y presencia: Quita cualquier configuración personalizada para las penalizaciones por frecuencia o presencia para evitar que tus llamadas a la API arrojen errores de tiempo de ejecución.
   • Asegúrate de que la integración del chat no intente completar previamente el modelo: Revisa los arrays del historial de mensajes para asegurarte de que la carga útil de la 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 estricta.
   • Usa thinking_level: Quita las instancias del parámetro thinking_budget obsoleto y usa thinking_level en su lugar.
   • Aplica convenciones estrictas de llamadas a funciones: El FunctionResponse debe coincidir estrictamente con el id, el name y el recuento de ejecución 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. Ten en cuenta los cambios en el flujo de trabajo:
   • Si tu aplicación se basa en bucles conversacionales de varios turnos, prueba tus flujos de trabajo para asegurarte de que la concisión del nuevo paso del modelo no provoque salidas prematuras.
   • Si compilas agentes de scripting básicos o de frontend, supervisa las llamadas exploratorias execute_code 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>) inmediatamente antes de realizar una llamada a la herramienta, es posible que la llamada a la herramienta falle ocasionalmente con un error Malformed_Function_Call. Puedes usar una de las siguientes soluciones alternativas para resolver este problema:

• (Recomendado) Indícale al modelo que coloque sus notas previas a la herramienta dentro de una llamada a función update() dedicada en lugar de texto sin formato. 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 herramientas.

Solución recomendada: Envuelve 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 anterior de <UPDATE> en la solicitud del cliente. Luego, agrega la declaración de 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