Guía para desarrolladores sobre Gemini 4 Argon

Gemini 4 Argon es el modelo de frontera de Google que se destaca en el trabajo profundo en tareas complejas y del mundo real en varios dominios, como programación, finanzas, asuntos legales, ciberseguridad y ciencia. Es el primer modelo de la familia Gemini 4.

En este documento, se abordan las novedades de 4 Argon, las convenciones de API que aplica, cómo migrar a él y una guía de inicio rápido. Para obtener una descripción general de la familia Gemini 4, consulta Comienza a usar Gemini 4.

¿Cuáles son las novedades de Gemini 4 Argon?

  • Límite unificado de tokens de entrada y salida: 4 Argon tiene un límite unificado de 1,048,576 tokens que incluye tokens de entrada y salida (en los que la salida incluye el pensamiento, las llamadas a funciones y la respuesta final).
  • Decodificaciones largas de hasta 1,048,576 tokens: Extiende la generación más allá del límite de salida de una sola solicitud (65,536 tokens o 32,768 tokens para solicitudes HTTP directas que no son de transmisión) hasta 1,048,576 tokens (menos los tokens de entrada) en GenerateContent. El SDK de IA generativa de Google controla continuation_token automáticamente en las solicitudes, o bien puedes administrar continuation_token en tu propio bucle de continuación.
  • Niveles de pensamiento: LOW, MEDIUM (predeterminado en gemini-4-argon) y HIGH (predeterminado en gemini-4-argon-cyber-permissive).
  • 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 6,144 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.
  • Comprensión de video de agentes: Está disponible de forma general y desactivada de forma predeterminada.

Guía de inicio rápido

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

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

Probar en Agent Studio

Para probar los mensajes y configurar gemini-4-argon en la IU de Agent Studio, haz lo siguiente:

  1. Abre Agent Studio en tu Cloud de Confiance by S3NS proyecto y selecciona gemini-4-argon en el grupo Gemini.
  2. En Ajustes del modelo, configura lo siguiente:
    • Nivel de pensamiento: Elige Low, Medium (predeterminado) o High.
    • Región: Selecciona Global, us, o eu.
    • Límite de tokens de salida: Establece entre 32,768 y 1,048,576 (1,048,576 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 (google-genai >= 2.30.1 para Python, @google/genai >= 2.29.1 para JavaScript, >= 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.30.1"

Solicitud básica

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-argon",
    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="MEDIUM",  # Default: "MEDIUM" (Valid: "LOW", "MEDIUM", "HIGH")
        ),
    ),
)
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-argon",
    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-argon",
    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-argon:generateContent" \
-d '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Provide an architectural review of this Go interface."
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
      "thinkingLevel": "MEDIUM"
    }
  }
}'

Resultados estructurados

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-argon",
    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)

Decodificaciones largas

De forma predeterminada, una sola solicitud a la API genera hasta 65,536 tokens de salida (o 32,768 tokens para solicitudes HTTP directas que no son de transmisión), en los que la salida incluye el pensamiento, las llamadas a funciones y la respuesta final. Para generar finalizaciones de hasta 1,048,576 tokens en GenerateContent (v1beta1), establece max_output_tokens en un valor superior a 65,536 para las solicitudes de transmisión o superior a 32,768 para las solicitudes que no son de transmisión (hasta 1,048,576). El SDK de IA generativa de Google sigue automáticamente continuation_token en las solicitudes cuando finish_reason es CONTINUATION (establece automatic_continuation=False en GenerateContentConfig para inhabilitar la continuación automática), o bien puedes pasar continuation_token en un bucle personalizado.

Python (SDK, recomendado)

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-argon",
    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-argon",
    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 > 32,768
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-argon: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-argon:generateContent" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Write a complete formal proof of the prime number theorem."}]
    }],
    "continuationToken": "CONTINUATION_TOKEN_FROM_REQUEST_1",
    "generationConfig": {
      "maxOutputTokens": 131072,
      "thinkingConfig": {"thinkingLevel": "HIGH"}
    }
  }'

Reglas obligatorias de la API y convenciones de comportamiento

Gemini 4 Argon aplica las siguientes convenciones:

  • Niveles de pensamiento: 4 Argon admite tres thinking_level valores (thinking_budget y MINIMAL muestran un error de validación 400 de HTTP):

    Nivel de pensamiento Cargas de trabajo recomendadas
    HIGH (predeterminado en gemini-4-argon-cyber-permissive) Ingeniería de software de varios archivos, pruebas formales, diseño de arquitectura y descubrimiento de vulnerabilidades
    MEDIUM (predeterminado en gemini-4-argon) Codificación general, uso de herramientas, preguntas y respuestas de documentos y comprensión de video
    LOW Clasificación, resumen y extracción de metadatos

  • Límite unificado de tokens de entrada y salida, y límites de salida de una sola solicitud:

    • 1,048,576 es el límite general de tokens del modelo e incluye tokens de entrada y salida (en los que la salida incluye el pensamiento, 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 los tokens de entrada); si se establece max_output_tokens en un valor superior a 1,048,576, se muestra un error 400 de HTTP.
    • Para evitar finalizaciones largas no deseadas, el límite de salida predeterminado de una sola solicitud (pensamiento + respuesta del modelo) es de 65,536 tokens (o 32,768 tokens para solicitudes HTTP directas que no son de transmisión).

  • Decodificaciones largas:

    • Cómo funciona la decodificación larga: La decodificación larga divide una generación de hasta 1,048,576 tokens en varias inferencias GenerateContent. Por ejemplo, si una tarea requiere 256,000 tokens de salida (incluidos los pensamientos, las llamadas a funciones y la respuesta final), la primera solicitud de transmisión genera hasta 65,536 tokens de salida y emite finish_reason=CONTINUATION con un continuation_token encriptado que contiene un hash del mensaje original y el estado de generación hasta ese punto. Si se incluye continuation_token en las solicitudes posteriores con el mensaje original, se continúa la generación desde donde se dejó hasta que continuation_token ya no se emite y finish_reason=STOP. (En Agent Studio, si se establece el límite de tokens de salida en un valor superior a 65,536 hasta 1,048,576, se controlan los tokens de continuación automáticamente).
    • Cuándo usar la decodificación larga: La mayoría de las solicitudes finalizan dentro del límite por solicitud (65,536 tokens o 32,768 tokens para llamadas REST que no son de transmisión). Usa la decodificación larga solo cuando una respuesta necesite más salida 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 ¿Usar decodificación larga? Por qué
    Matemáticas, ciencias, investigación y pruebas formales difíciles Sí El modelo puede usar más de 65,536 tokens para explorar y verificar su razonamiento.
    Las tareas de codificación y de agentes más difíciles Sí Algunas tareas necesitan más de 65,536 tokens de pensamiento y código en una respuesta. La mayoría de las tareas de codificación y de agentes finalizan con menos de 65,536 tokens.
    Aprovechamientos de evaluación que se detienen en el límite de salida Sí La decodificación larga evita las respuestas cortadas cuando el modelo usa una solicitud completa de 65,536 o 32,768 tokens para pensar.
    Chat, preguntas y respuestas, resumen, clasificación y extracción No Estas tareas finalizan con menos de 32,768 tokens.
    Solicitudes de una longitud fija, como "escribir 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 corto. Las salidas grandes en cada turno llenan rápidamente el límite unificado de entrada y salida de 1,048,576 tokens.
    Mensajes cerca del 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.
    • Cómo elegir una opción de continuación: Elige una de las dos opciones. La mayoría de los desarrolladores usan la opción 1. Todas las opciones alcanzan el mismo límite de 1,048,576 tokens en gemini-4-argon y gemini-4-argon-cyber-permissive.
    Dimensión Opción 1: SDK de IA generativa de Google (recomendado) Opción 2: Tu propio bucle de transmisión (streamGenerateContent) Opción 2: Tu propio bucle que no es de transmisión (generateContent)
    Quién inicia cada segmento SDKs de IA generativa de Google: Python (google-genai) 2.30.1, JavaScript (@google/genai) 2.29.1, Go 1.74.0, Java 1.77.0, .NET 1.26.0 y Kotlin 1.6.0 Estableces max_output_tokens. Tu código, en cada punto de control o después de una transmisión interrumpida Tu código, cada 32,768 tokens
    Tokens por solicitud Hasta 65,536 por segmento 65,536 por transmisión, con un punto de control cada 5,000 tokens después de 32,768 32,768 por solicitud
    Límite de tiempo por solicitud 20 minutos 20 minutos 20 minutos
    Almacenamiento Sin almacenamiento del servidor (compatible con ZDR) Sin almacenamiento del servidor (compatible con ZDR) Sin almacenamiento del servidor (compatible con ZDR)
    Ideal para La mayoría de las aplicaciones Llamadores de REST y aprovechamientos personalizados que transmiten Aprovechamientos de evaluación simples
    • Reglas y limitaciones de implementación:
      • v1beta1 requisito de la API (problema conocido): La decodificación larga (continuation_token) en GenerateContent (generateContent y streamGenerateContent) solo se admite en la API de v1beta1 (no en v1). El SDK de IA generativa de Google usa v1beta1 de forma predeterminada, a menos que se especifique api_version='v1' en http_options; para las llamadas directas de REST usa la ruta de acceso del extremo v1beta1. La decodificación larga no se admite en la API de Interactions.
      • Versiones del SDK y compatibilidad con OpenAI: Actualiza al SDK de IA generativa de Google más reciente (google-genai >= 2.30.1 para Python, @google/genai >= 2.29.1 para JavaScript, >= 1.74.0 para Go, >= 1.77.0 para Java, >= 1.26.0 para .NET o >= 1.6.0 para Kotlin). Las versiones anteriores del SDK y la capa de compatibilidad con OpenAI no pueden recuperar finalizaciones largas con tokens de continuación. Para las implementaciones de clientes personalizados, consulta las implementaciones de referencia del SDK de IA generativa de Google en Python y JavaScript/TypeScript.
      • Reenvía la solicitud original con continuation_token: En un bucle personalizado, establece max_output_tokens en un valor superior a 65,536 (transmisión) o 32,768 (unario) hasta 1,048,576 y reenvía el contents, system_instruction y tools originales en cada solicitud de continuación junto con el continuation_token más reciente (un campo de nivel superior en GenerateContentRequest en REST o en GenerateContentConfig en el SDK de IA generativa de Google). No agregues la salida parcial del modelo a contents ni envíes un mensaje de seguimiento en el que se le pida al modelo que continúe.
      • Continúa con las solicitudes de solo pensamiento: Haz un bucle mientras finish_reason sea CONTINUATION y continuation_token esté presente, incluso si una solicitud usó los 32,768 o 65,536 tokens para pensar (parts: [{"text": ""}]). Si finish_reason es MAX_TOKENS cuando continuation_token está presente, la generación alcanzó el límite de max_output_tokens solicitado. Aumenta max_output_tokens en la solicitud. Combina las partes acumuladas en un solo turno model para el historial de varios turnos solo después de STOP.
      • Conteo de tokens, compactación y descuento implícito del 95% en el caché:
        • En el SDK de IA generativa de Google para Python (generate_content y generate_content_stream), el usage_metadata de la respuesta final o del fragmento acumula los tokens facturados totales en las solicitudes de continuación. Dado que cada solicitud de continuación vuelve a completar las finalizaciones parciales anteriores como tokens de entrada, prompt_token_count aumenta de forma acumulativa en las solicitudes de continuación. No uses prompt_token_count para activar la compactación de contexto en los aprovechamientos de agentes. En su lugar, lee initial_prompt_token_count (en GenerateContentResponse o usage_metadata) y espera hasta que se complete GenerateContent(no hay continuation_token presente) antes de la compactación.
        • En los bucles REST personalizados, usage_metadata es acumulativo dentro de cada solicitud; suma el prompt_token_count, cached_content_token_count, candidates_token_count y thoughts_token_count finales en las solicitudes.
        • Cada solicitud de continuación vuelve a completar el mensaje más los tokens decodificados anteriores y recibe automáticamente el descuento implícito del 95% en el almacenamiento en caché de contexto (mínimo de 6,144 tokens) cuando las solicitudes se ejecutan de forma consecutiva dentro del TTL de caché de 15 a 20 minutos.
        • streamGenerateContent y generateContent muestran usage_metadata al final de cada solicitud (65,536 transmisión/32,768 unario), y la facturación se realiza al final de la solicitud.

  • 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 compatibles (frequency_penalty, presence_penalty, candidate_count): Estos muestran un error 400 de HTTP. Quítalos de tus solicitudes.

  • 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 6,144 tokens o más, por lo que debes colocar contenido estático al comienzo de tu mensaje.

  • Video de agentes: Los videos subidos se establecen de forma predeterminada en media_processing="static". Establece media_processing="agentic" para habilitar el procesamiento de video de agentes.

  • Conteo y facturación de tokens: Se cuenta y se factura cada token que procesa el modelo, incluidos los tokens de razonamiento y 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.

  • Llamada a función:

    • Simetría de turnos: Cada FunctionResponse debe coincidir con el id, name, y el orden del FunctionCall anterior.
    • Ejecución secuencial: Prefiere los turnos de ejecución secuencial de herramientas en los bucles de herramientas de varios pasos.

    • Formato previo a la herramienta: Separa las instrucciones intercaladas con \n\n y evita el texto no estructurado antes de las llamadas a herramientas. Para registrar el estado intermedio antes de una llamada a 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 secuencia de chat:

    • Las cargas útiles del historial no pueden terminar con un turno de rol model.
    • No se admiten los turnos de modelos precompletados.

Migra a 4 Argon desde 3.1 Pro

El siguiente comportamiento es diferente de gemini-3.1-pro-preview:

  • 4 Argon tiene un límite unificado de 1,048,576 tokens en la entrada y la salida (en los que la salida incluye el pensamiento, las llamadas a funciones y la respuesta final), en lugar de límites de entrada y salida separados. La salida de una sola solicitud está limitada a 65,536 tokens (o 32,768 tokens para solicitudes HTTP directas que no son de transmisión) y se puede extender hasta 1,048,576 tokens con decodificaciones largas en GenerateContent (que se controlan automáticamente en el SDK de IA generativa de Google o con continuation_token en bucles personalizados).
  • thinking_budget muestra un error 400 de HTTP en lugar de asignarse a un nivel de pensamiento. MINIMAL también muestra un error.
  • No se admite el almacenamiento en caché de contexto explícito.
  • 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 Gemini 3.1 Pro.

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

 response = client.models.generate_content(
-    model="gemini-3.1-pro-preview",
+    model="gemini-4-argon",
     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 Argon
+            thinking_level="MEDIUM", # Valid: "LOW", "MEDIUM" (default), "HIGH"
         ),
     ),
 )

Para migrar desde gemini-3.1-pro-preview, haz lo siguiente:

  1. Actualiza el ID del modelo a gemini-4-argon (o gemini-4-argon-cyber-permissive para las cargas de trabajo de ciberseguridad aprobadas por Fairwind).
  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.30.1 (Python), @google/genai >= 2.29.1 (JavaScript) o el SDK de IA generativa de Google más reciente equivalente. Los tokens de entrada y salida (incluidos los pensamientos y las llamadas a funciones) comparten el límite unificado de 1,048,576 tokens. Para las salidas que superan los 65,536 tokens (hasta 1,048,576 tokens) en 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 las solicitudes (o controla continuation_token en tu propio bucle REST).
  3. Reemplaza el parámetro de presupuesto de razonamiento: Reemplaza thinking_budget y MINIMAL por thinking_level establecido en LOW, MEDIUM (predeterminado en gemini-4-argon) o HIGH (predeterminado en gemini-4-argon-cyber-permissive).
  4. Quita el almacenamiento en caché explícito y carga previamente el contenido estático del mensaje (6,144 tokens o más) para el almacenamiento en caché implícito automático.
  5. Quita los parámetros que no tienen efecto o no son compatibles:
    • Quita temperature, top_p y top_k, que se ignoran.
    • Quita candidate_count, frequency_penalty y presence_penalty.
    • Quita los turnos de modelos precompletados de los historiales de conversaciones.

Lista de tareas de resumen para desarrolladores

Problemas conocidos

  • Las decodificaciones largas en GenerateContent requieren v1beta1: La decodificación larga (continuation_token) en la API de GenerateContent (generateContent y streamGenerateContent) solo se admite en la API de v1beta1 (no en v1). El SDK de IA generativa de Google usa v1beta1 de forma predeterminada, a menos que se establezca api_version='v1' en http_options; para las llamadas directas de REST, usa la ruta de acceso del extremo v1beta1.

Recursos adicionales