Guía para desarrolladores sobre Gemini 4 Hydrogen

Gemini 4 Hydrogen aporta inteligencia de vanguardia con velocidad y eficiencia a la programación diaria y a los flujos de trabajo empresariales basados en agentes.

En este documento, se abordan las capacidades clave de Hydrogen, las convenciones de la API que aplica, cómo migrar a él desde Gemini 3.8 Flash y los modelos anteriores de Gemini 3 Flash, y una guía de inicio rápido. Para obtener una descripción general de la familia de Gemini 4, consulta Comienza a usar Gemini 4.

Funciones clave de Gemini 4 Hydrogen

Gemini 4 Hydrogen incluye las siguientes funciones:

  • Límite unificado de tokens de entrada y salida: Hydrogen tiene un límite unificado de 1,048,576 tokens que incluye los tokens de entrada y salida (en los que la salida incluye el razonamiento, las llamadas a funciones y la respuesta final).
  • Decodificaciones largas de hasta 1,048,576 tokens: Hydrogen extiende la generación más allá de un solo segmento de primer plano de 65,536 tokens (con o sin transmisión) hasta 1,048,576 tokens (menos tus tokens de entrada) tanto en la API de Interactions como en GenerateContent (v1beta1). El SDK de IA generativa de Google controla continuation_token automáticamente en todos los segmentos, o puedes ejecutar decodificaciones en segundo plano asíncronas administradas por el servidor (background=true) o administrar continuation_token en un bucle de continuación personalizado.
  • Niveles de razonamiento: Hydrogen admite LOW, MEDIUM, HIGH (predeterminado) y XHIGH.
  • Almacenamiento en caché implícito con almacenamiento en caché duradero: El almacenamiento en caché implícito se aplica automáticamente a los prefijos de instrucciones compartidos de 4,096 tokens o más, con el almacenamiento en caché duradero habilitado de forma predeterminada. No se admite el almacenamiento en caché de contexto explícito.
  • Entradas de archivos de Office y OpenDocument: Además de PDF y texto sin formato, Hydrogen acepta archivos de Microsoft Office (.docx, .dotx, .doc, .pptx, .ppt, .xlsx, .xls) y OpenDocument (.odt, .odp, .ods) intercalados o de Cloud Storage en GenerateContent y la API de Interactions, incluso dentro de partes multimodales de FunctionResponse.
  • Comprensión de video de agentes: La comprensión de video de agentes está disponible de forma general y está desactivada de forma predeterminada.

Guía de inicio rápido

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

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

Probar en Agent Studio

Para probar instrucciones y configurar gemini-4-hydrogen en la IU de Agent Studio, haz lo siguiente:

  1. Abre Agent Studio en tu proyecto de Google Cloud y selecciona gemini-4-hydrogen en el grupo de Gemini.
  2. En Configuración del modelo, establece las siguientes opciones:
    • Nivel de pensamiento: Elige Low, Medium, High (predeterminado) o Extra high.
    • Región: Selecciona Global, us o eu.
    • Límite de tokens de salida: Se establece entre 32,768 y 1,048,576 (1,048,576 es el valor predeterminado). Agent Studio controla los tokens de continuación automáticamente para las respuestas que superan el límite de una sola solicitud.

Instalación

Actualiza al SDK de IA generativa de Google más reciente. La continuación automática en la API de Interactions requiere google-genai >= 2.34.0 para Python, @google/genai >= 2.32.0 para JavaScript/TypeScript, >= 1.77.0 para Go o >= 1.80.0 para Java (en GenerateContent, la continuación automática requiere >= 2.30.1 para Python, >= 2.29.1 para JavaScript/TypeScript, >= 1.74.0 para Go, >= 1.77.0 para Java, >= 1.26.0 para .NET o >= 1.6.0 para Kotlin):

pip install --upgrade "google-genai>=2.34.0"

Solicitud básica

Envía una solicitud a gemini-4-hydrogen con el SDK de IA generativa de Google o REST:

Python (GenerateContent)

from google import genai
from google.genai import types

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

response = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents="Design a lock-free ring buffer in Rust for multi-producer, single-consumer telemetry ingestion.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(
            thinking_level="HIGH",  # Default: "HIGH" (Valid: "LOW", "MEDIUM", "HIGH", "XHIGH")
        ),
    ),
)
print(response.text)

Python (API de Interactions)

from google import genai

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

# Turn 1: Initial request (stored server-side by default)
turn1 = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Design a lock-free ring buffer in Rust for multi-producer, single-consumer telemetry ingestion.",
    store=True,
)
print(turn1.output_text)

# Turn 2: Continue the conversation using previous_interaction_id
turn2 = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Add a bounded backpressure policy and unit tests for concurrent writers.",
    previous_interaction_id=turn1.id,
)
print(turn2.output_text)

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-hydrogen:generateContent" \
-d '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Provide an architectural review of this Go interface."
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
      "thinkingLevel": "HIGH"
    }
  }
}'

Resultados estructurados

Para generar un resultado JSON que se ajuste a un esquema, configura response_mime_type y response_schema:

from pydantic import BaseModel, Field
from google import genai
from google.genai import types

class ArchitectureReview(BaseModel):
    component: str = Field(description="Service or module name")
    bottlenecks: list[str] = Field(description="Throughput or latency bottlenecks")
    recommended_changes: list[str] = Field(description="Concrete refactoring steps")

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

response = client.models.generate_content(
    model="gemini-4-hydrogen",
    contents="Review a synchronous order-processing pipeline backed by a single primary database at 15,000 writes/sec.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=ArchitectureReview,
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
    ),
)
print(response.text)

Ejemplos de decodificación larga

De forma predeterminada, un solo segmento de la API en primer plano genera hasta 65,536 tokens de salida (de transmisión o sin transmisión), en los que el resultado incluye el razonamiento, las llamadas a funciones y la respuesta final. Para generar finalizaciones de hasta 1,048,576 tokens (menos los tokens de entrada), usa decodificaciones largas en la API de Interactions o GenerateContent. Para conocer las opciones de continuación, las transiciones de estado y las reglas de validación, consulta Decodificaciones largas.

Usa decodificaciones largas con la API de Interactions

En google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0 y Java >= 1.80.0, interactions.create() sigue automáticamente a continuation_token en todos los segmentos cada vez que un segmento devuelve status="requires_continuation". También puedes inhabilitar (automatic_continuation=False) para ejecutar un bucle personalizado almacenado (store=True) o sin estado (store=False):

Python (SDK automático)

from google import genai

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

# Automatic continuation is enabled by default in google-genai >= 2.34.0.
# Unary calls merge all segments into one Interaction with summed usage.
interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Write a complete formal proof of the prime number theorem.",
    generation_config={
        "max_output_tokens": 256000,
        "thinking_level": "high",
    },
)
print(interaction.output_text)
print(f"Merged segment IDs: {interaction.continuation_ids}")
print(f"Initial input tokens: {interaction.usage.initial_input_tokens}")

# Streaming yields events across all segments in order. Intermediate segments
# emit interaction.completed with status="requires_continuation".
stream = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Write a complete formal proof of the prime number theorem.",
    stream=True,
    generation_config={
        "max_output_tokens": 256000,
        "thinking_level": "high",
    },
)
for event in stream:
    if event.event_type == "step.delta" and getattr(event.delta, "text", None):
        print(event.delta.text, end="", flush=True)
    elif (
        event.event_type == "interaction.completed"
        and event.interaction.status != "requires_continuation"
    ):
        print(f"\nFinal status: {event.interaction.status}")

# Optional: Delete each stored server segment (last segment first) before its 7-day TTL expires.
for segment_id in reversed(interaction.continuation_ids or [interaction.id]):
    client.interactions.delete(id=segment_id)

# Set automatic_continuation=False to return after a single segment.
single_segment = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Write a complete formal proof of the prime number theorem.",
    generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
    automatic_continuation=False,
)

Python (bucle personalizado)

from google import genai

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

prompt = "Write a complete formal proof of the prime number theorem."

# Stored loop (store=True, default): chain previous_interaction_id + continuation_token
# without resending input.
segment = client.interactions.create(
    model="gemini-4-hydrogen",
    input=prompt,
    store=True,
    generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
    automatic_continuation=False,
)
full_text = segment.output_text or ""

while segment.status == "requires_continuation" and segment.continuation_token:
    segment = client.interactions.create(
        model="gemini-4-hydrogen",
        previous_interaction_id=segment.id,
        continuation_token=segment.continuation_token,
        generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
        automatic_continuation=False,
    )
    full_text += segment.output_text or ""

# If status == "incomplete", max_output_tokens was exhausted; raise max_output_tokens to continue.
if segment.status == "incomplete" and segment.continuation_token:
    segment = client.interactions.create(
        model="gemini-4-hydrogen",
        previous_interaction_id=segment.id,
        continuation_token=segment.continuation_token,
        generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
    )
    full_text += segment.output_text or ""

# Stateless loop (store=False): resend original input + continuation_token
# with no previous_interaction_id.
stateless_seg = client.interactions.create(
    model="gemini-4-hydrogen",
    input=prompt,
    store=False,
    generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
    automatic_continuation=False,
)
stateless_text = stateless_seg.output_text or ""
while stateless_seg.status == "requires_continuation" and stateless_seg.continuation_token:
    stateless_seg = client.interactions.create(
        model="gemini-4-hydrogen",
        input=prompt,
        store=False,
        continuation_token=stateless_seg.continuation_token,
        generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
        automatic_continuation=False,
    )
    stateless_text += stateless_seg.output_text or ""

REST (almacenado)

# Segment 1: Start a stored interaction (store=true by default)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-hydrogen",
    "store": true,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

# Segment 2: When status is "requires_continuation", pass previous_interaction_id
# and continuation_token without resending input
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-hydrogen",
    "store": true,
    "previous_interaction_id": "SEGMENT_1_ID",
    "continuation_token": "CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

REST (sin estado)

# Segment 1: Stateless interaction (store=false)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-hydrogen",
    "store": false,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

# Segment 2: Resend the original input and continuation_token (no previous_interaction_id)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-hydrogen",
    "store": false,
    "input": "Write a complete formal proof of the prime number theorem.",
    "continuation_token": "CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

Para la ejecución asíncrona administrada por el servidor (background=True con store=True) o la recuperación de puntos de control de transmisión (eventos interaction.status_update emitidos a partir de 65,536 tokens de salida y cada 5,000 tokens a partir de ese momento), usa los siguientes patrones:

Python (en segundo plano)

import time
from google import genai

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

# Start a server-managed background long decode (requires store=True)
interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Write a complete formal proof of the prime number theorem.",
    background=True,
    store=True,
    generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
)

while interaction.status in ("queued", "in_progress"):
    time.sleep(10)
    interaction = client.interactions.get(id=interaction.id)

print(f"Status: {interaction.status}")
print(interaction.output_text)

# Optional: Cancel an in-progress background interaction and resume later
# from its persisted checkpoint continuation_token (if >= 65,536 tokens decoded).
# cancelled = client.interactions.cancel(id=interaction.id)
# if cancelled.continuation_token:
#     resumed = client.interactions.create(
#         model="gemini-4-hydrogen",
#         previous_interaction_id=cancelled.id,
#         continuation_token=cancelled.continuation_token,
#         background=True,
#         generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
#     )

REST (segundo plano)

# Start a server-managed background long decode (requires store=true)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-hydrogen",
    "background": true,
    "store": true,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

# Poll the interaction until status reaches completed, incomplete, failed, or cancelled
curl -s -X GET \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID"

# Optional: Cancel an in-progress background decode
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID/cancel"

# Optional: Resume a cancelled background decode from its checkpoint continuation_token
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-hydrogen",
    "background": true,
    "store": true,
    "previous_interaction_id": "INTERACTION_ID",
    "continuation_token": "CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

Python (puntos de control de transmisión)

from google import genai
from google.genai import errors

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

# With default automatic_continuation=True, stream=True automatically
# reconnects from the latest interaction.status_update checkpoint (65,536
# output tokens, then every 5,000 tokens) if no output was yielded after the
# checkpoint. If a disconnect occurs after output was yielded since the last
# checkpoint, the SDK raises ContinuationInterruptedError so you can resume
# from err.continuation_token.
stream = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Write a complete formal proof of the prime number theorem.",
    stream=True,
    store=True,
    generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
)

try:
    for event in stream:
        if event.event_type == "step.delta" and getattr(event.delta, "text", None):
            print(event.delta.text, end="", flush=True)
except errors.ContinuationInterruptedError as err:
    # Resuming from a mid-segment checkpoint regenerates any output yielded
    # after that checkpoint.
    if err.interaction_id and err.continuation_token:
        resumed_stream = client.interactions.create(
            model="gemini-4-hydrogen",
            previous_interaction_id=err.interaction_id,
            continuation_token=err.continuation_token,
            stream=True,
            store=True,
            generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
        )
        for event in resumed_stream:
            if event.event_type == "step.delta" and getattr(event.delta, "text", None):
                print(event.delta.text, end="", flush=True)

REST (puntos de control de transmisión)

# Start a streaming interaction; save interaction.id from interaction.created
# and the latest continuation_token from interaction.status_update SSE events
curl -N -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-hydrogen",
    "stream": true,
    "store": true,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

# Resume a dropped stream from the last saved checkpoint continuation_token
# (for store=false, resend the original input instead of previous_interaction_id)
curl -N -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-hydrogen",
    "stream": true,
    "store": true,
    "previous_interaction_id": "SEGMENT_ID",
    "continuation_token": "CHECKPOINT_CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

Usa decodificaciones largas con GenerateContent

En GenerateContent (v1beta1), establece max_output_tokens en un valor superior a 65,536 (hasta 1,048,576) para las solicitudes de transmisión o sin transmisión. El SDK de IA generativa de Google sigue automáticamente continuation_token en todos los segmentos cuando finish_reason es CONTINUATION (establece automatic_continuation=False en GenerateContentConfig para inhabilitar esta opción) o puedes pasar continuation_token en un bucle personalizado:

from google import genai
from google.genai import types

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

# Automatic continuation is enabled by default in google-genai >= 2.30.1.
# Chunks across all continuation requests are yielded as a single stream.
for chunk in client.models.generate_content_stream(
    model="gemini-4-hydrogen",
    contents="Write a complete formal proof of the prime number theorem.",
    config=types.GenerateContentConfig(
        max_output_tokens=256000,
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
    ),
):
    print(chunk.text, end="")

# Set automatic_continuation=False to disable automatic continuation.
for chunk in client.models.generate_content_stream(
    model="gemini-4-hydrogen",
    contents="Write a complete formal proof of the prime number theorem.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
        automatic_continuation=False,
    ),
):
    print(chunk.text, end="")

REST (bucle de continuación personalizado)

# Request 1: Initial request with maxOutputTokens > 65,536
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-hydrogen:generateContent" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Write a complete formal proof of the prime number theorem."}]
    }],
    "generationConfig": {
      "maxOutputTokens": 131072,
      "thinkingConfig": {"thinkingLevel": "HIGH"}
    }
  }'

# Request 2: Resend the original request with top-level continuationToken
# from Request 1 (candidates[0].continuationToken)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-hydrogen:generateContent" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Write a complete formal proof of the prime number theorem."}]
    }],
    "continuationToken": "CONTINUATION_TOKEN",
    "generationConfig": {
      "maxOutputTokens": 131072,
      "thinkingConfig": {"thinkingLevel": "HIGH"}
    }
  }'

Reglas de API y convenciones de comportamiento obligatorias

Hydrogen aplica las convenciones de las siguientes secciones para los niveles de pensamiento, los límites de tokens, el almacenamiento en caché, los parámetros de generación y la ejecución de herramientas de varios turnos.

Niveles de razonamiento

Hydrogen admite cuatro valores de thinking_level (thinking_budget y MINIMAL devuelven un error de validación HTTP 400). En la siguiente tabla, se enumeran los niveles de razonamiento y sus cargas de trabajo recomendadas:

Nivel de pensamiento Cargas de trabajo recomendadas
XHIGH Razonamiento profundo, demostraciones matemáticas, análisis científicos y las tareas de ingeniería de software de varios archivos más complejas.
HIGH (predeterminado en gemini-4-hydrogen) Bucles de herramientas de agentes de varios pasos, generación de código, refactorización de arquitectura y análisis multimodal complejo.
MEDIUM Programación general, uso de herramientas, preguntas y respuestas sobre documentos y comprensión de videos con latencia equilibrada.
LOW Clasificación, enrutamiento, resumen y extracción de metadatos estructurados de alta capacidad de procesamiento.

Límites de tokens, almacenamiento en caché y facturación

Hydrogen aplica las siguientes reglas de token, almacenamiento en caché, contenido multimedia y facturación:

  • Límite unificado de tokens de entrada y salida, y límites de salida de una sola solicitud: Los presupuestos de tokens y los límites por solicitud funcionan de la siguiente manera:
    • El límite general de tokens del modelo es de 1,048,576 tokens y, además, incluye los tokens de entrada y salida (en los que la salida incluye el razonamiento, las llamadas a funciones y la respuesta final). max_output_tokens controla el límite de tokens de salida para la generación (hasta 1,048,576 menos tus tokens de entrada); establecer max_output_tokens en un valor mayor que 1,048,576 devuelve un error HTTP 400.
    • Para evitar que se completen respuestas largas de forma involuntaria, el presupuesto de salida predeterminado y el límite de primer plano de un solo segmento (razonamiento, llamadas a funciones y respuesta del modelo) es de 65,536 tokens para las solicitudes de transmisión y las que no son de transmisión.
    • Los tokens de razonamiento generados en HIGH (predeterminado) y XHIGH se consideran para max_output_tokens y se acumulan en el contexto de varios turnos cuando conservas las firmas de pensamiento en los turnos. Establece un valor de max_output_tokens lo suficientemente alto para el pensamiento y el resultado final, evita umbrales de compactación de contexto demasiado bajos en los entornos de programación de varios turnos o establece thinking_level="MEDIUM" en los turnos de herramientas sensibles a la latencia.
  • Decodificaciones largas: Las respuestas en primer plano de un solo segmento generan hasta 65,536 tokens de salida (con o sin transmisión). Para extender el resultado de un solo turno hasta 1,048,576 tokens (menos los tokens de entrada) en la API de Interactions o GenerateContent (v1beta1), consulta Decodificaciones largas.
  • Almacenamiento en caché de contexto: No se admite el almacenamiento en caché de contexto explícito. El almacenamiento en caché implícito (con el almacenamiento en caché duradero habilitado de forma predeterminada) se aplica automáticamente a los prefijos de instrucciones compartidos de 4,096 tokens o más, por lo que debes colocar el contenido estático al principio de la instrucción.
  • Entradas de Office y OpenDocument: Pasa archivos de Word (application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.openxmlformats-officedocument.wordprocessingml.template, application/msword, application/vnd.oasis.opendocument.text), PowerPoint (application/vnd.openxmlformats-officedocument.presentationml.presentation, application/vnd.ms-powerpoint, application/vnd.oasis.opendocument.presentation) y Excel o hojas de cálculo de OpenDocument (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel, application/vnd.oasis.opendocument.spreadsheet) de forma intercalada o por URI de Cloud Storage (gs://) con inlineData o fileData en GenerateContent (incluidas las partes de FunctionResponse) y entradas de document (incluidos los resultados de las herramientas) en la API de Interactions.
  • Video de agente: Los videos subidos se establecen de forma predeterminada en media_processing="static". Establece media_processing="agentic" para habilitar el procesamiento de video agéntico.
  • Recuento de tokens y facturación: Se cuenta y factura cada token que procesa el modelo, incluidos los tokens de razonamiento, las instrucciones internas del sistema de herramientas y las declaraciones de funciones cuando se usa la fundamentación. La fundamentación con la Búsqueda de Google también se sigue facturando por consulta.

Parámetros, llamada a funciones y validación de chat

Hydrogen aplica las siguientes reglas para los parámetros de generación, las llamadas a la herramienta, las firmas de pensamiento y el historial de chat:

  • Parámetros de muestreo ignorados (temperature, top_k, top_p): El backend ignora los valores personalizados. Controla la profundidad del razonamiento con thinking_level y el formato de salida con response_schema.
  • Parámetros no admitidos (frequency_penalty, presence_penalty y candidate_count mayores que 1): Pasar frequency_penalty, presence_penalty o candidate_count mayores que 1 (candidateCount se fija en 1) devuelve un error de HTTP 400. Quita estos parámetros de tus solicitudes.
  • Llamada a funciones y firmas de pensamiento: Las declaraciones de herramientas, las llamadas a herramientas paralelas y la reproducción de thought_signature de varios turnos siguen estas reglas:

    • Simetría de giro: Cada FunctionResponse debe coincidir con el id, el name y el orden del FunctionCall anterior.
    • Partes de FunctionResponse multimodales: Incluye documentos de Office, hojas de cálculo, presentaciones, PDFs, imágenes, audio y video dentro de partes de FunctionResponse multimodales (o resultados de herramientas en la API de Interactions) en lugar de agregarlos como partes separadas del turno del usuario.
    • Ubicación de la llamada a función paralela thought_signature: Cuando el modelo emite varias partes functionCall paralelas en un solo turno de model, solo la primera parte functionCall contiene el thought_signature. Omitir thought_signature de la primera parte de functionCall en el turno de usuario activo, duplicarlo en partes paralelas posteriores de functionCall o intercalar turnos de functionCall y functionResponse devuelve un error HTTP 400; mantén todas las partes paralelas de functionCall en un solo turno de model seguido de todas las partes de functionResponse que coincidan en un solo turno de user. Para obtener más información, consulta Firmas de amenazas.
    • Preservación de thought_signature entre turnos: Pasa de vuelta cada thought_signature dentro de su Part original en todos los turnos anteriores en el historial de chat de varios turnos (partes functionCall y text finales), no solo dentro del turno del usuario activo. Aunque la validación de la firma HTTP 400 solo se aplica a los pasos functionCall dentro del turno del usuario activo, quitar los valores thought_signature de los turnos anteriores o sustituir los valores de omisión, como skip_thought_signature_validator, quita el contexto de razonamiento, degrada la calidad del resultado y puede causar motivos de finalización MALFORMED_FUNCTION_CALL.
    • Formato previo a la herramienta: Separa las instrucciones intercaladas con \n\n y evita el texto no estructurado antes de las llamadas a la herramienta. Para registrar el estado intermedio antes de una llamada a la herramienta, usa una declaración de función dedicada:

      {
        "name": "update",
        "description": "Update working notes before tool execution",
        "parameters": {
          "type": "OBJECT",
          "properties": {
            "previous_step": {"type": "STRING"},
            "plan": {"type": "STRING"},
            "next_step": {"type": "STRING"}
          },
          "required": ["previous_step", "plan", "next_step"]
        }
      }
      
  • Validación de la secuencia de chat: Las cargas útiles de chat de varios turnos aplican las siguientes restricciones:

    • Las cargas útiles del historial no pueden terminar con un turno de rol de model.
    • No se admiten las respuestas predefinidas del modelo.

Decodificaciones largas

La decodificación larga divide una generación de hasta 1,048,576 tokens (menos tus tokens de entrada) en varios segmentos, ya sea en la API de Interactions o en GenerateContent (v1beta1). En la API de Interactions, cada segmento en primer plano (stream=true o stream=false) genera hasta 65,536 tokens de salida y devuelve status="requires_continuation" con un continuation_token encriptado, o bien puedes establecer background=true (store=true) para que el servidor ejecute el bucle de continuación de forma asíncrona y almacene el resultado combinado en un Interaction. En GenerateContent, cada segmento de transmisión o que no es de transmisión genera hasta 65,536 tokens de salida antes de emitir finish_reason=CONTINUATION con continuation_token, y continúa hasta finish_reason=STOP. En Agent Studio, establecer el límite de tokens de salida en un valor superior a 65,536 y hasta 1,048,576 controla los tokens de continuación automáticamente. Para ver muestras de código ejecutables, consulta los ejemplos de la guía de inicio rápido de decodificación larga.

Cuándo usar la decodificación larga

La mayoría de las solicitudes finalizan dentro del límite de salida de 65,536 tokens por segmento. Usa la decodificación larga solo cuando una respuesta necesite más resultados que eso. La decodificación larga le da al modelo más espacio para razonar; no hace que las respuestas sean más largas (usa thinking_level para controlar la profundidad del razonamiento).

Carga de trabajo ¿Quieres usar la decodificación larga? Por qué
Matemáticas, ciencias, investigación y pruebas formales complejas Sí El modelo puede usar más de 65,536 tokens para explorar y verificar su razonamiento.
Las tareas de programación y con agentes más difíciles Sí Algunas tareas necesitan más de 65,536 tokens de razonamiento y código en una sola respuesta. La mayoría de las tareas de programación y de agentes finalizan con menos de 65,536 tokens.
Arneses de evaluación que se detienen en el límite de salida Sí La decodificación larga evita que se corten las respuestas cuando el modelo dedica un segmento completo de 65,536 tokens a pensar.
Chat, preguntas y respuestas, resumen, clasificación y extracción No Estas tareas finalizan con menos de 65,536 tokens.
Solicitudes de una longitud fija, como "escribe un libro de 700,000 palabras" No El modelo no sigue los objetivos de longitud.
Agentes que llaman a herramientas en muchos turnos cortos No Cada turno es breve. Los resultados grandes en cada turno completan rápidamente el límite unificado de 1,048,576 tokens de entrada y salida.
Instrucciones cercanas al límite de entrada de 1,048,576 tokens No La salida solo puede usar 1,048,576 tokens menos tu entrada.
Solicitudes sensibles a la latencia No La decodificación larga puede ejecutarse durante varios minutos.

Elige una opción de continuación

Selecciona un patrón de continuación según la plataforma de la API, la postura de almacenamiento y el entorno de ejecución. Todas las opciones de la siguiente tabla alcanzan el mismo límite de 1,048,576 tokens (menos los tokens de entrada) en gemini-4-hydrogen.

Opción de continuación Superficie de la API Quién inicia cada segmento Tokens por segmento Límite de tiempo por solicitud Almacenamiento del servidor Ideal para
Continuación automática del SDK de IA generativa de Google (recomendado) API de Interactions (v1beta1) SDKs de IA generativa de Google: Python (google-genai >= 2.34.0), JavaScript/TypeScript (@google/genai >= 2.32.0), Go (>= 1.77.0) y Java (>= 1.80.0) Hasta 65,536 (stream=true o stream=false) 20 minutos por segmento Almacenamiento predeterminado de 7 días en el servidor (store=true) o ninguno (store=false) La mayoría de las aplicaciones de la API de Interactions con o sin estado
Ciclo administrado por el servidor en segundo plano (background=true) API de Interactions (v1beta1) Bucle del servidor de Agent Platform; tu código sondea get Administrado del lado del servidor hasta max_output_tokens Asíncrono (no se requiere una transmisión de cliente abierta) Almacenamiento del servidor de 7 días (se requiere store=true) Trabajos asíncronos, emisores de llamadas de .NET/Kotlin y persistencia de un solo registro
Bucle almacenado personalizado en primer plano (store=true) API de Interactions (v1beta1) Tu código (previous_interaction_id + continuation_token, no input) Hasta 65,536 (stream=true o stream=false; puntos de control que comienzan en 65,536 y cada 5,000 tokens a partir de ese momento) 20 minutos por segmento Almacenamiento en el servidor durante 7 días (store=true) Recuperación de puntos de control personalizados y emisores de REST
Bucle sin estado en primer plano personalizado (store=false) API de Interactions (v1beta1) Tu código (input original + continuation_token, sin previous_interaction_id) Hasta 65,536 (stream=true o stream=false; puntos de control que comienzan en 65,536 y cada 5,000 tokens a partir de ese momento) 20 minutos por segmento Sin almacenamiento en el servidor (flujos de trabajo de retención de datos cero) Arneses de REST personalizados que requieren una ejecución sin estado
Continuación automática del SDK de IA generativa de Google (recomendado) GenerateContent (v1beta1) SDKs de IA generativa de Google: Python (>= 2.30.1), JavaScript/TypeScript (>= 2.29.1), Go (>= 1.74.0), Java (>= 1.77.0), .NET (>= 1.26.0) y Kotlin (>= 1.6.0) Hasta 65,536 (generate_content_stream o generate_content) 20 minutos por segmento Sin almacenamiento en el servidor (flujos de trabajo de retención de datos cero) Aplicaciones de GenerateContent existentes
Bucle de continuación personalizado GenerateContent (v1beta1) Tu código (contents original + continuation_token) Hasta 65,536 (streamGenerateContent o generateContent; puntos de control que comienzan en 65,536 y cada 5,000 tokens a partir de ese momento) 20 minutos por segmento Sin almacenamiento en el servidor (flujos de trabajo de retención de datos cero) Llamadores de REST GenerateContent directos y arneses de evaluación

Requisitos de la versión de la API y del SDK

Las decodificaciones largas requieren la siguiente versión de la API y las versiones mínimas del SDK:

  • Requisito de la API de v1beta1 (problema conocido): La decodificación larga (continuation_token) tanto en la API de Interactions como en GenerateContent (generateContent y streamGenerateContent) solo se admite en la API de v1beta1 (no en v1) en Agent Platform. El SDK de IA generativa de Google usa v1beta1 de forma predeterminada, a menos que se especifique api_version='v1' en http_options (o api_version="v1" en interactions.create). Para las llamadas de REST directas, usa la ruta del endpoint /v1beta1/.
  • Versiones del SDK y compatibilidad con OpenAI: Para la continuación automática en la API de Interactions, actualiza a Python google-genai >= 2.34.0, JavaScript/TypeScript @google/genai >= 2.32.0, Go >= 1.77.0 o Java >= 1.80.0 (para .NET y Kotlin en la API de Interactions, usa background=true o un bucle de continuación personalizado). Para continuar automáticamente en GenerateContent, actualiza a Python >= 2.30.1, JavaScript/TypeScript >= 2.29.1, Go >= 1.74.0, Java >= 1.77.0, .NET >= 1.26.0 o Kotlin >= 1.6.0. Las versiones anteriores del SDK y la capa de compatibilidad con OpenAI no pueden recuperar respuestas largas con tokens de continuación.

Reglas de continuación de la API de Interactions

Las siguientes transiciones de estado, reglas de encadenamiento y comportamientos de almacenamiento se aplican a las decodificaciones largas en la API de Interactions.

Valores de estado y presupuesto de tokens de salida

Cuando se omite generation_config.max_output_tokens en una solicitud a la API de Interactions, el presupuesto total de salida se establece de forma predeterminada en 65,536 tokens (lo que coincide con el límite de primer plano de un solo segmento de 65,536 tokens para las solicitudes de transmisión y las que no son de transmisión). Establece generation_config.max_output_tokens en un valor mayor que 65,536 (hasta 1,048,576 menos tokens de entrada) para decodificaciones largas de varios segmentos en los modos en primer plano y background=true. El servidor devuelve los siguientes valores de estado:

  • requires_continuation: Se alcanzó el límite de salida de 65,536 tokens por segmento antes de max_output_tokens. Pasa el continuation_token devuelto en la siguiente solicitud para continuar con la decodificación.
  • incomplete: Se agotó el presupuesto total de max_output_tokens. Si continúas con continuation_token sin aumentar max_output_tokens, se muestra un error HTTP 400 (max_output_tokens has already been exhausted). Aumenta max_output_tokens en la siguiente solicitud para reanudar la decodificación.
  • completed: La generación finalizó de forma natural y se borra continuation_token.

Encadenamiento, cambio de modo y almacenamiento de segmentos

Las solicitudes de continuación en la API de Interactions aplican las siguientes reglas:

  • Continuación almacenada (store=true, predeterminado): Pasa previous_interaction_id establecido en el segmento id que emitió el continuation_token junto con continuation_token y omite input (el segmento almacenado ya contiene la entrada del turno). Siempre vincula cada continuation_token con el previous_interaction_id del segmento que lo emitió. Si pasas un continuation_token en una interacción que ya se completed, se devuelve un error de HTTP 400.
  • Continuación sin estado (store=false): Omite previous_interaction_id y vuelve a enviar el input original junto con continuation_token en cada segmento.
  • Cambia los modos de store entre segmentos: Puedes cambiar de almacenado (store=true) a sin estado (store=false) a mitad de la decodificación omitiendo previous_interaction_id y volviendo a enviar el input original con continuation_token. No se admite el cambio de sin estado (store=false) a almacenado (store=true) porque no existe una interacción superior almacenada para previous_interaction_id.
  • Cambio y ramificación entre el modo en primer plano y el modo background=true: Las continuaciones almacenadas (store=true) pueden cambiar entre la ejecución en primer plano (background=false) y en segundo plano (background=true) en todos los segmentos, lo que incluye reanudar una interacción cancelada de background=true desde su punto de control continuation_token (que se conserva a partir de 65,536 tokens de salida y cada 5,000 tokens a partir de ese momento) en modo en segundo plano o en primer plano. Si vuelves a usar los mismos previous_interaction_id y continuation_token, se crearán continuaciones ramificadas independientes.
  • Aplicación forzosa de límites de turnos: Iniciar un turno de usuario nuevo (previous_interaction_id con un input nuevo y sin continuation_token) desde un segmento cuyo estado es requires_continuation o incomplete devuelve un error HTTP 400. Termina de continuar la decodificación a completed o ramifica tu próximo turno desde la interacción completed más reciente. Una vez que el segmento final alcance completed, pasar el id de ese segmento final como previous_interaction_id reconstruirá el historial de conversación completo en todos los segmentos anteriores.
  • Coherencia de los parámetros en los segmentos: Si cambias model, system_instruction o las declaraciones de funciones (tools) en un segmento de continuación, se muestra un error de HTTP 400. Mantén thinking_level y las herramientas integradas sin cambios en los segmentos (consulta Problemas conocidos).
  • Comportamiento de un solo segmento de get, list y delete: En el modo en primer plano (background=false), cada segmento se almacena como un recurso Interaction independiente (interactions.get(id) muestra solo ese segmento, interactions.list() enumera cada segmento por separado y interactions.delete(id) borra solo ese segmento; cuando borres una cadena de segmentos, hazlo en orden inverso, desde el último segmento hacia atrás). En el SDK de IA generativa de Google con automatic_continuation=True (stream=False), interactions.create() combina todos los segmentos en la devolución y propaga interaction.continuation_ids con los IDs de segmento ordenados (que terminan con interaction.id). Si un segmento posterior falla, excede un timeout numérico por llamada o se interrumpe a mitad de la transmisión después de que se avanzó más allá de un punto de control reanudable, el SDK genera ContinuationInterruptedError con partial_interaction, continuation_token, interaction_id y continuation_ids para que puedas reanudar desde continuation_token.

Reglas de bucle personalizado de GenerateContent

En un bucle de continuación personalizado de GenerateContent, sigue estas reglas:

  • Establece max_output_tokens en un valor superior a 65,536 (hasta 1,048,576) y vuelve a enviar los valores originales de contents, system_instruction y tools en cada solicitud de continuación junto con el valor más reciente de continuation_token (un campo de nivel superior en GenerateContentRequest en REST o en GenerateContentConfig en el SDK de IA generativa de Google).
  • No agregues el resultado parcial del modelo a contents ni envíes una instrucción de seguimiento para pedirle al modelo que continúe.
  • Sigue repitiendo el bucle mientras finish_reason sea CONTINUATION y continuation_token esté presente, incluso si un segmento usó los 65,536 tokens en el razonamiento (parts: [{"text": ""}]). Si finish_reason es MAX_TOKENS cuando continuation_token está presente, aumenta max_output_tokens en la siguiente solicitud.
  • Combina las partes acumuladas en un solo turno de model para el historial de varios turnos solo después de STOP.

Recuento de tokens, compactación y almacenamiento en caché implícito

La contabilidad y el almacenamiento en caché de tokens en los segmentos de continuación funcionan de la siguiente manera:

  • En la API de Interactions, las llamadas interactions.create() que no son de transmisión con automatic_continuation=True y las interacciones background=true administradas por el servidor suman los recuentos de tokens en todos los segmentos de usage (total_input_tokens, total_cached_tokens, total_output_tokens, total_thought_tokens, total_tokens), lo que conserva el recuento de instrucciones del primer segmento en usage.initial_input_tokens. En los bucles personalizados en primer plano y los eventos de interaction.completed transmitidos, el usage de cada segmento informa solo el delta de ese segmento, por lo que se suman los campos usage en todos los segmentos para obtener el total de tokens facturados.
  • En GenerateContent, el SDK de IA generativa de Google para Python (generate_content y generate_content_stream) acumula el total de tokens facturados en los segmentos del usage_metadata final y conserva initial_prompt_token_count. En los bucles de REST personalizados, suma los valores finales de prompt_token_count, cached_content_token_count, candidates_token_count y thoughts_token_count en todos los segmentos.
  • Debido a que cada segmento de continuación en primer plano vuelve a completar previamente la conversación y los tokens generados anteriormente como entrada, usage.total_input_tokens (en la API de Interactions) y prompt_token_count (en GenerateContent) aumentan en todos los segmentos. No uses recuentos de entradas acumulativos para activar la compactación de contexto en los arneses de agentes. En su lugar, verifica usage.initial_input_tokens (o initial_prompt_token_count en GenerateContent) y compacta solo después de que finalice el turno (status="completed" o sin continuation_token).
  • Cada segmento de continuación vuelve a completar previamente la instrucción y los tokens decodificados con anterioridad, y califica automáticamente para el almacenamiento en caché de contexto implícito (mínimo de 4,096 tokens, con el almacenamiento en caché duradero habilitado de forma predeterminada) cuando los segmentos se ejecutan de forma consecutiva. Los segmentos completados se facturan al final de cada segmento, incluso si un segmento posterior falla o se cancela.

Migra a Hydrogen desde 3.8 Flash

El siguiente comportamiento es diferente del de gemini-3.8-flash y los modelos anteriores de Gemini 3 Flash:

  • Hydrogen tiene un límite unificado de 1,048,576 tokens para la entrada y la salida (en la que la salida incluye el pensamiento, las llamadas a funciones y la respuesta final), en lugar de límites de entrada y salida independientes. El resultado en primer plano de un solo segmento tiene un límite de 65,536 tokens (con o sin transmisión) y se puede extender hasta 1,048,576 tokens con decodificaciones largas en la API de Interactions o GenerateContent (se controla automáticamente en el SDK de IA generativa de Google, con background=true en la API de Interactions o con continuation_token en bucles personalizados).
  • El valor predeterminado de thinking_level es HIGH (se cambió de MEDIUM el gemini-3.8-flash), y se admite XHIGH para tareas de razonamiento profundo (deja espacio para la compactación de contexto para los seguimientos de razonamiento de HIGH y XHIGH en los arneses de programación de varios turnos, o establece MEDIUM en los turnos sensibles a la latencia). thinking_budget y thinking_level="MINIMAL" devuelven un error de HTTP 400.
  • No se admite el almacenamiento en caché de contexto explícito (cached_content). El almacenamiento en caché implícito se aplica automáticamente con un mínimo de 4,096 tokens (reducido de 6,144 tokens en gemini-3.8-flash), con el almacenamiento en caché duradero habilitado de forma predeterminada.
  • Los archivos de Microsoft Office (.docx, .dotx, .doc, .pptx, .ppt, .xlsx, .xls) y OpenDocument (.odt, .odp, .ods) se admiten de forma intercalada o por URI de Cloud Storage (gs://), incluso dentro de partes multimodales de FunctionResponse.
  • Los turnos de llamadas paralelas a funciones aplican una ubicación estricta de thought_signature (solo la primera parte de functionCall en un turno paralelo lleva thought_signature; omitirla en el turno activo o duplicarla en partes de functionCall hermanas posteriores devuelve un error HTTP 400). Conserva las partes de thought_signature en todos los turnos anteriores (tanto las partes de functionCall como las de text finales) para mantener la calidad del razonamiento y evitar los motivos de finalización de MALFORMED_FUNCTION_CALL.
  • Se factura cada token que procesa el modelo, incluidas las instrucciones internas del sistema de herramientas y las declaraciones de funciones cuando se usa la fundamentación.

Para obtener una comparación en paralelo, consulta Migra desde los modelos de Gemini 3.

 client = genai.Client(
     enterprise=True,
     project="PROJECT_ID",
     location="global", # Supports "global", "us", and "eu"
 )

 response = client.models.generate_content(
-    model="gemini-3.8-flash",
+    model="gemini-4-hydrogen",
     contents=prompt,
     config=types.GenerateContentConfig(
-        temperature=0.0,
-        cached_content="projects/.../cachedContents/...", # Explicit caching unsupported
         thinking_config=types.ThinkingConfig(
-            thinking_budget=16384, # Returns HTTP 400 instead of mapping silently
-            thinking_level="MINIMAL", # MINIMAL unsupported on Gemini 4 Hydrogen
+            thinking_level="HIGH", # Valid: "LOW", "MEDIUM", "HIGH" (default), "XHIGH"
         ),
     ),
 )

Para migrar desde gemini-3.8-flash o modelos anteriores de Gemini 3 Flash, haz lo siguiente:

  1. Actualiza el ID del modelo a gemini-4-hydrogen.
  2. Actualiza al SDK de IA generativa de Google más reciente y ten en cuenta el límite unificado de tokens de entrada y salida: Actualiza a google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0 o Java >= 1.80.0 para la continuación automática de la API de Interactions (o >= 2.30.1 Python/>= 2.29.1 JavaScript en GenerateContent). Los tokens de entrada y salida (incluidos los de razonamiento y las llamadas a funciones) comparten el límite unificado de 1,048,576 tokens. Para los resultados que superen los 65,536 tokens (hasta 1,048,576 tokens) en la API de Interactions o GenerateContent, establece max_output_tokens en un valor superior a 65,536 para que el SDK de IA generativa de Google continúe automáticamente en los segmentos (o usa background=true o un bucle continuation_token personalizado).
  3. Actualiza la configuración de thinking_level: Reemplaza thinking_budget y MINIMAL por thinking_level establecido en LOW, MEDIUM, HIGH (predeterminado en gemini-4-hydrogen) o XHIGH (usa minúsculas "low", "medium", "high" o "xhigh" en la API de Interactions). Si tu carga de trabajo dependía de MEDIUM como el valor predeterminado en gemini-3.8-flash, establece de forma explícita thinking_level="MEDIUM" para mantener una latencia de razonamiento equivalente.
  4. Quita el almacenamiento en caché explícito y carga previamente el contenido estático de la instrucción (4,096 tokens o más) para el almacenamiento en caché implícito automático.
  5. Verifica la preservación de thought_signature de varios turnos y paralelos: Conserva thought_signature en todos los turnos anteriores (tanto en las partes functionCall como en las partes text finales) en lugar de quitar las firmas entre turnos, y mantén thought_signature solo en la primera parte functionCall de un turno de llamada a la herramienta paralelo.
  6. Quita los parámetros que no tienen efecto o no son compatibles: Quita los campos de generación ignorados y rechazados de la siguiente manera:
    • Quita temperature, top_p y top_k, que se ignoran.
    • Quita frequency_penalty, presence_penalty y cualquier valor de candidate_count mayor que 1.
    • Quita las respuestas predefinidas del modelo de los historiales de conversaciones.

Lista de tareas de resumen para desarrolladores

Usa la siguiente lista de tareas para verificar tu integración de Hydrogen:

Problemas conocidos

Los siguientes problemas conocidos se aplican a las decodificaciones largas de Hydrogen:

  • La decodificación de contenido largo requiere v1beta1: La decodificación de contenido largo (continuation_token) en la API de Interactions y la API de GenerateContent (generateContent y streamGenerateContent) solo se admite en la API de v1beta1 (no en v1) en Agent Platform. El SDK de IA generativa de Google usa v1beta1 de forma predeterminada, a menos que se establezca api_version='v1' en http_options (o api_version="v1" en interactions.create). Para las llamadas de REST directas, usa la ruta del extremo /v1beta1/.
  • Cambios de parámetros en los segmentos de continuación de la API de Interactions: Cambiar model, system_instruction o las declaraciones de funciones en los segmentos de continuación devuelve un error de HTTP 400, mientras que los cambios a mitad de la decodificación en generation_config.thinking_level o las herramientas integradas (google_search, code_execution, url_context) no se rechazan por la validación del servidor. Mantén thinking_level y las herramientas integradas sin cambios en todos los segmentos de un bucle de continuación.

¿Qué sigue?