Description

n8n-nodes-gemini3-vertex

n8n community nodes that expose Gemini 3 features for Google Vertex AI.

Nodes

• Google Vertex Chat Model (Gemini 3) — a Chat Model sub-node for Agents

and Chains. Adds the native Gemini 3 thinking level
(MINIMAL/LOW/MEDIUM/HIGH), a thinking budget, per-category safety
settings, and a streaming toggle.

• Google Vertex Gemini 3 — an action node with a Message a Model

operation. Adds the native thinking level, thought summaries, per-category
safety settings, Google Search grounding, and structured JSON output.

Both Model and Thinking Level are resource locators — pick from a list
or switch to Expression / ID mode to supply the value dynamically. Safety
settings expose one threshold dropdown per harm category, all at once, so there
is no per-row “add item” clicking.

Installation

In n8n: Settings → Community Nodes → Install and enter
n8n-nodes-gemini3-vertex.

Credentials

Both nodes use the built-in Google API credential — a GCP service account
with the Vertex AI API enabled (email, private key, region).

Model selection

The Model field is a resource locator: From List queries the live Vertex
AI model catalogue (ai.models.list, base models, filtered to Gemini) for the
selected project and region, so it never goes stale — or switch to ID to type
a model name directly.

Leave the Model field empty and the node auto-resolves the **latest flash
model** at run time — it queries the live catalogue and picks the highest
Gemini version of gemini--flash (excluding flash-lite and non-chat
flash variants). No hardcoded model, nothing to keep updating.

Feature placement

• The sub-node forwards the native thinking level and thinking budget through

@langchain/google-vertexai (pinned to 2.1.24, matching the version n8n
itself ships, to avoid duplicate-@langchain/core runtime conflicts).

• Thought summaries as an independent toggle live on the action node.

The sub-node’s LangChain layer couples thought inclusion to the thinking
budget rather than exposing a separate switch.

Gotchas with Gemini 3.x

• includeThoughts / thoughtSummary — On Gemini 3.x, the flag is accepted

by Vertex (the model still thinks; you can see the token count in
usageMetadata.thoughtsTokenCount), but the response **does not include the
thought text** the way Gemini 1.5 / 2.x did. The action node’s
thoughtSummary output field will be empty for 3.x models. Use it with 1.5 /
2.x if you need the readable reasoning.

• Thinking-by-default models eating your tokens. Gemini 3.5 (and similar

thinking-by-default flash models) will consume your entire maxOutputTokens
on reasoning if you don’t bound it. If you ask for a short answer with a
small token budget and get back empty text, set Thinking Level = Minimal
(or give it more tokens). This caught us in the integration tests — the same
trap will catch a workflow.

Caveat: grounding & JSON output

Google Search grounding and forced JSON output conflict with how n8n Agents
bind their own tools, so they live on the action node rather than the
sub-node. The two features also cannot be combined with each other (a Gemini
API restriction); the action node validates this and errors clearly.

Development

npm install --ignore-scripts   # eslint-plugin-n8n-nodes-base has a pnpm-only preinstall guard
npm run build
npm test                       # unit tests — mocked, no network

Requires Node.js 20+.

Live integration tests

npm run test:integration exercises both nodes against the real Vertex AI
API and verifies the parameters the nodes send actually take effect in
Google’s response. It needs a GCP service-account key:

export GCPKEYFILE=/absolute/path/to/service-account.json
optional overrides:
export GCPPROJECTID=my-project     # defaults to project_id in the key file
export GCP_LOCATION=us-central1      # default
export GEMINI_MODEL=gemini-3.1-pro        # default
npm run test:integration

Without GCPKEYFILE the suites skip themselves, so a normal npm test
never makes network calls. These tests make billable API calls.

What is verified against the live response:

| Parameter | Verified via |
| — | — |
| thinkingLevel (MINIMAL→HIGH) | usageMetadata.thoughtsTokenCount scales up (action node); usagemetadata.outputtoken_details.reasoning (sub-node) |
| includeThoughts | a response part with thought: true |
| Google Search grounding | candidates[].groundingMetadata present |
| responseSchema | output parses as schema-shaped JSON |
| maxOutputTokens | finishReason === 'MAX_TOKENS' |
| systemInstruction | model obeys the instruction |
| streaming | generateContentStream / .stream() yields chunks |
| latest-flash resolution | resolveLatestFlash returns a live *-flash model (not flash-lite) |
| safety settings | accepted without error, normal response still produced |
| temperature / topP / topK | accepted without error (Google does not echo these back) |