---
title: "Google Gen AI SDKとは？google-genaiの導入とAgent Platform切替・旧SDK移行【2026年10月】"
url: "https://www.issoh.co.jp/tech/details/8438/"
published: 2025-08-27
updated: 2026-10-22
categories: ["Gemini"]
publisher: "株式会社一創"
---

# Google Gen AI SDKとは？google-genaiの導入とAgent Platform切替・旧SDK移行【2026年10月】

Google Gen AI SDKは、Gemini Developer APIとGemini Enterprise Agent Platform（旧Vertex AI）の両方を1つのクライアントで呼ぶための公式SDKです。Pythonのパッケージ名は`google-genai`で、2026年10月7日時点の最新版は2.28.0（2026年10月2日公開）です。この記事では、導入手順、Interactions APIと`generate_content`の選び分け、Agent Platformへの切り替え、旧`google-generativeai`からの移行を、SDKのソースと公式ドキュメントで確かめた内容で説明します。

## まとめ：Google Gen AI SDKの要点（2026年10月時点）

- 新規開発ではPythonなら`pip install google-genai`、JavaScriptなら`@google/genai`を使います。旧`google-generativeai`と`@google/generative-ai`は2025年11月30日にサポートが終わりました。
- 新しいプロジェクトの呼び出しは`client.interactions.create()`が推奨です。`generate_content`もサポートが続いており、Batch APIや明示的キャッシュを使う処理はこちらに残します。
- Agent Platform（旧Vertex AI）へは`enterprise=True`か環境変数`GOOGLE_GENAI_USE_ENTERPRISE=true`で切り替えます。旧名の`vertexai`も動きますが、両方を矛盾する値で渡すと`ValueError`になります。
- APIキーの環境変数は`GOOGLE_API_KEY`が`GEMINI_API_KEY`より優先されます。両方あると警告が出たうえで`GOOGLE_API_KEY`が使われます。
- リリースは2026年8月以降の2か月で13回あり、更新が速いSDKです。本番ではマイナー版まで固定します。

以下、位置づけ、導入、APIの選び分け、切り替え、移行の順に説明します。

## Google Gen AI SDKの位置づけと対応言語の最新版

### 1つのClientで2つのバックエンドを呼ぶ構造

旧SDKは`GenerativeModel`などのオブジェクトを個別に作る設計で、ファイル操作やキャッシュは別クラスでした。Gen AI SDKは`Client`を1つ作り、`models`・`chats`・`files`・`interactions`などのサービスをその配下から呼びます。2.28.0の`Client`には、ほかに`batches`・`caches`・`tunings`・`auth_tokens`・`aio`（非同期版）などもあります。

SDKが呼ぶ先のGemini APIの全体像（Interactions APIを含むできること、料金、始め方）は[Gemini APIとは？できること・料金・始め方とInteractions APIの最小コード](https://www.issoh.co.jp/tech/details/18759/)で扱っています。

バックエンドはGemini Developer API（AI StudioのAPIキーで使う）とGemini Enterprise Agent Platform（Google Cloudのプロジェクトで使う）の2つです。コードの大半は共通で、初期化の引数だけが変わります。Vertex AIは2026年4月のCloud NextでGemini Enterprise Agent Platformへ改称されましたが、エンドポイントは`aiplatform.googleapis.com`のままです。プラットフォーム側の機能と料金は[Vertex AIの機能・料金とSageMaker/Azure MLとの違い](/tech/details/15546/)で扱っています。

### 言語別パッケージと最新版（2026年10月7日時点・6言語）

| 言語                    | パッケージ                                | 最新版     | 公開日        |
| --------------------- | ------------------------------------ | ------- | ---------- |
| Python                | google-genai                         | 2.28.0  | 2026-10-02 |
| JavaScript／TypeScript | @google/genai                        | 2.27.0  | 2026-10-02 |
| Go                    | google.golang.org/genai              | v1.72.0 | 2026-10-01 |
| Java                  | com.google.genai:google-genai        | 1.75.0  | 2026-10-01 |
| C#                    | Google.GenAI                         | 1.24.0  | 2026-10-01 |
| Kotlin                | com.google.genai:google-genai-kotlin | 1.4.0   | 2026-10-01 |

版番号と日付はPyPI・npm・Goモジュールプロキシ・Maven Central・NuGetのレジストリを直接引いて確かめました（日付はUTC）。動作要件は、PyPIのメタデータがPython 3.10以上、npmの`engines`がNode.js 20以上です。[公式のライブラリページ](https://ai.google.dev/gemini-api/docs/libraries)は本文で「Python、JavaScript/TypeScript、Go、Java」の4言語と書きつつ、C#の`Google.GenAI`もインストール手順付きで載せています。Kotlin版はこのページに無く、Google Cloudブログで2026年9月4日に1.0が発表されたKotlin Multiplatformのライブラリです（JVMとAndroid向け）。Goでの実装は[GoでGemini APIを呼び出す実装手順](/tech/details/2760/)にまとめています。

## Pythonでの導入手順と最初のリクエスト

### インストールとAPIキーの渡し方

APIキーはGoogle AI Studioで発行し、環境変数に入れておくのが基本です。`genai.Client()`を引数なしで作ると、SDKが環境変数からキーを読みます。

```
pip install "google-genai==2.28.0"
export GEMINI_API_KEY="YOUR_API_KEY"
```

公式のクイックスタートは`GEMINI_API_KEY`を使いますが、SDKのソース（`_api_client.py`）は`GOOGLE_API_KEY`を先に見ます。両方が設定されていると「Both GOOGLE\_API\_KEY and GEMINI\_API\_KEY are set. Using GOOGLE\_API\_KEY.」という警告が出て、`GOOGLE_API_KEY`の値が送られます。手元の模擬サーバーで送信ヘッダー`x-goog-api-key`を記録して確かめました。gcloudなどで`GOOGLE_API_KEY`を別用途に設定している環境では、意図しないキーで課金される原因になります。

### Interactions APIの初回呼び出しと会話継続

公式のget-startedページは、Python・JavaScript・Java・Go・RESTのすべてで`interactions.create`と`gemini-3.8-flash`を使っています。

```
from google import genai

client = genai.Client()  # GEMINI_API_KEY（または GOOGLE_API_KEY）を読む

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Google Gen AI SDKを一文で説明して",
)
print(interaction.output_text)

# 会話を続ける：前回のIDを渡すと履歴はサーバー側が持つ
follow_up = client.interactions.create(
    model="gemini-3.8-flash",
    input="Pythonのパッケージ名は？",
    previous_interaction_id=interaction.id,
)
print(follow_up.output_text)
```

このコードは`POST /v1beta/interactions`へ`{"model": ..., "input": ...}`を送ります。2回目もモデル名と新しい入力を送り、過去の会話履歴の代わりに`previous_interaction_id`を渡します。

### generate\_contentの生成設定と構造化出力

旧SDKから移行するコードや、Batch APIと組み合わせる処理では`generate_content`を使います。システム指示や温度は`types.GenerateContentConfig`にまとめて渡し、JSONで受け取るならPydanticのモデルをスキーマにします。

```
from google import genai
from google.genai import types
from pydantic import BaseModel

class Library(BaseModel):
    name: str
    language: str

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Gen AI SDKのPython版パッケージ名を答えて",
    config=types.GenerateContentConfig(
        system_instruction="日本語で簡潔に答える",
        temperature=0.2,
        response_mime_type="application/json",
        response_schema=Library,
    ),
)
print(response.parsed)  # Library(name=..., language=...)
```

送信先は`/v1beta/models/gemini-3.8-flash:generateContent`です。`response.parsed`にはPydanticのインスタンスが入ります。この記事のサンプルは、google-genai 2.28.0とPython 3.11で、応答を固定した模擬サーバーに向けて例外なく動くことを確かめています。実際のモデルの応答内容までは確かめていません。

## Interactions APIとgenerate\_contentの選び分け

[公式のInteractions APIの概要ページ](https://ai.google.dev/gemini-api/docs/interactions-overview)は、2026年6月にGAとなったInteractions APIを「新規プロジェクトに推奨」とし、`generateContent`を「legacy」としながら「fully supported」と書いています。今後の新しいモデル・ツール・エージェント機能はInteractions API側に出るとも書いています。新しく書くコードはInteractions APIで始めてください。

ただし、次の機能は2026年10月時点でInteractions APIにまだありません。使っている処理は`generate_content`に残します。

- Batch API（料金ページでは標準の半額）
- Pythonの自動関数呼び出し（Automatic function calling）
- 明示的なコンテキストキャッシュ（`previous_interaction_id`による暗黙キャッシュは使えます）
- 安全設定（safety settings）のカスタマイズ

見落としやすいのは保存の既定です。Interactions APIは既定で`store=true`となり、やり取りをサーバーに保存します。保持期間は有料枠で55日、無料枠で1日です。`store=False`を渡せば保存されませんが、そのやり取りは`previous_interaction_id`で続けられず、バックグラウンド実行（`background=true`）とも併用できません。個人情報を扱う業務システムでは、会話の状態をクライアント側で持つ設計にして`store=False`を付けるか、AI Studioのログ保持期間（有料枠は7・14・28・55日から選べます）を短く設定してください。

Interactions APIはSDKの中でも変化の大きい部分です。Python SDK 2.0.0（2026年5月7日）はInteractions APIに限った破壊的変更を含み、変更履歴には「`GenerateContent`の使い方は影響を受けない」と明記されています。2.9.0（2026年6月19日）ではInteractions APIの実装そのものが置き換わりました。Interactions APIに依存するコードでは、`google-genai==2.28.*`のようにマイナー版を固定し、変更履歴を読んでから上げます。

## Gemini Developer APIとAgent Platform（旧Vertex AI）の切り替え

### enterprise引数と環境変数での切り替え

```
from google import genai

# Gemini Developer API（APIキー）
dev = genai.Client(enterprise=False, api_key="YOUR_API_KEY")

# Gemini Enterprise Agent Platform（ADCで認証）
# ローカル開発では事前に gcloud auth application-default login を実行
ent = genai.Client(enterprise=True, project="my-project", location="global")
```

環境変数で切り替える場合は、`GOOGLE_GENAI_USE_ENTERPRISE=true`・`GOOGLE_CLOUD_PROJECT`・`GOOGLE_CLOUD_LOCATION`の3つを設定します。Agent Platformの公式SDKページ（2026年10月6日更新）は、ロケーションの例に`global`を使っています。上のコードでDeveloper API側にも`enterprise=False`を書いているのは、`GOOGLE_GENAI_USE_ENTERPRISE=true`が環境に残っていると、APIキーを渡してもAgent Platform側へ送られるためです。

| 設定                             | 扱い（2.28.0）                |
| ------------------------------ | ------------------------- |
| enterprise=True                | 推奨の指定                     |
| vertexai=True                  | 旧名（Legacy flag）として有効・警告なし |
| GOOGLE\_GENAI\_USE\_ENTERPRISE | 推奨の環境変数                   |
| GOOGLE\_GENAI\_USE\_VERTEXAI   | 旧名として有効                   |
| 環境変数の2つが矛盾                     | 警告のうえENTERPRISEを採用        |
| 引数の2つが矛盾                       | ValueError                |

公式ドキュメントの初期化例は、Python SDK 2.6.0（2026年5月21日）の変更で`vertexai`から`enterprise`へ書き換わりました。JavaScript版の型定義（2.27.0）でも`vertexai`には「The `enterprise` flag is recommended instead.」と書かれています。2026年4月以前に書かれた記事やサンプルは`vertexai=True`と`GOOGLE_GENAI_USE_VERTEXAI`を使っていますが、今も動きます。新規コードでは`enterprise`に揃えてください。

### 切り替え時に初期化で止まる条件

SDKのソースと模擬サーバーでの実行で、初期化の時点で例外になる組み合わせを確かめました。

- Developer APIのまま`project`や`location`を渡す：「Gemini API does not support project/location.」の`ValueError`
- `credentials`と`api_key`を同時に渡す：相互排他のため`ValueError`
- `enterprise=True, vertexai=False`のように矛盾させる：`ValueError`（JavaScript版も同じ文面のエラー）

Agent PlatformはAPIキーだけでも使えます（エクスプレスモード）。`enterprise=True`に`api_key`だけを渡すと、送信先は`https://aiplatform.googleapis.com/`になります。`project`と`location="us-central1"`を渡すと`https://us-central1-aiplatform.googleapis.com/`になり、APIバージョンはどちらも`v1beta1`です（Developer APIは`v1beta`）。

### どちらのバックエンドを選ぶかの判断基準

判断を分けるのはデータの扱いです。Gemini APIの料金ページでは、無料枠のデータは「Used to improve our products」が「Yes」、有料枠は「No」です。社内データや顧客データを送るなら、無料枠のDeveloper APIは使いません。有料枠のDeveloper APIか、IAMとプロジェクト単位の権限管理が使えるAgent Platformを選びます。

試作や個人開発ならDeveloper APIで十分です。Google Cloudで既にIAM・VPC Service Controls・リージョン指定を運用している組織はAgent Platformを選びます。SDKのコードはほぼ共通なので、Developer APIで書いたものを後から`enterprise=True`に移すのは難しくありません。ただし、APIの一部機能は片方のバックエンドにしか無く、使えない側で呼ぶとエラーになります。移す前に、使う機能が移行先にあるかを公式ドキュメントで確かめてください。モデルごとの単価は[Gemini 3.1 Proの料金](/tech/details/11077/)や[Gemini 3.8 Flashの差分・料金・移行コード](/tech/details/17704/)で扱っています。SLAの適用範囲やリージョン別単価まで含めた比較は[Vertex AIとGemini APIの違い](https://www.issoh.co.jp/tech/details/18410/)にまとめました。

## 旧google-generativeaiからGen AI SDKへの移行

### サポート終了日と旧ライブラリの現状

公式のライブラリページは、旧ライブラリを「deprecated as of November 30th, 2025」とし、Python・JavaScript/TypeScript・Go・Dart/Flutter・Swift・Androidの6系統すべてを「Not actively maintained」としています。旧ライブラリはLive APIやVeoなどの新機能に対応していません。PyPIの`google-generativeai`は0.8.6（2025年12月16日）、npmの`@google/generative-ai`は0.24.1が最後の版です。

移行先は言語で分かれます。Python・JavaScript・GoはGen AI SDKへ移ります。Dart/Flutter・Swift・Androidの旧SDKは、移行先がFirebase AI Logic（DartはGenkit Dartも可）です。Javaには旧SDKがなかったため移行作業はありません。モバイルの移行先は[Firebase AI Logicの構成とApp Check強制への移行](/tech/details/16693/)で扱っています。

### Pythonのコード対応表

| 処理     | 旧 google-generativeai                  | 新 google-genai                           |
| ------ | -------------------------------------- | ---------------------------------------- |
| import | import google.generativeai as genai    | from google import genai                 |
| 認証     | genai.configure(api\_key=…)            | client = genai.Client()                  |
| 生成     | GenerativeModel(m).generate\_content() | client.models.generate\_content(model=m) |
| チャット   | model.start\_chat()                    | client.chats.create(model=m)             |
| ファイル   | genai.upload\_file()                   | client.files.upload()                    |
| 設定     | genai.GenerationConfig                 | types.GenerateContentConfig              |

差分の大部分は「モデルオブジェクトを作る」から「Clientのメソッドにモデル名を渡す」への書き換えです。旧SDKで`GenerativeModel`の引数に置いていた`system_instruction`は、新SDKでは`GenerateContentConfig`の中に移ります。[公式の移行ガイド](https://ai.google.dev/gemini-api/docs/migrate)のとおり、新SDKは`GEMINI_API_KEY`を自動で読むので、`configure`の呼び出しは不要です。

### 旧SDK移行とInteractions API移行の実施順序

SDKの置き換えとAPIの変更は、別々に実施します。旧SDKの`generate_content`を新SDKの`client.models.generate_content`へ置き換え、テストが通ってから、必要な箇所だけInteractions APIへ移します。いきなりInteractions APIへ書き換えると、旧SDKとの差なのかAPIの差なのか、原因の切り分けができません。Pythonの自動関数呼び出しはInteractions APIの対応までgenerateContent系に残し、SDKが推奨する`chat.send_message`を使います。Batch APIを使う処理も、Interactions APIに対応するまで`generate_content`のままにします。

## JavaScriptでの初期化とブラウザで使うときの注意

Node.js 20以上で`npm install @google/genai@2.27.0`を実行し、APIキーの環境変数を設定します。次のコードを`sample.mjs`として保存し、`node sample.mjs`で実行します。

```
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});  // Node.jsでは GEMINI_API_KEY を読む
const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: "Gen AI SDKを一文で説明して",
});
console.log(interaction.output_text);
```

JavaScript版もPython版と同じ順序で環境変数を読み、`GOOGLE_API_KEY`を優先します。Agent Platformへの切り替えも`enterprise: true`で同じです。上のコードは2.27.0とNode.js 26.5.0で、模擬サーバーに向けて動くことを確かめました。

注意点はブラウザです。型定義の`apiKey`には「Required on browser runtimes」とあり、`project`と`location`はブラウザでは無視されます。ブラウザから直接呼ぶとAPIキーを利用者に配ることになるので、本番のWebアプリでは自前のサーバーを経由させるか、Firebase AI Logicを使います。

## Gen AI SDKを直接使わないほうがよい場面

Gen AI SDKはモデルを呼ぶための層です。次の場面では、別の手段のほうが手戻りが少なくなります。

**エージェントを組む場合**：ツール呼び出しのループ、複数エージェントの連携、デプロイまでを自前で書くなら、Agent Development Kit（ADK）を先に検討します。`google-adk` 2.11.0は`google-genai>=2.19,<3`に依存しており、内部でGen AI SDKを使っています。SDKを直接使うのは、ADKの抽象が合わない部分だけで十分です。ADKの構成は[ADKとは？GoogleのAgent Development Kitの仕組みと始め方](/tech/details/7936/)で扱っています。

**既にOpenAIのライブラリで書いたコードがある場合**：Gemini APIには`https://generativelanguage.googleapis.com/v1beta/openai/`という互換エンドポイントがあり、公式ドキュメントには「3行の変更」で呼べるとあります。複数社のモデルを切り替える既存コードは、まず互換エンドポイントで動かし、Geminiに固有の機能が必要になった箇所だけGen AI SDKへ移すと、SDK依存の書き換え範囲を抑えられます。公式ドキュメント自身も、OpenAIのライブラリを使っていないならGemini APIを直接呼ぶよう勧めています。

**モバイルアプリから直接呼ぶ場合**：前の章のとおり、Firebase AI Logicを使います。

## よくある質問

### Google Gen AI SDKは無料で使えますか？

SDK自体はオープンソースで無料です（PyPIのライセンス表記はApache-2.0）。料金がかかるのは呼び出すAPIのほうです。Gemini Developer APIには無料枠があり、`gemini-3.8-flash`は料金ページで入力・出力ともFree Tierが「Free of charge」です。ただし無料枠のデータは製品改善に使われるため、業務データを送るなら有料枠かAgent Platformにします。

### google-generativeaiは今も動きますか？

インストールはできますが、2025年11月30日にサポートが終わり、公式の状態は「Not actively maintained」です。Live APIやVeoのような新機能には対応していないため、新しいモデルの機能を使うにはGen AI SDKへの移行が必要です。移行は、まず`generate_content`を新SDKの同名メソッドへ置き換えるところから始めると、差分が小さく済みます。

### Gemini APIとは何ですか？SDKとはどう違いますか？

Gemini APIはGoogleの生成AIモデルを呼ぶWeb API（`generativelanguage.googleapis.com`）で、Gen AI SDKはそれをPythonやJavaScriptから呼ぶためのライブラリです。SDKを使わずにRESTを直接呼ぶこともできますが、SDKなら認証ヘッダー、型付きの設定、構造化出力のパース、Agent Platformへの切り替えを同じコードで扱えます。

### Vertex AIとGemini APIのどちらを使えばよいですか？

試作や個人開発ならGemini Developer API、Google CloudのIAMやリージョン指定で統制したい組織はAgent Platform（旧Vertex AI）です。Gen AI SDKでは`enterprise=True`でバックエンドを切り替えられますが、認証・プロジェクト・ロケーションの設定と、移行先のモデル・機能への対応確認が必要です。

### Gen AI SDKのバージョンはどう管理すべきですか？

`requirements.txt`で`google-genai==2.28.*`のようにマイナー版まで固定し、GitHubの`CHANGELOG.md`を読んでから上げます。ADKを併用する場合は、ADKが要求する範囲（2.11.0なら2.19以上3未満）に収まっているかも確かめてください。

## 関連記事

- [Vertex AIとは？Google CloudのAI開発プラットフォームの機能・料金とSageMaker/Azure MLとの違いを実装者目線で解説](/tech/details/15546/)
- [ADKとは？GoogleのAgent Development Kitの仕組みと始め方【2.11対応】](/tech/details/7936/)
- [GoでGemini APIを呼び出す実装手順｜SDKとエンドポイントURL【2026年8月版】](/tech/details/2760/)
- [Gemini 3.8 Flashとは？3.7からの差分・料金・移行コードを実装目線で解説【2026年9月】](/tech/details/17704/)
- [Firebase AI Logicとは｜クライアント直呼びの構成とApp Check強制への移行【2026年8月時点】](/tech/details/16693/)

---

出典: [Google Gen AI SDKとは？google-genaiの導入とAgent Platform切替・旧SDK移行【2026年10月】](<https://www.issoh.co.jp/tech/details/8438/>)（株式会社一創）