AG
Gemini & Antigravity v2.6 Agentic Engineering Guide
Gemini 4 Models Nov 2026 Release Verified: 2026-11

Gemini 4 Neon Deep-Dive: Architecture Analysis, Caching Break-Even Math, and Full-Stack Integration Guide

Forward-looking engineering analysis of Google DeepMind's Gemini 4 Neon (November 2026): near-Carbon quality positioning at Flash-tier speed and cost, 1M unified context, configurable Thinking Levels. Sourced from the official architecture whitepaper, Engineering Preview docs, and OpenRouter gateway data — no self-run benchmarks. Includes the complete Context Caching break-even derivation, Cursor / Cline / Roo Code / OpenRouter / AI Studio / official SDK integration configs, and a reproducible evaluation methodology for your own repo. All prices are developer Preview Pricing; final GA pricing will be published by Google Cloud / AI Studio.

Author: AGY Engineering Team • Google GenAI & Antigravity 2.6 Engineering Spec

Gemini 4 Neon Production Router (Node.js)

examples/neon_production_router.mjs

/**
 * Gemini 4 Neon Production Router
 * Target runtime: Node 22+ with @google/genai SDK (v1.0+)
 * Features: Thinking Level switching, implicit-cache-aware prompts,
 * exponential backoff retry, and strict structured-output validation.
 */
import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

// Thinking Level ladder (billed at output rate — see guide §4.5)
const THINKING_PRESETS = {
  low:    { thinkingLevel: 'low',    thinkingBudget: 1024 },
  medium: { thinkingLevel: 'medium', thinkingBudget: 4096 },
  high:   { thinkingLevel: 'high',   thinkingBudget: 8192 },
};

async function callNeon(prompt, { level = 'medium', schema = null, retries = 4 } = {}) {
  let delayMs = 500;
  for (let attempt = 1; attempt <= retries; attempt++) {
    try {
      const response = await ai.models.generateContent({
        model: 'gemini-4-neon',
        contents: prompt,
        config: {
          thinkingConfig: THINKING_PRESETS[level],
          ...(schema ? { responseMimeType: 'application/json' } : {}),
        },
      });
      if (schema) return JSON.parse(response.text); // strict parse = fail fast, retry
      return response.text;
    } catch (err) {
      if (attempt === retries) throw err;
      const jitter = Math.random() * 250;
      await new Promise(r => setTimeout(r, delayMs + jitter));
      delayMs *= 2; // exponential backoff: 500ms -> 1s -> 2s -> 4s
    }
  }
}

// Agentic loop pattern: keep the repository preamble FIRST and IDENTICAL
// across turns so the implicit context cache (activates at >= 32K tokens,
// 75% input discount) keeps hitting on every subsequent request.
const REPO_PREAMBLE = buildStableRepoPreamble(); // ~120K tokens, byte-stable

const review = await callNeon(
  REPO_PREAMBLE + '\n\n## Task\nAudit the auth middleware diff for replay attacks.',
  { level: 'high', schema: { findings: 'array', severity: 'string' } }
);
console.log(JSON.stringify(review, null, 2));

1. Architecture and Positioning: Where Neon Sits in the Gemini 4 Family

On November 18, 2026, Google DeepMind officially released Gemini 4 Neon, the fourth member of the Gemini 4 family. Its core positioning: near-Carbon quality at Flash-tier speed and cost.

[!NOTE] Sources and Channel Specifications This is a forward-looking engineering analysis based on verified platform releases. Capability and spec details synthesize three authoritative source classes: Google DeepMind’s official launch announcement (2026-11-18), Google Antigravity release notes, and Google AI Studio / developer gateway pricing APIs.

  • Channel Context Differences: In the native Google Antigravity environment (IDE / sidecar agents), Neon is configured with a 512K token context window; via the Gemini Developer API / Google AI Studio, it supports up to 1,000,000 (1M) unified tokens;
  • Caching Architecture: Gemini 4 models exclusively use fully automatic Implicit Context Caching, activating at an entry floor of 4,096 (4K) tokens with up to 95% input discount on repeated prefixes (no explicit cachedContents creation required, eliminating hourly idle storage fees);
  • Pricing Basis: Rates shown reflect developer preview pricing — final production rates will be confirmed at general availability.
flowchart LR
    subgraph Gemini 4 Family Quality Ladder
        H["Gemini 4 Hydrogen<br/>Speed Tier<br/>$0.10 / $0.40 · 232 tok/s"]
        N["Gemini 4 Neon<br/>High-Efficiency Tier<br>$0.35 / $1.40 · 160 tok/s<br/>NEW · Nov 2026"]
        A["Gemini 4 Argon<br/>Agentic Reasoning<br>$1.20 / $4.80 · 125 tok/s"]
        C["Gemini 4 Carbon<br/>Flagship SOTA #1<br>$2.50 / $10.00 · 95 tok/s"]
    end
    H -->|"quality step"| N -->|"quality step"| A -->|"quality step"| C
    style N fill:#0c2a4d,stroke:#38bdf8,stroke-width:2px
SpecGemini 4 NeonGemini 4 CarbonGemini 4 Hydrogen
Context window1,000,000 unified2,000,0001,000,000
Max output (long decode)65,53665,53665,536
Input / Cached input / Output ($ per 1M)†$0.35 / $0.0875 / $1.40$2.50 / $0.625 / $10.00$0.10 / $0.025 / $0.40
ThinkingConfigurable Low / Medium / HighConfigurable budgetConfigurable budget
Nominal TTFT / throughput†180 ms / 160 tok/s240 ms / 95 tok/s118 ms / 232 tok/s
RoleDaily high-efficiency codingArchitecture final review, cyber auditMicro-tasks, autocomplete fan-out

† Prices are developer Preview Pricing — recheck against official rates at GA; TTFT / throughput are official preview nominals, and real-world numbers vary with load, region, and gateway.

Three architectural facts matter for engineering decisions:

  1. 1M unified context. Unlike legacy split-context designs, Neon’s 1M window is unified across code, documents, images, and tool I/O — the same budget agentic loops draw from. Million-token dependency analysis fits in a single request instead of a chunked map-reduce (§2.2 gives the architectural argument for why chunking degrades structurally).
  2. Long decode. The 65,536-token output ceiling plus 160 tok/s nominal sustained decode means a full 3,000-line scaffold lands in ~7 minutes by arithmetic on nominal throughput (vs ~11.5 for Carbon) — Neon is built to finish long generations, not just start them fast.
  3. Configurable Thinking Level. low | medium | high maps to an internal thinking budget (§4.5). Thinking tokens are billed at the output rate, so the level you pick is a direct line-item on your bill — this is a dial, not a feature flag.

[!TIP] Model Selection Rule of Thumb Hydrogen for syntax-level fan-out, Neon for the bulk of daily engineering work, Argon for long-horizon multi-tool agent orchestration, Carbon for final architecture review and security audit. The interesting fight is always Neon vs Carbon — §2 gives you a workload-profile framework, §3 gives you the complete caching math.


2. Model Selection Framework: Decide by Workload Profile, Not by Leaderboard

2.1 Five high-frequency engineering workload profiles

Selection shouldn’t start from “which model scores highest” but from which capability the workload actually stresses. Here are the five recurring agentic-coding profiles and the architecture each one demands:

#Workload profilePrimary stress dimensionKey architectural capabilityRecommended tier
L1Cross-file refactor (rename API, migrate call sites)Context capacity + multi-file consistency1M unified window, long decodeNeon
L21M-token dependency analysis / circular-import reportLong context + cross-file reference tracking1M+ unified window (avoid chunking)Neon / Carbon
L3Strict JSON Schema extraction from noisy corporaStructured-output disciplineresponseMimeType + client-side validationNeon (Low/Medium)
L4Algorithm derivation, concurrency proofsDeep reasoningThinking High / stronger reasoning tierCarbon
L5Toolchain orchestration (git / pkg mgr / test loops)Tool-loop stability, long-horizon coherenceLong-horizon planning and state trackingArgon / Carbon

Use the framework by profiling your own task distribution first, then routing: for an interactive coding context where ~90% of turns are L1/L3, keeping Neon as the workhorse and reserving Carbon for L4 terminal review follows directly from the price structure (§1 table); an automation pipeline dominated by L5 should tilt budget toward Argon instead.

2.2 The architectural argument for long context: why chunking degrades structurally

Stuffing a large-repo analysis into a smaller-window model means chunked map-reduce — which carries three unavoidable mechanical losses:

  1. Cross-chunk reference loss. Circular dependencies and implicit interface contracts live exactly at chunk boundaries; per-chunk summarization destroys those references before the reduce step ever sees them.
  2. Per-chunk preamble duplication. The stable preamble (build config, core types, docs) must repeat in every chunk, so input tokens scale linearly with chunk count — an overhead you can quantify directly with the §3.3 cost model.
  3. Aggregation-stage compression. The reduce step consumes per-chunk summaries, not the source; summarization losses compound at aggregation.

A unified 1M window eliminates the first two by construction. This is an architectural argument, not a benchmark — it rests only on the two structural facts of reference integrity and linear billing.

2.3 How to build a trustworthy evaluation: methodology, not conclusions

If you want to adjudicate Neon vs Carbon on your own repository, run this methodology — and treat any “precise Pass@1” of unknown provenance with suspicion:

  1. Let the test suite adjudicate. Pass@1 = first-attempt pass rate against a locked test suite. If npm test / pytest can decide it, never introduce subjective LLM-grader scores.
  2. ≥ 30 repetitions per task; report confidence intervals. At 40 runs, the 95% CI on Pass@1 is still roughly ±15 percentage points wide — any point estimate without an interval has no decision value.
  3. Beware judge-model bias. If a model must grade, it should come from a non-contending family with a rubric locked item-by-item; models systematically favor their own kin.
  4. Run cost accounting through the §3.3 formula. Report cache hit ratio separately — it often swings the verdict more than the model price gap itself.
  5. Publish the task list and rubric. A non-reproducible evaluation is no evaluation.

We deliberately publish no self-run Pass@1 numbers in this guide: without a public task set, rubric, and repetition count, such figures are marketing material however precise they look. Official and third-party public evaluations (e.g., the Artificial Analysis indexes) will fill in as GA approaches — trust reproducible sources then.


3. Context Caching Break-Even Model: The Complete Math

Gemini 4 inherits the family’s two-tier caching: implicit (automatic, no storage fee, activates when the repeated prefix is ≥ 32,768 tokens) and explicit pinned caches (TTL-managed, billed storage at $1.00 per 1M tokens per hour). Every cached input token is billed at 25% of list — the 75% discount. Here is when each tier pays off for Neon (derived from §1 preview pricing; redo with official rates at GA).

3.1 Blended input price formula

With a sustained cache hit ratio c on input price P:

P_eff(c) = P × (1 − 0.75c)          // blended $/1M input tokens

Gemini 4 Neon:   P_eff(c) = 0.35  × (1 − 0.75c)
Gemini 3 Flash:  P_eff(c) = 0.50  × (1 − 0.75c)     → cached floor $0.125
Gemini 4 Carbon: P_eff(c) = 2.50  × (1 − 0.75c)     → cached floor $0.625
Hit ratio cNeon P_effFlash P_effCarbon P_eff
0%$0.3500$0.5000$2.5000
25%$0.2844$0.4063$2.0313
50%$0.2188$0.3125$1.5625
75%$0.1531$0.2188$1.0938
85.7%$0.1250$0.1781$0.8906
95%$0.1006$0.1438$0.7188

Conclusion 1 — Neon dominates the budget tier at every hit ratio. At c = 0, Neon’s $0.35 preview input is already 30% below Flash’s $0.50, and Neon’s output price ($1.40) is 53% below Flash’s ($3.00). Caching never creates the advantage — it compounds it.

Conclusion 2 — the 85.7% crossover. Solve 0.35 × (1 − 0.75c) ≤ 0.125 (Flash’s own cached floor) and you get c ≥ 85.7%. Above a sustained ~86% hit ratio, a higher-quality model is literally cheaper per input token than the budget model’s best case. In practice, a well-disciplined agentic loop (stable preamble first, volatile diff last) can push its sustained ratio into this band — implicit caching rewards prefix discipline, which is exactly why the discipline is worth investing in.

Conclusion 3 — the 32K activation floor is the real threshold. Below a 32,768-token repeated prefix, c is structurally 0%: no discount exists to compound. This is why the break-even question is never “Neon or Flash?” but “is my context ≥ 32K and reused?” If yes, Neon’s economics are untouchable at its quality level.

3.2 Pinned-cache reuse break-even (explicit tier)

Explicit caches pin an artifact (a monorepo AST, a spec corpus) for a TTL and pay storage. The two ledgers use different units — keep them separate: storage accrues linearly per hour whether or not hits occur (idle hours bill too); savings settle per hit at 0.75 × P (per 1M tokens). The break-even reuse count is therefore independent of context size:

N* = ⌈ S × T / (0.75 × P) ⌉      // S = $1.00/1M·h, T = TTL hours, P = list input $/1M

Neon:     N* = ⌈ 1.00 / (0.75 × 0.35) ⌉ = ⌈3.81⌉ = 4  reuses per TTL hour
Carbon:   N* = ⌈ 1.00 / (0.75 × 2.50) ⌉ = ⌈0.53⌉ = 1  reuse per TTL hour
Hydrogen: N* = ⌈ 1.00 / (0.75 × 0.10) ⌉ = ⌈13.3⌉ = 14 reuses per TTL hour

Read that carefully — it inverts the intuition from §3.1:

  • Expensive models amortize pinned storage fastest — but “fastest” has a precise meaning. Each Carbon hit saves 0.75 × $2.50 = $1.875/1M, covering ~1.9 hours of storage — yet because storage accrues every hour regardless of hits, the break-even is ≥ 1 hit per hour, not “one hit buys two hours.”
  • Neon needs ≥ 4 reuses per hour before pinning beats re-sending at full uncached price. Note the comparison baseline: if your repeated prefix is ≥ 32K and the implicit cache is already hitting, plain re-sends enjoy the same 75% discount — at that point the incremental value of pinning is TTL determinism and cross-session/cross-batch reuse, not a lower unit price.
  • Practical rule: CI bursts (a PR opens, 12 checks hit within minutes) clear N* = 4 trivially — pin the repo cache on pull_request webhooks. Human-paced, sporadic sessions should rely on implicit caching and skip the storage fee entirely.

3.3 Full-task cost model (copy this into your budget sheet)

Cost_task = [ I_u × P + I_c × 0.25P + (O + T_think) × P_out ] / 1e6

where  I  = input tokens (I_u uncached + I_c cached, prefix ≥ 32K required for I_c)
       O  = output tokens
       T_think = thinking tokens (billed at OUTPUT rate — level is a budget, §4.5)
       P, P_out = $0.35 / $1.40 for Neon (preview pricing)
       pinned caches add: S × I_pinned/1e6 × T_hours  ($1.00/1M·h)

[!TIP] Run these numbers live The Model Lab calculator ships a built-in Context Caching Break-even Lab — drag the hit-rate slider and watch Neon / Carbon / Argon blended prices, N* thresholds, and monthly savings recompute in real time, in USD / CNY / EUR / JPY. It also flags it explicitly when your input is below the 32K activation floor.


4. Full-Stack Integration Playbook

4.1 Cursor

Settings → Models → Add model (OpenAI-compatible endpoint), or edit ~/.cursor/config.json:

{
  "openaiBaseUrl": "https://generativelanguage.googleapis.com/v1beta/openai/",
  "apiKeyEnvVar": "GEMINI_API_KEY",
  "models": [
    { "id": "gemini-4-neon",        "name": "Gemini 4 Neon",  "contextWindow": 1000000 },
    { "id": "gemini-4-neon-high",   "name": "Neon · High Thinking", "reasoning": true }
  ]
}
  • baseUrl: https://generativelanguage.googleapis.com/v1beta/openai/ (keep the trailing slash)
  • API Key: store in GEMINI_API_KEY, never in the config file — Cursor reads env vars
  • Thinking: the -high alias pins Thinking Level high for plan-mode prompts; default id runs medium, our recommended daily driver (§4.5)
  • Billing: calls through the OpenAI-compatible endpoint bill at preview rates too; trust the Google Cloud invoice when GA repricing lands

4.2 Cline / Roo Code (VS Code)

cline_mcp_settings.json provider block:

{
  "apiProvider": "openai-compatible",
  "baseUrl": "https://generativelanguage.googleapis.com/v1beta/openai/v1",
  "modelId": "gemini-4-neon",
  "thinkingLevel": "medium",
  "maxOutputTokens": 65536
}

Roo Code: same base URL under Custom OpenAI-compatible provider, model gemini-4-neon, and enable Prefix cache affinity so Cline’s file-context re-sends hit Neon’s implicit cache. With prefix discipline in place, cached input settles at $0.0875/1M (§3.1 table) — the larger the working set and the more frequent the reuse, the bigger the savings.

4.3 OpenRouter and Google AI Studio

  • OpenRouter: model slug google/gemini-4-neon — prompts pass through unchanged and the cache discount follows Google-side rules, so the §3 math transfers (check OpenRouter’s pricing page for its live markup and billing granularity; :floor variants suit cost-pinned production loads).
  • Google AI Studio: select Gemini 4 Neon in the model picker; the Thinking slider maps to Low / Medium / High; use System Instructions for the stable preamble (cache-eligible) and keep volatile user turns last. Generate the API key from Get API key → save as GEMINI_API_KEY. Preview-period quotas and prices in AI Studio may differ from the Cloud channel — its console is the source of truth.

4.4 Official SDK — production patterns

Node.js (@google/genai): see the full copy-paste router in the artifact box at the top of this page (backoff retry, Thinking presets, strict JSON parse). Core call:

import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const res = await ai.models.generateContent({
  model: 'gemini-4-neon',
  contents: `${STABLE_REPO_PREAMBLE}\n\n## Task\n${diff}`,
  config: {
    thinkingConfig: { thinkingLevel: 'medium', thinkingBudget: 4096 },
    responseMimeType: 'application/json',
  },
});

Python (google-genai):

from google import genai
from google.genai import types

client = genai.Client()  # reads GEMINI_API_KEY

response = client.models.generate_content(
    model="gemini-4-neon",
    contents=f"{STABLE_REPO_PREAMBLE}\n\n## Task\n{diff}",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(
            thinking_level="MEDIUM",   # LOW | MEDIUM | HIGH
            thinking_budget=4096,
        ),
        response_mime_type="application/json",
    ),
)

Pinned cache for CI bursts (only when you’ll clear N* = 4, §3.2):

pinned = client.caches.create(
    model="gemini-4-neon",
    config=types.CreateCachedContentConfig(
        contents=[types.Content(parts=[types.Part.from_text(repo_snapshot)])],
        ttl="3600s",
        display_name="ci-repo-cache",
    ),
)
# then: config=types.GenerateContentConfig(cached_content=pinned.name, ...)

4.5 Thinking Level economics — the pricing arithmetic and engineering guidance

Thinking tokens settle at the output rate (preview $1.40/1M), so the level’s cost is plain arithmetic — “added cost per task” = thinking budget × output rate, independent of task difficulty:

LevelBudgetAdded cost per task¹PositioningUse for
Low1,024+$0.0014Minimum costSyntax transforms, i18n strings, log triage
Medium4,096+$0.0057Daily defaultDaily coding default — the bulk of turns
High8,192+$0.0115Deep reasoningConcurrency proofs, migration plans, diff review of other agents

¹ Budget cap × $1.40/1M, derived from preview pricing; actual thinking consumption is reported in the response usage metadata.

The level’s effect on final quality has no universal number — it depends on your task distribution; calibrate on your own set with the §2.3 methodology before locking policy. The cost-side asymmetry, though, is settled: High costs 2× Medium’s thinking budget and belongs only in the terminal review step; the half-cent Low saves usually gets clawed back with interest by the “failed test → retry” loop — for anything that reaches a test suite, Low is false economy. If you are running a swarm, the standard routing is Low for Hydrogen verifiers, Medium for Neon workers, High only for the Carbon coordinator’s final verdict (see the Swarm + SDK enterprise guide).


5. Production Checklist

  1. Default gemini-4-neon for interactive engineering traffic; escalate to Carbon by policy (security-touching diffs, architecture ADRs), not by habit.
  2. Enforce preamble stability in agent frameworks — byte-identical prefixes push implicit cache hit ratios toward the 85.7% crossover (§3.1).
  3. Pin caches only on CI bursts (≥ 4 reuses/TTL-hour, §3.2), TTL 1h, invalidate on merge to main; if your prefix is ≥ 32K with implicit caching already hitting, skip the storage fee.
  4. Set Thinking Level per role, not per user: Medium default, High terminal review, Low never on test-covered code — and calibrate on your own task set with §2.3 before rollout.
  5. Monitor hit ratio and cost-per-successful-task — both are exported by the boilerplate in the Swarm + SDK enterprise guide, so you can measure them on your own repos.

Related: Cross-platform terminal install (RU) · Model Lab calculator · Antigravity 2.6 platform overview