Connect Google Gemini

Connect Google Gemini

If you’ve been following along with our Hermes Agent series, you know we love giving you choices. Today, we’re diving into one of the most popular options: Google Gemini. The good news? Hermes now supports Gemini as a native provider — no OpenAI-compatible workarounds needed.

What’s New with Gemini Support?

Previously, connecting Gemini meant routing through an OpenAI-compatible endpoint. That worked, but it wasn’t perfect. Now, Hermes speaks Gemini’s native language through the generateContent API. This means better tool calling, smoother streaming, proper multimodal support, and access to Gemini-specific response metadata.

In plain English: your agent conversations will feel more natural, and complex multi-step tasks will work more reliably.

What You’ll Need

Before we start, grab these:

• A Google AI Studio API key — get one free at aistudio.google.com/apikey
• A billing-enabled Google Cloud project — this is important! Gemini’s free tier is too small for long agent sessions since Hermes may make several model calls per user turn
• Hermes installed — no extra Python packages required for the native provider

One quick tip: you can set your key as either GOOGLE_API_KEY or GEMINI_API_KEY. Hermes checks both names.

Quick Start Guide

Ready to connect? Here’s the fastest path:

# Add your Gemini API key
echo "GOOGLE_API_KEY=..." >> ~/.hermes/.env

# Select Gemini as your provider
hermes model
# → Choose "More providers..." → "Google AI Studio"
# → Hermes checks your key tier and shows available models
# → Select a model

# Start chatting
hermes chat

Prefer editing config files directly? Here’s what your ~/.hermes/config.yaml should look like:

model:
  default: gemini-3.7-flash
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

Why the Native Endpoint Matters

Google offers two ways to connect: a native Gemini API and an OpenAI-compatible endpoint. For Hermes agent sessions, always prefer the native endpoint:

https://generativelanguage.googleapis.com/v1beta

Here’s why: Hermes internally keeps its agent loop in OpenAI-shaped messages, then translates everything to Gemini’s native schema. This includes:

• Messages → Gemini contents[]
• System prompts → Gemini systemInstruction
• Tool schemas → Gemini functionDeclarations
• Tool results → Gemini functionResponse parts
• Streaming → OpenAI-shaped chunks for the Hermes loop

If you previously set GEMINI_BASE_URL to the /openai URL, remove it or change it to the native endpoint above.

A couple of handy details: if your base URL is just the Google host with no version segment, Hermes adds /v1beta for you — so https://generativelanguage.googleapis.com works the same as the full path. The same applies to the Gemini TTS base URL. And note that chat only takes the native Gemini path when the base URL points at generativelanguage.googleapis.com or the Vertex AI express host; a proxy on another host is treated as OpenAI-compatible, so give it its /openai-style URL.

Vertex AI Express Mode Keys

Google now issues AQ.…-prefixed keys for both Google AI Studio and Vertex AI express mode (the legacy AIza… Studio format is being phased out), so a key’s prefix no longer identifies its surface. Hermes never reroutes by key shape: the configured base URL decides the surface. Set GEMINI_API_KEY and leave GEMINI_BASE_URL unset for the default AI Studio host; set GEMINI_BASE_URL to https://aiplatform.googleapis.com (with or without /v1beta1) for a Vertex AI express-mode key, and Hermes completes it to the publishers/google form. Each surface only accepts its own keys — a 403 PERMISSION_DENIED usually means the key/host pairing is crossed, and Hermes appends guidance naming the other surface. A base URL on any other host (a proxy) is never rewritten. Express keys are separate from the OAuth-based Vertex AI provider, which needs no API key.

Models served only in the global location (Gemini 4 Argon) are not reachable on the bare express host, which routes to us-central1. For those, set the base URL to the project-scoped form, https://aiplatform.googleapis.com/v1beta1/projects/<project>/locations/global, and Hermes completes it to …/publishers/google the same way.

:::warning Upgrade note for existing express-key users Earlier Hermes releases detected the AQ. prefix and rerouted such keys to aiplatform.googleapis.com automatically, so the documented setup was “set GEMINI_API_KEY to the express key and leave GEMINI_BASE_URL unset”. That automatic reroute is gone: with GEMINI_BASE_URL unset, every request — chat, hermes doctor, TTS — now goes to the AI Studio host and a Vertex express key gets 403 PERMISSION_DENIED there. Add GEMINI_BASE_URL=https://aiplatform.googleapis.com to ~/.hermes/.env (or set base_url on the provider) once and restart. :::

Choosing Your Model

The hermes model picker shows all available Gemini models. Here are the most useful ones:

Model	ID	Best For
Gemini 4 Argon	gemini-4-argon	Flagship reasoning model; shared 1M input+output window, long decode up to 1M output tokens
Gemini 3.8 Flash	gemini-3.8-flash	Most capable Flash model for long-horizon agentic and coding work
Gemini 3.7 Flash	gemini-3.7-flash	Recommended default — great speed and capability
Gemini 3.1 Pro Preview	gemini-3.1-pro-preview	Complex reasoning, math, and coding
Gemini 3.5 Flash Lite	gemini-3.5-flash-lite	Fastest, lowest-cost lightweight tasks
Gemini 2.5 Flash	gemini-2.5-flash	Previous gen fast model with thinking
Gemini 2.5 Pro	gemini-2.5-pro	Previous gen complex reasoning

Important: Use native model IDs like gemini-3.7-flash, not OpenRouter-style IDs like google/gemini-3.7-flash.

Gemini 4 Argon: Reasoning Effort and Long Decode

Gemini 4 Argon always thinks; Hermes maps the reasoning effort (/reasoning, agent.reasoning_effort) onto its thinkingLevel:

Hermes effort	thinkingLevel	Total output budget
none, minimal, low	low (thoughts hidden for none)	Per-request cap
medium (Google’s default)	medium	Per-request cap
high	high	Per-request cap
xhigh	high	262,144 tokens (long decode)
max, ultra	high	1,048,576 tokens minus the input (long decode)

Without long decode a single request stops at 65,536 output tokens when streaming (32,768 non-streaming), thinking included. With xhigh or max, Hermes raises maxOutputTokens and, when a request reaches the per-request cap with budget left (finishReason: CONTINUATION), resends the same request with Google’s continuationToken until the model finishes. The hops are joined into one reply.

Usage across hops is reported the way Google bills it: every hop re-reads the prompt plus the output so far, so the summed input count is far larger than the real context. Hermes prices the summed counts but feeds context compaction and the context meter the first hop’s prompt size, so a long-decode turn does not trigger an early compaction. Long decode runs only on the native endpoints (AI Studio and Vertex AI express); Google’s /openai compatibility endpoint, OpenRouter and the OAuth Vertex AI provider stop at the per-request cap.

Smart Aliases for Automatic Updates

Google offers moving aliases that automatically track the latest models:

Alias	Tracks	Use Case
gemini-pro-latest	Latest Pro model	Want Google’s current Pro default
gemini-flash-latest	Latest Flash model	Want Google’s current Flash default

model:
  default: gemini-pro-latest
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

Just remember: if you need strict reproducibility, stick with explicit IDs like gemini-3.1-pro-preview.

A Note on Gemma Models

Gemma models are also available through the Gemini API. Hermes hides very low-throughput Gemma entries from the default picker to prevent accidental selection for long agent sessions. But for evaluation purposes, you can use IDs like gemma-4-31b-it or gemma-4-26b-a4b-it.

Keep in mind these are evaluation options: Gemma’s Gemini API pricing is free-tier-only with low caps, so for sustained agent use you’ll want a paid Gemini model, a self-hosted deployment, or another provider with proper quota.

Final Thoughts

Connecting Gemini to Hermes is now simpler and more powerful than ever. The native adapter means your agents can handle complex tool loops, streaming responses, and multimodal inputs with ease. Start with gemini-3.7-flash for the best balance, and experiment from there!

Happy building!

---

Keep reading: Hermes with Google Vertex AI — Billing through Google Cloud instead? Run Hermes with Google Vertex AI and the same Gemini models.