Guida per sviluppatori a Gemini 4 Argon

Gemini 4 Argon è il modello pionieristico di Google che eccelle nel lavoro approfondito su attività complesse del mondo reale in vari ambiti, tra cui programmazione, finanza, legale, sicurezza informatica e scienza. È il primo modello della famiglia Gemini 4.

Questo documento illustra le novità di 4 Argon, le convenzioni API che applica, come eseguire la migrazione e una guida rapida. Per una panoramica della famiglia Gemini 4, vedi Inizia a utilizzare Gemini 4.

Novità in Gemini 4 Argon

  • Limite di token di input e output unificato: 4 Argon ha un limite di 1.048.576 token unificato che include sia i token di input sia quelli di output (dove l'output include il ragionamento, le chiamate di funzione e la risposta finale ).
  • Decodifiche lunghe fino a 1.048.576 token: estende la generazione oltre il limite di output di una singola richiesta (65.536 token o 32.768 token per le richieste HTTP dirette non di streaming) fino a 1.048.576 token (meno i token di input) su GenerateContent. L'SDK Google Gen AI gestisce automaticamente continuation_token tra le richieste oppure puoi gestire continuation_token nel tuo loop di continuazione.
  • Livelli di ragionamento: LOW, MEDIUM (valore predefinito su gemini-4-argon) e HIGH (valore predefinito su gemini-4-argon-cyber-permissive).
  • Memorizzazione nella cache implicita con memorizzazione nella cache durevole: la memorizzazione nella cache implicita viene applicata automaticamente ai prefissi di prompt condivisi di almeno 6144 token, con la memorizzazione nella cache durevole attivata per impostazione predefinita. La memorizzazione nella cache del contesto esplicita non è supportata.
  • Comprensione dei video agentica: Disponibilità generale e disattivata per impostazione predefinita.

Guida rapida

Prima di iniziare, devi eseguire l'autenticazione ad Agent Platform utilizzando le credenziali predefinite dell'applicazione (ADC) o una chiave API. Per ulteriori informazioni, vedi Inizia a utilizzare Gemini Enterprise Agent Platform.

Nei seguenti blocchi di codice, sostituisci PROJECT_ID con il tuo ID progetto.

Prova in Agent Studio

Per testare i prompt e configurare gemini-4-argon nell' interfaccia utente di Agent Studio:

  1. Apri Agent Studio nel tuo Cloud de Confiance by S3NS progetto e seleziona gemini-4-argon nel gruppo Gemini.
  2. In Impostazioni modello, configura:
    • Livello di ragionamento: scegli Low, Medium (valore predefinito) o High.
    • Regione: seleziona Global, us o eu.
    • Limite di token di output: imposta un valore compreso tra 32,768 e 1,048,576 (1,048,576 predefinito). Agent Studio gestisce automaticamente i token di continuazione per le risposte che superano il limite di una singola richiesta.

Installazione

Esegui l'upgrade all'ultima versione dell'SDK Google Gen AI (google-genai >= 2.30.1 per Python, @google/genai >= 2.29.1 per JavaScript, >= 1.74.0 per Go, >= 1.77.0 per Java, >= 1.26.0 per .NET o >= 1.6.0 per Kotlin):

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

Richiesta di base

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

Output strutturato

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)

Decodifiche lunghe

Per impostazione predefinita, una singola richiesta API genera fino a 65.536 token di output (o 32.768 token per le richieste HTTP dirette non di streaming), dove l'output include il ragionamento, le chiamate di funzione e la risposta finale. Per generare completamenti fino a 1.048.576 token su GenerateContent (v1beta1), imposta max_output_tokens su un valore maggiore di 65.536 per le richieste di streaming o maggiore di 32.768 per le richieste non di streaming (fino a 1.048.576). L'SDK Google Gen AI segue automaticamente continuation_token tra le richieste quando finish_reason è CONTINUATION (imposta automatic_continuation=False in GenerateContentConfig per disattivare la continuazione automatica) oppure puoi passare continuation_token in un loop personalizzato.

Python (SDK - consigliato)

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 (loop di continuazione personalizzato)

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

Regole API obbligatorie e convenzioni comportamentali

Gemini 4 Argon applica le seguenti convenzioni:

  • Livelli di ragionamento: 4 Argon supporta tre thinking_level valori (thinking_budget e MINIMAL restituiscono un errore di convalida HTTP 400):

    Livello di ragionamento Workload consigliati
    HIGH (valore predefinito su gemini-4-argon-cyber-permissive) Ingegneria del software multi-file, prove formali, progettazione dell'architettura e rilevamento delle vulnerabilità.
    MEDIUM (valore predefinito su gemini-4-argon) Programmazione generale, utilizzo di strumenti, domande e risposte sui documenti e comprensione dei video.
    LOW Classificazione, riepilogo ed estrazione dei metadati.

  • Limite di token di input e output unificato e limiti di output di una singola richiesta:

    • 1,048,576 è il limite di token complessivo del modello e include sia i token di input sia quelli di output (dove l'output include il ragionamento, le chiamate di funzione e la risposta finale). max_output_tokens controlla il limite di token di output per la generazione (fino a 1,048,576 meno i token di input); l'impostazione di max_output_tokens su un valore maggiore di 1,048,576 restituisce un errore HTTP 400.
    • Per evitare completamenti lunghi non intenzionali, il limite di output predefinito di una singola richiesta (ragionamento + risposta del modello) è di 65.536 token (o 32.768 token per le richieste HTTP dirette non di streaming).

  • Decodifiche lunghe:

    • Come funziona la decodifica lunga: la decodifica lunga suddivide una generazione fino a 1.048.576 token in più inferenze GenerateContent. Ad esempio, se un'attività richiede 256.000 token di output (inclusi pensieri, chiamate di funzione e risposta finale), la prima richiesta di streaming genera fino a 65.536 token di output ed emette finish_reason=CONTINUATION con un continuation_token criptato contenente un hash del prompt originale e lo stato di generazione fino a quel punto. L'inclusione di continuation_token nelle richieste successive con il prompt originale continua la generazione dal punto in cui è stata interrotta fino a quando continuation_token non viene più emesso e finish_reason=STOP. (In Agent Studio, l'impostazione del limite di token di output su un valore maggiore di 65.536 fino a 1.048.576 gestisce automaticamente i token di continuazione.)
    • Quando utilizzare la decodifica lunga: la maggior parte delle richieste viene completata entro il limite per richiesta (65.536 token o 32.768 token per le chiamate REST non di streaming). Utilizza la decodifica lunga solo quando una risposta richiede più output. La decodifica lunga offre al modello più spazio per ragionare; non allunga le risposte (utilizza thinking_level per controllare la profondità del ragionamento).
    Workload Utilizzare la decodifica lunga? Perché
    Matematica, scienza, ricerca e prove formali difficili Sì Il modello può utilizzare più di 65.536 token per esplorare e controllare il suo ragionamento.
    Le attività di programmazione e agentiche più difficili Sì Alcune attività richiedono più di 65.536 token di ragionamento e codice in una risposta. La maggior parte delle attività di programmazione e agentiche viene completata con meno di 65.536 token.
    Strumenti di valutazione che si arrestano al limite di output Sì La decodifica lunga impedisce che le risposte vengano troncate quando il modello utilizza un'intera richiesta di 65.536 o 32.768 token per il ragionamento.
    Chat, domande e risposte, riepilogo, classificazione ed estrazione No Queste attività vengono completate con meno di 32.768 token.
    Richieste di una lunghezza fissa, ad esempio "scrivi un libro di 700.000 parole" No Il modello non segue gli obiettivi di lunghezza.
    Agenti che chiamano strumenti in molti turni brevi No Ogni turno è breve. Gli output di grandi dimensioni in ogni turno riempiono rapidamente il limite di input e output unificato di 1.048.576 token.
    Prompt vicini al limite di input di 1.048.576 token No L'output può utilizzare solo 1.048.576 token meno l'input.
    Richieste sensibili alla latenza No La decodifica lunga può essere eseguita per diversi minuti.
    • Scelta di un'opzione di continuazione: scegli una delle due opzioni. La maggior parte degli sviluppatori utilizza l'opzione 1. Tutte le opzioni raggiungono lo stesso limite di 1.048.576 token su gemini-4-argon e gemini-4-argon-cyber-permissive.
    Dimensioni Opzione 1: SDK Google Gen AI (consigliata) Opzione 2: il tuo loop di streaming (streamGenerateContent) Opzione 2: il tuo loop non di streaming (generateContent)
    Chi inizia ogni segmento SDK Google Gen AI: Python (google-genai) 2.30.1, JavaScript (@google/genai) 2.29.1, Go 1.74.0, Java 1.77.0, .NET 1.26.0 e Kotlin 1.6.0. Imposta max_output_tokens. Il tuo codice, a ogni checkpoint o dopo un flusso interrotto Il tuo codice, ogni 32.768 token
    Token per richiesta Fino a 65.536 per segmento 65.536 per flusso, con un checkpoint ogni 5000 token dopo 32.768 32.768 per richiesta
    Limite di tempo per richiesta 20 minuti 20 minuti 20 minuti
    Archiviazione Nessuna archiviazione server (conforme a ZDR) Nessuna archiviazione server (conforme a ZDR) Nessuna archiviazione server (conforme a ZDR)
    Ideale per La maggior parte delle applicazioni Chiamanti REST e strumenti personalizzati che eseguono lo streaming Strumenti di valutazione semplici
    • Regole e limitazioni di implementazione:
      • v1beta1 requisito API (problema noto): la decodifica lunga (continuation_token) su GenerateContent (generateContent e streamGenerateContent) è supportata solo nell'API v1beta1 (non v1). L'SDK Google Gen AI utilizza v1beta1 per impostazione predefinita, a meno che non venga specificato api_version='v1' in http_options; per le chiamate REST dirette, utilizza il percorso dell'endpoint v1beta1. La decodifica lunga non è supportata nell'API Interactions.
      • Versioni dell'SDK e compatibilità con OpenAI: esegui l'upgrade all'ultima versione dell' SDK Google Gen AI (google-genai >= 2.30.1 per Python, @google/genai >= 2.29.1 per JavaScript, >= 1.74.0 per Go, >= 1.77.0 per Java, >= 1.26.0 per .NET o >= 1.6.0 per Kotlin). Le versioni precedenti dell'SDK e il livello di compatibilità con OpenAI non possono recuperare i completamenti lunghi utilizzando i token di continuazione. Per le implementazioni client personalizzate, consulta le implementazioni di riferimento dell'SDK Google Gen AI in Python e JavaScript/TypeScript.
      • Invia di nuovo la richiesta originale con continuation_token: in un loop personalizzato, imposta max_output_tokens su un valore maggiore di 65.536 (streaming) o 32.768 (unario) fino a 1.048.576 e invia di nuovo contents, system_instruction e tools originali in ogni richiesta di continuazione insieme all'ultimo continuation_token (un campo di primo livello in GenerateContentRequest in REST o in GenerateContentConfig nell'SDK Google Gen AI). Non aggiungere l'output parziale del modello a contents né inviare un prompt di follow-up chiedendo al modello di continuare.
      • Continua con le richieste di solo ragionamento: esegui il loop mentre finish_reason è CONTINUATION e continuation_token è presente, anche se una richiesta ha utilizzato tutti i 32.768 o 65.536 token per il ragionamento (parts: [{"text": ""}]). Se finish_reason è MAX_TOKENS quando continuation_token è presente, la generazione ha raggiunto il limite max_output_tokens richiesto. Aumenta max_output_tokens nella richiesta. Combina le parti accumulate in un singolo turno model per la cronologia a più turni solo dopo STOP.
      • Conteggio dei token, compattazione e sconto del 95% sulla cache implicita:
        • Nell'SDK Google Gen AI per Python (generate_content e generate_content_stream), usage_metadata della risposta o del blocco finale accumula i token fatturati totali nelle richieste di continuazione. Poiché ogni richiesta di continuazione riempie nuovamente i completamenti parziali precedenti come token di input, prompt_token_count aumenta cumulativamente nelle richieste di continuazione. Non utilizzare prompt_token_count per attivare la compattazione del contesto nelle infrastrutture agentiche. Leggi invece initial_prompt_token_count (in GenerateContentResponse o usage_metadata) e attendi il completamento di GenerateContent (nessun continuation_token presente) prima di eseguire la compattazione.
        • Nei loop REST personalizzati, usage_metadata è cumulativo all'interno di ogni richiesta; somma i valori finali di prompt_token_count, cached_content_token_count, candidates_token_count e thoughts_token_count nelle richieste.
        • Ogni richiesta di continuazione riempie nuovamente il prompt più i token decodificati precedenti e riceve automaticamente lo sconto del 95% sulla memorizzazione nella cache del contesto implicita (minimo 6144 token) quando le richieste vengono eseguite in sequenza entro il TTL della cache di 15-20 minuti.
        • streamGenerateContent e generateContent restituiscono usage_metadata alla fine di ogni richiesta (65.536 streaming/32.768 unari) e la fatturazione avviene alla fine della richiesta.

  • Parametri di campionamento ignorati (temperature, top_k, top_p): il backend ignora i valori personalizzati. Controlla la profondità del ragionamento con thinking_level e il formato di output con response_schema.

  • Parametri non supportati (frequency_penalty, presence_penalty, candidate_count): questi restituiscono un errore HTTP 400. Rimuovili dalle richieste.

  • Memorizzazione nella cache del contesto: la memorizzazione nella cache del contesto esplicita non è supportata. La memorizzazione nella cache implicita (con la memorizzazione nella cache durevole attivata per impostazione predefinita) viene applicata automaticamente ai prefissi di prompt condivisi di almeno 6144 token, quindi inserisci i contenuti statici all'inizio del prompt.

  • Video agentici: per impostazione predefinita, i video caricati sono impostati su media_processing="static". Imposta media_processing="agentic" per attivare l'elaborazione dei video agentica.

  • Conteggio dei token e fatturazione: ogni token elaborato dal modello viene conteggiato e fatturato, inclusi i token di ragionamento e le istruzioni di sistema degli strumenti interni e le dichiarazioni di funzione quando si utilizza il grounding. Anche il grounding con la Ricerca Google rimane fatturato per query.

  • Chiamata di funzione:

    • Simmetria dei turni: ogni FunctionResponse deve corrispondere a id, name, e all'ordine della FunctionCall precedente.
    • Esecuzione sequenziale: preferisci i turni di esecuzione sequenziale degli strumenti nei loop di strumenti a più passaggi.

    • Formattazione pre-strumento: separa le istruzioni in linea con \n\n e evita il testo non strutturato prima delle chiamate agli strumenti. Per registrare lo stato intermedio prima di una chiamata allo strumento, utilizza una dichiarazione di funzione dedicata:

      {
  "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"]
  }
}

  • Convalida della sequenza di chat:

    • I payload della cronologia non possono terminare con un turno di ruolo model.
    • I turni precompilati del modello non sono supportati.

Eseguire la migrazione a 4 Argon da 3.1 Pro

Il seguente comportamento è diverso da gemini-3.1-pro-preview:

  • 4 Argon ha un limite di 1.048.576 token unificato per input e output (dove l'output include il ragionamento, le chiamate di funzione e la risposta finale), anziché limiti di input e output separati. L'output di una singola richiesta è limitato a 65.536 token (o 32.768 token per le richieste HTTP dirette non di streaming) e può essere esteso fino a 1.048.576 token utilizzando le decodifiche lunghe su GenerateContent (gestite automaticamente nell' SDK Google Gen AI o utilizzando continuation_token nei loop personalizzati).
  • thinking_budget restituisce un errore HTTP 400 anziché essere mappato a un livello di ragionamento. Anche MINIMAL restituisce un errore.
  • La memorizzazione nella cache del contesto esplicita non è supportata.
  • Ogni token elaborato dal modello viene fatturato, incluse le istruzioni di sistema e le dichiarazioni di funzione degli strumenti interni quando si utilizza il grounding.

Per un confronto fianco a fianco, vedi Eseguire la migrazione da 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"
         ),
     ),
 )

Per eseguire la migrazione da gemini-3.1-pro-preview:

  1. Aggiorna l'ID modello a gemini-4-argon (o gemini-4-argon-cyber-permissive per i workload di cybersicurezza approvati da Fairwind).
  2. Esegui l'upgrade all'ultima versione dell'SDK Google Gen AI e tieni conto del limite di token di input e output unificato: esegui l'upgrade a google-genai >= 2.30.1 (Python), @google/genai >= 2.29.1 (JavaScript) o all'ultima versione equivalente dell'SDK Google Gen AI. I token di input e output (inclusi il ragionamento e le chiamate di funzione) condividono il limite unificato di 1.048.576 token. Per gli output che superano i 65.536 token (fino a 1.048.576 token) su GenerateContent, imposta max_output_tokens su un valore maggiore di 65.536 in modo che l'SDK Google Gen AI continui automaticamente tra le richieste (o gestisci continuation_token nel tuo loop REST).
  3. Sostituisci il parametro del budget di ragionamento: sostituisci thinking_budget e MINIMAL con thinking_level impostato su LOW, MEDIUM (valore predefinito su gemini-4-argon) o HIGH (valore predefinito su gemini-4-argon-cyber-permissive).
  4. Rimuovi la memorizzazione nella cache esplicita e carica in anticipo i contenuti statici del prompt (6144 token o più) per la memorizzazione nella cache implicita automatica.
  5. Rimuovi i parametri che non hanno effetto o non sono supportati:
    • Rimuovi temperature, top_p e top_k, che vengono ignorati.
    • Rimuovi candidate_count, frequency_penalty e presence_penalty.
    • Rimuovi eventuali turni del modello precompilati dalle cronologie delle conversazioni.

Elenco di controllo riepilogativo per gli sviluppatori

Problemi noti

  • Le decodifiche lunghe su GenerateContent richiedono v1beta1: la decodifica lunga (continuation_token) sull'API GenerateContent (generateContent e streamGenerateContent) è supportata solo nell'API v1beta1 (non v1). L'SDK Google Gen AI utilizza v1beta1 per impostazione predefinita, a meno che non venga impostato api_version='v1' in http_options; per le chiamate REST dirette, utilizza il percorso dell'endpoint v1beta1.

Risorse aggiuntive