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の最小コードで扱っています。

バックエンドは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との違いで扱っています。

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

版番号と日付はPyPI・npm・Goモジュールプロキシ・Maven Central・NuGetのレジストリを直接引いて確かめました（日付はUTC）。動作要件は、PyPIのメタデータがPython 3.10以上、npmのenginesがNode.js 20以上です。公式のライブラリページは本文で「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を呼び出す実装手順にまとめています。

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の概要ページは、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側へ送られるためです。

公式ドキュメントの初期化例は、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の料金やGemini 3.8 Flashの差分・料金・移行コードで扱っています。SLAの適用範囲やリージョン別単価まで含めた比較はVertex AIとGemini APIの違いにまとめました。

旧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強制への移行で扱っています。

Pythonのコード対応表

差分の大部分は「モデルオブジェクトを作る」から「Clientのメソッドにモデル名を渡す」への書き換えです。旧SDKでGenerativeModelの引数に置いていたsystem_instructionは、新SDKではGenerateContentConfigの中に移ります。公式の移行ガイドのとおり、新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/[email protected]を実行し、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の仕組みと始め方で扱っています。

既に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との違いを実装者目線で解説
• ADKとは？GoogleのAgent Development Kitの仕組みと始め方【2.11対応】
• GoでGemini APIを呼び出す実装手順｜SDKとエンドポイントURL【2026年8月版】
• Gemini 3.8 Flashとは？3.7からの差分・料金・移行コードを実装目線で解説【2026年9月】
• Firebase AI Logicとは｜クライアント直呼びの構成とApp Check強制への移行【2026年8月時点】