Guia para desenvolvedores sobre o Gemini 4 Hydrogen

O Gemini 4 Hydrogen traz inteligência de ponta com velocidade e eficiência para a programação diária e os fluxos de trabalho agênticos das empresas.

Este documento aborda os principais recursos do Hydrogen, as convenções de API que ele aplica, como migrar do Gemini 3.8 Flash e de modelos anteriores do Gemini 3 Flash para ele, além de um guia de início rápido. Para uma visão geral da família Gemini 4, consulte Começar a usar o Gemini 4.

Principais recursos do Gemini 4 Hydrogen

O Gemini 4 Hydrogen inclui os seguintes recursos:

  • Limite unificado de tokens de entrada e saída: o Hydrogen tem um limite unificado de 1.048.576 tokens que inclui tokens de entrada e saída (em que a saída inclui raciocínio, chamadas de função e a resposta final).
  • Decodificações longas de até 1.048.576 tokens: o Hydrogen estende a geração além de um único segmento de primeiro plano de 65.536 tokens (com ou sem streaming) até 1.048.576 tokens (menos os tokens de entrada) na API Interactions e no GenerateContent (v1beta1). O SDK de IA generativa do Google processa continuation_token automaticamente em todos os segmentos, ou você pode executar decodificações em segundo plano assíncronas gerenciadas pelo servidor (background=true) ou gerenciar continuation_token em um loop de continuação personalizado.
  • Níveis de raciocínio: o Hydrogen é compatível com LOW, MEDIUM, HIGH (padrão) e XHIGH.
  • Armazenamento em cache implícito com armazenamento em cache durável: o armazenamento em cache implícito é aplicado automaticamente a prefixos de comandos compartilhados de 4.096 tokens ou mais, com o armazenamento em cache durável ativado por padrão. Não há suporte para o armazenamento em cache de contexto explícito.
  • Entradas de arquivos do Office e do OpenDocument: além de PDF e texto simples, o Hydrogen aceita arquivos do Microsoft Office (.docx, .dotx, .doc, .pptx, .ppt, .xlsx, .xls) e do OpenDocument (.odt, .odp, .ods) inline ou do Cloud Storage no GenerateContent e na API Interactions, inclusive em partes multimodais do FunctionResponse.
  • Compreensão agêntica de vídeos: esse recurso está em disponibilidade geral e desativado por padrão.
  • Ciclo de vida de lançamento de curto prazo: o Hydrogen é uma versão de disponibilidade geral (GA) de curto prazo sujeita a uma política de aviso de desativação de no mínimo 45 dias. Para detalhes sobre o ciclo de vida, consulte Versões e ciclo de vida do modelo.

Guia de início rápido

Antes de começar, autentique-se na Gemini Enterprise Agent Platform usando o Application Default Credentials (ADC) ou uma chave de API. Consulte Começar a usar a plataforma de agentes para mais informações.

Nos blocos de código a seguir, substitua PROJECT_ID pelo ID do projeto.

Teste no Agent Studio

Para testar comandos e configurar gemini-4-hydrogen na UI do Agent Studio, faça o seguinte:

  1. Abra o Agent Studio no seu projeto do Google Cloud e selecione gemini-4-hydrogen no grupo do Gemini.
  2. Em Configurações do modelo, configure as seguintes opções:
    • Nível de raciocínio: escolha Low, Medium, High (padrão) ou Extra high.
    • Região: selecione Global, us ou eu.
    • Limite de tokens de saída: defina entre 32,768 e 1,048,576 (1,048,576 é o padrão). O Agent Studio processa tokens de continuação automaticamente para respostas acima do limite de solicitação única.

Instalação

Faça upgrade para o SDK de IA generativa do Google mais recente. A continuação automática na API Interactions requer google-genai >= 2.34.0 para Python, @google/genai >= 2.32.0 para JavaScript/TypeScript, >= 1.77.0 para Go ou >= 1.80.0 para Java (no GenerateContent, a continuação automática requer >= 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 ou >= 1.6.0 para Kotlin):

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

Solicitação básica

Envie uma solicitação para gemini-4-hydrogen usando o SDK de IA generativa do Google ou 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 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"
    }
  }
}'

Resposta estruturada

Para gerar uma saída JSON que esteja em conformidade com um esquema, configure response_mime_type e 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)

Exemplos de decodificação longa

Por padrão, um único segmento de API em primeiro plano gera até 65.536 tokens de saída (com ou sem streaming), em que a saída inclui o raciocínio, as chamadas de função e a resposta final. Para gerar conclusões de até 1.048.576 tokens (menos os tokens de entrada), use decodificações longas na API Interactions ou na GenerateContent. Para opções de continuação, transições de status e regras de validação, consulte Decodificações longas.

Usar decodificações longas com a API Interactions

Em google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0 e Java >= 1.80.0, interactions.create() segue automaticamente continuation_token entre segmentos sempre que um segmento retorna status="requires_continuation". Também é possível desativar (automatic_continuation=False) para executar um loop personalizado armazenado (store=True) ou sem 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 (loop 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 (armazenado)

# 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 (sem 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 execução assíncrona gerenciada pelo servidor (background=True com store=True) ou recuperação de checkpoints de streaming (eventos interaction.status_update emitidos a partir de 65.536 tokens de saída e a cada 5.000 tokens depois disso), use os seguintes padrões:

Python (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 (pontos de verificação de streaming)

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 (checkpoints de streaming)

# 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"
    }
  }'

Usar decodificações longas com GenerateContent

Em GenerateContent (v1beta1), defina max_output_tokens como maior que 65.536 (até 1.048.576) para solicitações de streaming ou não streaming. O SDK de IA generativa do Google segue automaticamente continuation_token em todos os segmentos quando finish_reason é CONTINUATION (defina automatic_continuation=False em GenerateContentConfig para desativar) ou você pode transmitir continuation_token em um loop 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 (loop de continuação 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"}
    }
  }'

Regras obrigatórias de API e convenções comportamentais

O Hydrogen aplica as convenções nas seções a seguir para níveis de pensamento, limites de tokens, armazenamento em cache, parâmetros de geração e execução de ferramentas de vários turnos.

Níveis de raciocínio

O Hydrogen aceita quatro valores de thinking_level (thinking_budget e MINIMAL retornam um erro de validação HTTP 400). A tabela a seguir lista cada nível de pensamento e as cargas de trabalho recomendadas:

Nível de raciocínio Cargas de trabalho recomendadas
XHIGH Raciocínio profundo, provas matemáticas, análise científica e as tarefas mais complexas de engenharia de software com vários arquivos.
HIGH (padrão em gemini-4-hydrogen) Loops de ferramentas agênticas de várias etapas, geração de código, refatoração arquitetônica e análise multimodal complexa.
MEDIUM Programação geral, uso de ferramentas, perguntas e respostas sobre documentos e compreensão de vídeos com latência equilibrada.
LOW Classificação, roteamento, resumo e extração de metadados estruturados de alta capacidade de processamento.

Limites de tokens, armazenamento em cache e faturamento

O Hydrogen aplica as seguintes regras de token, armazenamento em cache, mídia e faturamento:

  • Limite unificado de tokens de entrada e saída e limites de saída de solicitação única: os orçamentos de tokens e os limites por solicitação funcionam da seguinte maneira:
    • O limite geral de tokens do modelo é de 1,048,576 tokens e inclui tokens de entrada e saída (em que a saída inclui raciocínio, chamadas de função e a resposta final). max_output_tokens controla o limite de tokens de saída para a geração (até 1,048,576 menos os tokens de entrada). Definir max_output_tokens como maior que 1,048,576 retorna um erro HTTP 400.
    • Para evitar conclusões longas não intencionais, o orçamento de saída padrão e o limite de primeiro plano de segmento único (pensamento, chamadas de função e resposta do modelo) são de 65.536 tokens para solicitações de streaming e não streaming.
    • Os tokens de raciocínio gerados em HIGH (padrão) e XHIGH são contabilizados em max_output_tokens e se acumulam no contexto de vários turnos quando você preserva as assinaturas de pensamento entre os turnos. Defina max_output_tokens como um valor alto o suficiente para o pensamento e a saída final, evite limites de compactação de contexto excessivamente baixos em harnesses de programação de vários turnos ou defina thinking_level="MEDIUM" em turnos de ferramentas sensíveis à latência.
  • Decodificações longas: as respostas em primeiro plano de segmento único geram até 65.536 tokens de saída (com ou sem streaming). Para estender a saída de turno único para até 1.048.576 tokens (menos tokens de entrada) na API Interactions ou GenerateContent (v1beta1), consulte Decodificações longas.
  • Armazenamento em cache de contexto: não há suporte para o armazenamento em cache de contexto explícito. O armazenamento em cache implícito (com o armazenamento em cache durável ativado por padrão) é aplicado automaticamente a prefixos de comando compartilhados de 4.096 tokens ou mais. Portanto, coloque o conteúdo estático no início do comando.
  • Entradas do Office e do OpenDocument: transmita arquivos do 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) e Excel ou planilha do OpenDocument (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel, application/vnd.oasis.opendocument.spreadsheet) inline ou por URI do Cloud Storage (gs://) usando inlineData ou fileData em GenerateContent (incluindo dentro de partes de FunctionResponse) e entradas de document (incluindo resultados de ferramentas) na API Interactions.
  • Vídeo agêntico: os vídeos enviados usam media_processing="static" por padrão. Defina media_processing="agentic" para ativar o processamento agêntico de vídeos.
  • Contagem e faturamento de tokens: cada token processado pelo modelo é contado e faturado, incluindo tokens de raciocínio, instruções do sistema de ferramentas internas e declarações de função ao usar o embasamento. O embasamento com a Pesquisa Google também continua sendo cobrado por consulta.

Parâmetros, chamada de função e validação de chat

O Hydrogen aplica as seguintes regras para parâmetros de geração, chamadas de ferramentas, assinaturas de pensamento e histórico de conversas:

  • Parâmetros de amostragem ignorados (temperature, top_k, top_p): o back-end ignora valores personalizados. Controle a profundidade do raciocínio com thinking_level e o formato de saída com response_schema.
  • Parâmetros não compatíveis (frequency_penalty, presence_penalty e candidate_count maiores que 1): transmitir frequency_penalty, presence_penalty ou candidate_count maiores que 1 (candidateCount é fixado em 1) retorna um erro HTTP 400. Remova esses parâmetros das suas solicitações.
  • Chamada de função e assinaturas de pensamento: as declarações de ferramentas, as chamadas de ferramentas paralelas e a repetição de thought_signature em várias interações seguem estas regras:

    • Simetria de curva: cada FunctionResponse precisa corresponder ao id, name e à ordem do FunctionCall anterior.
    • Partes FunctionResponse multimodais: inclua documentos do Office, planilhas, apresentações, PDFs, imagens, áudio e vídeo em partes FunctionResponse multimodais (ou resultados de ferramentas na API Interactions) em vez de adicioná-los como partes separadas de turnos do usuário.
    • Posicionamento da chamada de função paralela thought_signature: quando o modelo emite várias partes paralelas de functionCall em uma única rodada de model, somente a primeira parte de functionCall contém o thought_signature. Omitir thought_signature da primeira parte functionCall na vez do usuário ativo, duplicá-lo em partes paralelas subsequentes de functionCall ou intercalar as vezes de functionCall e functionResponse retorna um erro HTTP 400. Mantenha todas as partes paralelas de functionCall em uma única vez de model, seguida por todas as partes correspondentes de functionResponse em uma única vez de user. Para mais detalhes, consulte Assinaturas de pensamento.
    • Preservação de thought_signature entre turnos: transmita de volta cada thought_signature dentro do Part original em todos os turnos anteriores no histórico de conversas multiturno (partes functionCall e text finais), não apenas no turno do usuário ativo. Embua a validação de assinatura HTTP 400 se aplique apenas às etapas functionCall na vez do usuário ativo, remover valores thought_signature de vezes anteriores ou substituir valores de desvio, como skip_thought_signature_validator, remove o contexto de raciocínio, degrada a qualidade da saída e pode causar motivos de conclusão MALFORMED_FUNCTION_CALL.
    • Formatação pré-ferramenta: separe as instruções inline com \n\n e evite texto não estruturado antes das chamadas de ferramenta. Para registrar o estado intermediário antes de uma chamada de ferramenta, use uma declaração de função 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"]
        }
      }
      
  • Validação da sequência de conversa: os payloads de conversa multiturno aplicam as seguintes restrições:

    • Os payloads de histórico não podem terminar com uma vez de função model.
    • Não há suporte para turnos de modelo preenchidos automaticamente.

Decodificações longas

A decodificação longa divide uma geração de até 1.048.576 tokens (menos os tokens de entrada) em vários segmentos na API Interactions ou GenerateContent (v1beta1). Na API Interactions, cada segmento de primeiro plano (stream=true ou stream=false) gera até 65.536 tokens de saída e retorna status="requires_continuation" com um continuation_token criptografado. Se preferir, defina background=true (store=true) para que o servidor execute o loop de continuação de forma assíncrona e armazene a saída mesclada em um Interaction. No GenerateContent, cada segmento de streaming ou não streaming gera até 65.536 tokens de saída antes de emitir finish_reason=CONTINUATION com continuation_token, continuando até finish_reason=STOP. No Agent Studio, definir o limite de tokens de saída acima de 65.536 até 1.048.576 processa os tokens de continuação automaticamente. Para exemplos de código executáveis, consulte os exemplos do guia de início rápido de decodificação longa.

Quando usar a decodificação longa

A maioria das solicitações é concluída dentro do limite de saída de 65.536 tokens por segmento. Use a decodificação longa somente quando uma resposta precisar de mais saída do que isso. A decodificação longa dá ao modelo mais espaço para raciocinar, mas não torna as respostas mais longas (use thinking_level para controlar a profundidade do raciocínio).

Carga de trabalho Usar decodificação longa? Por quê?
Matemática, ciência, pesquisa e provas formais difíceis Sim O modelo pode gastar mais de 65.536 tokens para explorar e verificar o raciocínio.
As tarefas agênticas e de programação mais difíceis Sim Algumas tarefas precisam de mais de 65.536 tokens de raciocínio e código em uma única resposta. A maioria das tarefas de programação e agênticas é concluída com menos de 65.536 tokens.
Ambientes de avaliação que param no limite de saída Sim A decodificação longa evita respostas cortadas quando o modelo gasta um segmento inteiro de 65.536 tokens no raciocínio.
Chat, perguntas e respostas, resumo, classificação e extração Não Essas tarefas são concluídas com menos de 65.536 tokens.
Solicitações de tamanho fixo, como "Escreva um livro de 700.000 palavras" Não O modelo não segue as metas de comprimento.
Agentes que chamam ferramentas em muitas interações curtas Não Cada turno é curto. As saídas grandes em cada turno preenchem rapidamente o limite unificado de 1.048.576 tokens de entrada e saída.
Comandos próximos ao limite de entrada de 1.048.576 tokens Não A saída pode usar apenas 1.048.576 tokens menos sua entrada.
Solicitações sensíveis à latência Não A decodificação longa pode levar vários minutos.

Escolha uma opção de continuação

Selecione um padrão de continuação com base na superfície da API, na postura de armazenamento e no ambiente de execução. Todas as opções na tabela a seguir atingem o mesmo limite de 1.048.576 tokens (menos tokens de entrada) em gemini-4-hydrogen.

Opção de continuação Superfície da API Quem inicia cada segmento Tokens por segmento Limite de tempo por solicitação Armazenamento do servidor Ideal para
Continuação automática do SDK de IA generativa do Google (recomendado) API Interactions (v1beta1) SDKs de IA generativa do Google: Python (google-genai >= 2.34.0), JavaScript/TypeScript (@google/genai >= 2.32.0), Go (>= 1.77.0) e Java (>= 1.80.0) Até 65.536 (stream=true ou stream=false) 20 minutos por segmento Armazenamento de servidor de sete dias por padrão (store=true) ou nenhum (store=false) A maioria dos aplicativos da API Interactions com ou sem estado
Loop gerenciado pelo servidor em segundo plano (background=true) API Interactions (v1beta1) Loop do servidor da Agent Platform; seu código faz uma sondagem em get Gerenciado do lado do servidor até max_output_tokens Assíncrono (não é necessário abrir um stream de cliente) Armazenamento do servidor por sete dias (store=true necessário) Jobs assíncronos, autores de chamada .NET/Kotlin e persistência de registro único
Loop armazenado em primeiro plano personalizado (store=true) API Interactions (v1beta1) Seu código (previous_interaction_id + continuation_token, sem input) Até 65.536 (stream=true ou stream=false; checkpoints a partir de 65.536 e a cada 5.000 tokens depois disso) 20 minutos por segmento Armazenamento de sete dias no servidor (store=true) Chamadores REST e recuperação de checkpoint personalizada
Loop personalizado sem estado em primeiro plano (store=false) API Interactions (v1beta1) Seu código (input + continuation_token original, sem previous_interaction_id) Até 65.536 (stream=true ou stream=false; checkpoints a partir de 65.536 e a cada 5.000 tokens depois disso) 20 minutos por segmento Sem armazenamento no servidor (fluxos de trabalho de retenção zero de dados) Harnesses REST personalizados que exigem execução sem estado
Continuação automática do SDK de IA generativa do Google (recomendado) GenerateContent (v1beta1) SDKs de IA generativa do Google: Python (>= 2.30.1), JavaScript/TypeScript (>= 2.29.1), Go (>= 1.74.0), Java (>= 1.77.0), .NET (>= 1.26.0) e Kotlin (>= 1.6.0) Até 65.536 (generate_content_stream ou generate_content) 20 minutos por segmento Sem armazenamento no servidor (fluxos de trabalho de retenção zero de dados) Aplicativos GenerateContent atuais
Loop de continuação personalizado GenerateContent (v1beta1) Seu código (contents original + continuation_token) Até 65.536 (streamGenerateContent ou generateContent; checkpoints a partir de 65.536 e a cada 5.000 tokens depois disso) 20 minutos por segmento Sem armazenamento no servidor (fluxos de trabalho de retenção zero de dados) Chamadores REST GenerateContent diretos e harnesses de avaliação

Versão da API e requisitos do SDK

As decodificações longas exigem as seguintes versões de API e do SDK:

  • Requisito da API v1beta1 (problema conhecido): a decodificação longa (continuation_token) na API Interactions e GenerateContent (generateContent e streamGenerateContent) só é compatível com a API v1beta1 (não v1) na Agent Platform. O SDK de IA generativa do Google usa v1beta1 por padrão, a menos que api_version='v1' seja especificado em http_options (ou api_version="v1" em interactions.create). Para chamadas REST diretas, use o caminho do endpoint /v1beta1/.
  • Versões do SDK e compatibilidade com a OpenAI: para continuar automaticamente na API Interactions, faça upgrade para Python google-genai >= 2.34.0, JavaScript/TypeScript @google/genai >= 2.32.0, Go >= 1.77.0 ou Java >= 1.80.0 (para .NET e Kotlin na API Interactions, use background=true ou um loop de continuação personalizado). Para continuar automaticamente no GenerateContent, faça upgrade para Python >= 2.30.1, JavaScript/TypeScript >= 2.29.1, Go >= 1.74.0, Java >= 1.77.0, .NET >= 1.26.0 ou Kotlin >= 1.6.0. As versões anteriores do SDK e a camada de compatibilidade com a OpenAI não podem recuperar conclusões longas usando tokens de continuação.

Regras de continuação da API Interactions

As seguintes transições de status, regras de encadeamento e comportamentos de armazenamento se aplicam a decodificações longas na API Interactions.

Valores de status e orçamento de tokens de saída

Quando generation_config.max_output_tokens é omitido em uma solicitação de API Interactions, o orçamento total de saída é definido como 65.536 tokens (correspondendo ao limite de primeiro plano de segmento único de 65.536 tokens para solicitações com e sem streaming). Defina generation_config.max_output_tokens como maior que 65,536 (até 1,048,576 menos tokens de entrada) para decodificações longas de vários segmentos nos modos de primeiro plano e background=true. O servidor retorna os seguintes valores de status:

  • requires_continuation: o limite de saída de 65.536 tokens por segmento foi atingido antes de max_output_tokens. Transmita o continuation_token retornado na próxima solicitação para continuar a decodificação.
  • incomplete: o orçamento total de max_output_tokens foi esgotado. Continuar com continuation_token sem aumentar max_output_tokens retorna um erro HTTP 400 (max_output_tokens has already been exhausted). Aumente max_output_tokens na próxima solicitação para retomar a decodificação.
  • completed: a geração foi concluída naturalmente e continuation_token foi limpo.

Encadeamento, alternância de modo e armazenamento de segmentos

As solicitações de continuação na API Interactions aplicam as seguintes regras:

  • Continuação armazenada (store=true, padrão): transmita previous_interaction_id definido como o segmento id que emitiu o continuation_token junto com continuation_token e omita input (o segmento armazenado já contém a entrada de turno). Sempre pareie cada continuation_token com o previous_interaction_id do segmento que o emitiu. Transmitir um continuation_token em uma interação que já é completed retorna um erro HTTP 400.
  • Continuação sem estado (store=false): omita previous_interaction_id e reenvie o input original com continuation_token em cada segmento.
  • Alternar os modos store entre os segmentos: é possível alternar do modo armazenado (store=true) para o sem estado (store=false) no meio da decodificação omitindo previous_interaction_id e reenviando o input original com continuation_token. Não é possível alternar de sem estado (store=false) para armazenada (store=true) porque não há uma interação pai armazenada para previous_interaction_id.
  • Alternância e ramificação entre os modos de primeiro plano e background=true: as continuações armazenadas (store=true) podem alternar entre a execução em primeiro plano (background=false) e em segundo plano (background=true) entre os segmentos, incluindo a retomada de uma interação background=true cancelada do checkpoint continuation_token (persistente a partir de 65.536 tokens de saída e a cada 5.000 tokens depois disso) no modo de segundo plano ou em primeiro plano. Reutilizar os mesmos previous_interaction_id e continuation_token cria continuações ramificadas independentes.
  • Aplicação de limite de turno: iniciar um novo turno do usuário (previous_interaction_id com um novo input e sem continuation_token) em um segmento com o status requires_continuation ou incomplete retorna um erro HTTP 400. Termine de continuar a decodificação para completed ou ramifique sua próxima vez na interação mais recente de completed. Quando o segmento final chegar a completed, transmitir o id desse segmento final como previous_interaction_id vai reconstruir o histórico completo da conversa em todos os segmentos anteriores.
  • Consistência de parâmetros entre segmentos: alterar model, system_instruction ou declarações de função (tools) em um segmento de continuação retorna um erro HTTP 400. Mantenha thinking_level e as ferramentas integradas inalteradas em todos os segmentos (consulte Problemas conhecidos).
  • Comportamento de segmento único de get, list e delete: no modo de primeiro plano (background=false), cada segmento é armazenado como um recurso Interaction separado (interactions.get(id) retorna apenas esse segmento, interactions.list() lista cada segmento separadamente e interactions.delete(id) exclui apenas esse segmento; ao excluir uma cadeia de segmentos, exclua em ordem inversa, do último segmento para trás). No SDK de IA generativa do Google com automatic_continuation=True (stream=False), interactions.create() mescla todos os segmentos no retorno e preenche interaction.continuation_ids com os IDs de segmento ordenados (terminando com interaction.id). Se um segmento posterior falhar, exceder um timeout numérico por chamada ou cair no meio do stream depois que o progresso tiver sido feito além de um ponto de verificação retomável, o SDK vai gerar ContinuationInterruptedError com partial_interaction, continuation_token, interaction_id e continuation_ids para que você possa retomar de continuation_token.

Regras de loop personalizado do GenerateContent

Em um loop de continuação GenerateContent personalizado, siga estas regras:

  • Defina max_output_tokens como um valor maior que 65.536 (até 1.048.576) e reenvie os valores originais de contents, system_instruction e tools em cada solicitação de continuação, junto com o continuation_token mais recente (um campo de nível superior em GenerateContentRequest na REST ou em GenerateContentConfig no SDK de IA generativa do Google).
  • Não anexe a saída parcial do modelo a contents nem envie um comando de acompanhamento pedindo que o modelo continue.
  • Continue o loop enquanto finish_reason for CONTINUATION e continuation_token estiver presente, mesmo que um segmento tenha gasto todos os 65.536 tokens no raciocínio (parts: [{"text": ""}]). Se finish_reason for MAX_TOKENS quando continuation_token estiver presente, gere max_output_tokens na próxima solicitação.
  • Combine as partes acumuladas em uma única rodada model para o histórico de várias rodadas somente após STOP.

Contagem de tokens, compactação e armazenamento em cache implícito

A contabilidade e o armazenamento em cache de tokens em segmentos de continuação funcionam da seguinte maneira:

  • Na API Interactions, as chamadas interactions.create() não streaming com automatic_continuation=True e as interações background=true gerenciadas pelo servidor somam as contagens de tokens em todos os segmentos em usage (total_input_tokens, total_cached_tokens, total_output_tokens, total_thought_tokens, total_tokens), preservando a contagem de comandos do primeiro segmento em usage.initial_input_tokens. Em loops personalizados em primeiro plano e eventos interaction.completed transmitidos, o usage de cada segmento informa apenas o delta desse segmento. Portanto, some os campos usage em todos os segmentos para ver o total de tokens faturados.
  • No GenerateContent, o SDK de IA generativa do Google para Python (generate_content e generate_content_stream) acumula o total de tokens faturados em todos os segmentos no usage_metadata final e preserva initial_prompt_token_count. Em loops REST personalizados, some os valores finais de prompt_token_count, cached_content_token_count, candidates_token_count e thoughts_token_count em todos os segmentos.
  • Como cada segmento de continuação em primeiro plano preenche novamente a conversa e os tokens gerados anteriormente como entrada, usage.total_input_tokens (na API Interactions) e prompt_token_count (em GenerateContent) aumentam entre os segmentos. Não use contagens de entrada cumulativas para acionar a compactação de contexto em estruturas de agentes. Em vez disso, verifique usage.initial_input_tokens (ou initial_prompt_token_count em GenerateContent) e compacte somente após o término da rodada (status="completed" ou sem continuation_token).
  • Cada segmento de continuação preenche novamente o comando e os tokens decodificados anteriormente,além de se qualificar automaticamente para o armazenamento em cache de contexto implícito (mínimo de 4.096 tokens, com armazenamento em cache durável ativado por padrão) quando os segmentos são executados em sequência. Os segmentos concluídos são faturados no final de cada segmento, mesmo que um segmento posterior falhe ou seja cancelado.

Migrar para o Hydrogen do 3.8 Flash

O comportamento a seguir é diferente do gemini-3.8-flash e dos modelos anteriores do Gemini 3 Flash:

  • O Hydrogen tem um limite unificado de 1.048.576 tokens para entrada e saída (em que a saída inclui raciocínio, chamadas de função e a resposta final), em vez de limites separados para entrada e saída. A saída em primeiro plano de segmento único é limitada a 65.536 tokens (com ou sem streaming) e pode ser estendida para até 1.048.576 tokens usando decodificações longas na API Interactions ou GenerateContent (processada automaticamente no SDK de IA Generativa do Google, com background=true na API Interactions ou usando continuation_token em loops personalizados).
  • O thinking_level padrão é HIGH (mudou de MEDIUM em gemini-3.8-flash), e XHIGH é compatível com tarefas de raciocínio profundo (deixe espaço para compactação de contexto para rastreamentos de raciocínio HIGH e XHIGH em harnesses de codificação multiturno ou defina MEDIUM em turnos sensíveis à latência). thinking_budget e thinking_level="MINIMAL" retornam um erro HTTP 400.
  • Não há suporte para o armazenamento em cache de contexto explícito (cached_content). O armazenamento em cache implícito é aplicado automaticamente a um mínimo de 4.096 tokens (reduzido de 6.144 tokens em gemini-3.8-flash), com o armazenamento em cache durável ativado por padrão.
  • Os arquivos do Microsoft Office (.docx, .dotx, .doc, .pptx, .ppt, .xlsx, .xls) e do OpenDocument (.odt, .odp, .ods) são aceitos inline ou por URI do Cloud Storage (gs://), inclusive em partes multimodais de FunctionResponse.
  • As chamadas de função paralelas aplicam um posicionamento estrito de thought_signature (somente a primeira parte functionCall em uma chamada paralela carrega thought_signature; omiti-lo na chamada ativa ou duplicá-lo em partes functionCall irmãs subsequentes retorna um erro de HTTP 400), e as edições de prefixo de comando do mesmo modelo falham com erro de HTTP 400 por padrão, a menos que prefix_mismatch_behavior="DROP" esteja definido em ThinkingConfig. Preserve as partes thought_signature em todas as interações anteriores (as partes functionCall e as partes finais text) para manter a qualidade do raciocínio e evitar motivos de encerramento MALFORMED_FUNCTION_CALL.
  • Cada token processado pelo modelo é faturado, incluindo instruções internas do sistema de ferramentas e declarações de função ao usar o embasamento.

Para uma comparação lado a lado, consulte Migrar dos modelos do 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"
+            # prefix_mismatch_behavior="DROP", # Optional: set if compacting or editing prior history
         ),
     ),
 )

Para migrar de modelos do Gemini 3 Flash gemini-3.8-flash ou anteriores, faça o seguinte:

  1. Atualize o ID do modelo para gemini-4-hydrogen.
  2. Faça upgrade para o SDK de IA generativa do Google mais recente e considere o limite unificado de tokens de entrada e saída: faça upgrade para google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0 ou Java >= 1.80.0 para a continuação automática da API Interactions (ou >= 2.30.1 Python / >= 2.29.1 JavaScript em GenerateContent). Os tokens de entrada e saída (incluindo pensamento e chamadas de função) compartilham o limite unificado de 1.048.576 tokens. Para saídas que excedem 65.536 tokens (até 1.048.576 tokens) na API Interactions ou GenerateContent, defina max_output_tokens como um valor maior que 65.536 para que o SDK de IA generativa do Google continue automaticamente entre os segmentos (ou use background=true ou um loop continuation_token personalizado).
  3. Atualizar a configuração de thinking_level: substitua thinking_budget e MINIMAL por thinking_level definido como LOW, MEDIUM, HIGH (padrão em gemini-4-hydrogen) ou XHIGH (use "low", "medium", "high" ou "xhigh" em letras minúsculas na API Interactions). Se sua carga de trabalho dependia de MEDIUM como padrão em gemini-3.8-flash, defina explicitamente thinking_level="MEDIUM" para manter a latência de raciocínio equivalente.
  4. Remova o armazenamento em cache explícito e carregue o conteúdo estático do comando (4.096 tokens ou mais) para o armazenamento em cache implícito automático.
  5. Verifique a preservação de thought_signature multiturno e paralela e a compactação de prefixo: preserve thought_signature em todos os turnos anteriores (partes functionCall e text finais) em vez de remover assinaturas entre turnos, mantenha thought_signature apenas na primeira parte functionCall de um turno de chamada de ferramenta paralela e defina prefix_mismatch_behavior="DROP" em ThinkingConfig se o aplicativo modificar ou compactar turnos anteriores no histórico de conversas multiturno.
  6. Remova os parâmetros que não têm efeito ou não são compatíveis: remova os campos de geração ignorados e rejeitados da seguinte maneira:
    • Remova temperature, top_p e top_k, que são ignorados.
    • Remova frequency_penalty, presence_penalty e qualquer valor de candidate_count maior que 1.
    • Remova todos os turnos de modelo preenchidos automaticamente dos históricos de conversas.

Lista de verificação de resumo para desenvolvedores

Use a lista de verificação a seguir para verificar sua integração com o Hydrogen:

Problemas conhecidos

Os seguintes problemas conhecidos se aplicam às decodificações longas do Hydrogen:

  • As decodificações longas exigem v1beta1: a decodificação longa (continuation_token) na API Interactions e na API GenerateContent (generateContent e streamGenerateContent) só é compatível com a API v1beta1 (não v1) na plataforma de agentes. O SDK de IA Generativa do Google usa v1beta1 por padrão, a menos que api_version='v1' esteja definido em http_options (ou api_version="v1" em interactions.create). Para chamadas REST diretas, use o caminho do endpoint /v1beta1/.
  • Mudanças de parâmetros em segmentos de continuação da API Interactions: mudar model, system_instruction ou declarações de função em segmentos de continuação retorna um erro HTTP 400, enquanto mudanças no meio da decodificação em generation_config.thinking_level ou ferramentas integradas (google_search, code_execution, url_context) não são rejeitadas pela validação do servidor. Mantenha as ferramentas integradas e thinking_level inalteradas em todos os segmentos de um loop de continuação.

Outros recursos

Para mais informações sobre o Hydrogen, consulte os seguintes recursos: