Google Gemini

Hermes Agent は Google Gemini をネイティブのプロバイダとして扱い、Google AI Studio / Gemini API を使います。OpenAI 互換のエンドポイントではありません。これにより Hermes は、内部で持っている OpenAI 形式のメッセージとツールのやり取りを Gemini ネイティブの generateContent API へ変換しつつ、ツール呼び出し、ストリーミング、画像などを含む入力、Gemini 固有の応答メタデータをそのまま活かせます。

事前に必要なもの

• Google AI Studio の API キー — aistudio.google.com/apikey で作成します
• 課金を有効にした Google Cloud プロジェクト — エージェントとして使うなら用意しておくことをおすすめします。Hermes はユーザーの 1 往復ごとに何度もモデルを呼ぶことがあるため、Gemini の無料枠では長時間のセッションには足りません。
• Hermes のインストール — ネイティブの Gemini プロバイダに追加の Python パッケージは要りません

クイックスタート

# 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 Gemini models
# → Select a model

# Start chatting
hermes chat

設定ファイルを直接書きたい場合は、Gemini ネイティブ API のベース URL を指定します。

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

設定

hermes model を実行したあと、~/.hermes/config.yaml は次のような内容になります。

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

そして ~/.hermes/.env はこうなります。

GOOGLE_API_KEY=...

Gemini ネイティブ API

おすすめのエンドポイントはこちらです。

https://generativelanguage.googleapis.com/v1beta

Hermes はこのエンドポイントを検出すると、ネイティブの Gemini アダプタを作ります。内部ではエージェントのやり取りを OpenAI 形式のメッセージのまま保持し、リクエストごとに Gemini ネイティブのスキーマへ変換します。

• messages[] → Gemini の contents[]
• システムプロンプト → Gemini の systemInstruction
• ツールのスキーマ → Gemini の functionDeclarations
• ツールの実行結果 → Gemini の functionResponse パート
• ストリーミング応答 → Hermes のやり取り用に OpenAI 形式のストリームチャンクへ

ツールのパラメータで "type": ["number", "null"] のように型を配列で書いたものは、Gemini のスカラー型と nullable を組み合わせた形へ変換されます。複数の型を並べたユニオンは、入れ子のプロパティや配列の要素も含めて、anyOf ですべての候補を残します。これは自動で行われるので、MCP サーバーやプロバイダの設定を変える必要はありません。

ネイティブのエンドポイントを使う

Google は OpenAI 互換のエンドポイントも公開しています。

https://generativelanguage.googleapis.com/v1beta/openai/

Hermes のエージェントセッションでは、上に挙げた Gemini ネイティブのエンドポイントを選んでください。Hermes にはネイティブの Gemini アダプタが入っているので、複数往復のツール利用、ツールの実行結果、ストリーミング、画像などを含む入力、Gemini の応答メタデータを、そのまま Gemini の generateContent API に対応づけられます。OpenAI 互換のエンドポイントは、どうしても OpenAI API との互換性が必要なときには役に立ちます。

以前に GEMINI_BASE_URL を /openai の URL に設定していた場合は、削除するか次のように書き換えます。

GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta

Google のホストのルートだけを書いたベース URL は、自動で整えられます。URL が API のバージョンの区切り （v1beta、v1alpha、v1、...）で終わっていなければ、Hermes が /v1beta を足すので、 GEMINI_BASE_URL=https://generativelanguage.googleapis.com と書いても、/v1beta まで書いたときと同じように動きます。 同じ整え方は Gemini の TTS のベース URL（tts.gemini.base_url）にも当てはまります。チャットの要求がネイティブの Gemini の経路を通るのは、ベース URL が generativelanguage.googleapis.com か、下で説明する Vertex AI の エクスプレス用のホストを指しているときだけです。ほかのホストにあるプロキシは OpenAI 互換のエンドポイントとして 扱われるので、/openai の形の URL で設定してください。

Vertex AI のエクスプレスモードのキー

Google はいま、Google AI Studio と Vertex AI のエクスプレスモードの どちらにも AQ.… で始まる キーを出しています（従来の AIza… という AI Studio の形式は、順次なくなっていく予定です）。 そのため、キーの頭の文字を見ても、どちらのサービス向けかは分かりません。Hermes がキーの形で 経路を切り替えることはありません。どちらへ行くかを決めるのは、設定したベース URL です。 既定の AI Studio のホストを使うなら、GEMINI_API_KEY を設定して GEMINI_BASE_URL は 設定しないままにします。Vertex AI のエクスプレスモードのキーを使うなら、GEMINI_BASE_URL に https://aiplatform.googleapis.com を設定してください（/v1beta1 はあってもなくても構いません）。 Hermes が publishers/google の形まで補います。どちらのサービスも、自分向けのキーしか受け付けません。 403 PERMISSION_DENIED が返るときは、たいていキーとホストの組み合わせが食い違っています。 Hermes は、もう一方のサービスの名前を挙げた案内を添えます。ほかのホストを指すベース URL （プロキシなど）が書き換えられることはありません。エクスプレスのキーは、OAuth を使う Vertex AI プロバイダとは別のもので、そちらは API キーを必要としません。

global のロケーションでしか提供されていないモデル（Gemini 4 Argon）には、ロケーションを付けない エクスプレスのホストからは届きません。このホストは us-central1 へつながるためです。こうしたモデルを使うときは、 ベース URL をプロジェクト付きの形 https://aiplatform.googleapis.com/v1beta1/projects/<project>/locations/global にしてください。Hermes が同じように …/publishers/google の形まで補います。

使えるモデル

hermes model の選択画面には、Hermes のプロバイダ登録簿で管理している Gemini モデルが並びます。よく選ばれるのは次のものです。

使えるモデルは時期によって変わります。モデルが消えていたり、手元のキーで有効になっていなかったりしたら、もう一度 hermes model を実行して、その時点の一覧から選び直してください。

Gemini 4 Argon の推論の強さと長いデコード

Gemini 4 Argon は常に思考します。Hermes は推論の強さ（/reasoning、 agent.reasoning_effort）を、このモデルの thinkingLevel へ次のように割り当てます。

長いデコードを使わない場合、1 回のリクエストは、ストリーミングなら 65,536 トークン （ストリーミングでなければ 32,768 トークン）を出力したところで止まります。この数には思考の分も含まれます。xhigh か max のときは、Hermes が maxOutputTokens を引き上げます。さらに、リクエストが 1 回分の上限に達してもまだ予算が残っているとき （finishReason: CONTINUATION）は、Google の continuationToken を付けて同じリクエストを送り直し、モデルが書き終えるまで続けます。こうして何回かに分けた応答は、1 つの返答にまとめられます。

複数回に分けたときの使用量は、Google の課金と同じ数え方で報告されます。送り直すたびに プロンプトとそれまでの出力をもう一度読み込むので、入力の合計は実際の コンテキストよりはるかに大きくなります。Hermes は料金をこの合計で計算しますが、コンテキストの圧縮と コンテキストの残量表示には最初の 1 回目のプロンプトの大きさを渡します。そのため、長いデコードを使った 1 往復が原因で 圧縮が早まることはありません。長いデコードが動くのはネイティブのエンドポイント（AI Studio と Vertex AI のエクスプレスモード）だけです。Google の /openai 互換エンドポイント、OpenRouter、 OAuth を使う Vertex AI プロバイダでは、1 回のリクエストの上限で止まります。

latest のエイリアス

Google は Gemini の Pro 系と Flash 系について、追従して動くエイリアスを公開しています。gemini-pro-latest と gemini-flash-latest は、Hermes の設定を書き換えずに Google 側でモデルを新しくしてほしいときに便利です。ただし、新しいモデルの料金が変わると、支払う金額にも影響することがあります。

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

毎回きっちり同じ結果を再現したいなら、gemini-3.1-pro-preview や gemini-3.7-flash のように明示的なモデル ID を選んでください。

Gemini API 経由の Gemma

Google は Gemma のモデルも Gemini API から公開しています。Hermes はこれらを Google のモデルとして認識しますが、処理量がとても小さい Gemma は既定の選択画面から隠しています。長く動かすエージェントのセッションに、評価用のモデルをうっかり選んでしまわないようにするためです。

評価に使いやすい ID には次のものがあります。

これらは Gemini API のキーで試せる評価用の選択肢と考えるのが良いでしょう。Google の Gemma API は無料枠だけの提供で、上限も本番向けの Gemini モデルに比べて低いため、Hermes のエージェントを継続的に動かすなら、有料の Gemini モデル、自前で立てた環境、あるいは十分な割り当てのある別のプロバイダへ移るのが普通です。

選択画面に出てこない Gemma を使いたいときは、直接指定します。

model:
  default: gemma-4-31b-it
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

会話の途中でモデルを切り替える

会話の最中に /model コマンドを使います。

/model gemini-3.7-flash
/model gemini-flash-latest
/model gemini-3.1-pro-preview
/model gemini-pro-latest
/model gemma-4-31b-it
/model gemini-3.1-flash-lite-preview

Gemini をまだ設定していない場合は、いったんセッションを抜けて先に hermes model を実行してください。/model は設定済みのプロバイダとモデルのあいだで切り替えるだけで、新しい API キーを聞いてはくれません。

診断

hermes doctor

doctor は次を確認します。

• GOOGLE_API_KEY または GEMINI_API_KEY が使える状態か
• 設定したプロバイダの認証情報を解決できるか

ゲートウェイ（メッセージのやり取り）

Gemini は Hermes のゲートウェイが対応するすべてのサービス（Telegram、Discord、Slack、WhatsApp、LINE、Feishu など）で動きます。プロバイダとして Gemini を設定したら、あとはいつもどおりゲートウェイを起動します。

hermes gateway setup
hermes gateway start

ゲートウェイは config.yaml を読み、同じ Gemini の設定をそのまま使います。

うまくいかないとき

「Gemini native client requires an API key」と出る

Hermes が使える API キーを見つけられませんでした。次のどちらかを ~/.hermes/.env に追加してください。

GOOGLE_API_KEY=...
# or
GEMINI_API_KEY=...

そのあと、もう一度 hermes model を実行します。

「This Google API key is on the free tier」と出る

Hermes は設定のときに Gemini の API キーを調べます。ツールの利用、やり直し、履歴の圧縮、補助的な処理などで何度もモデルを呼ぶことがあるため、無料枠の割り当てはエージェントの数往復で尽きてしまうことがあります。

キーがひもづいている Google Cloud プロジェクトで課金を有効にし、必要ならキーを作り直してから、次を実行します。

hermes model

「404 model not found」と出る

選んだモデルが、そのアカウント、地域、キーでは使えません。もう一度 hermes model を実行し、その時点の一覧から別の Gemini モデルを選んでください。

hermes model に Gemma のモデルが出てこない

Hermes は処理量の小さい Gemma を既定で選択画面から隠していることがあります。あえて試したい場合は、~/.hermes/config.yaml にモデル ID を直接書いてください。

Gemma で「429 quota exceeded」と出る

Gemini API から使える Gemma は評価には便利ですが、Gemini API の無料枠の上限は低めです。互換性の確認までにとどめ、続けてエージェントを動かすなら有料の Gemini モデルか別のプロバイダに切り替えてください。

OpenAI 互換のエンドポイントが設定されている

~/.hermes/.env に次の行がないか確認します。

GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/

ネイティブのエンドポイントに書き換えるか、この上書き自体を消します。

GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta

ツール呼び出しがスキーマのエラーで失敗する

Hermes を新しくしてから hermes model を実行し直してください。ネイティブの Gemini アダプタは、Gemini の厳しめな関数宣言の形式に合わせてツールのスキーマを整えます。古いビルドや独自のエンドポイントでは、これが行われないことがあります。

関連

• AI プロバイダ
• 設定
• 予備のプロバイダ
• AWS Bedrock — AWS の認証情報を使ったクラウド側のネイティブ連携