Google Gen AI Python migration: packages, clients and system instructions

Migrate older Gemini and Vertex examples to google-genai: Python requirements, separate API backends, current system instructions, LangChain integration and an offline-checked configuration example.

Published 2026-10-25 · AI-assisted Ithy editorial. Primary references checked 2026-10-25. Original examples are labeled; this is not a named human expert review.

If a Gemini tutorial imports google.generativeai or vertexai.generative_models, first identify which SDK generation it describes. The maintained Google Gen AI Python package is google-genai, imported with from google import genai. It supports both the Gemini Developer API and Google Cloud’s Gemini interface. Credentials, project configuration and model availability still depend on the backend you choose.

This guide was source-checked on October 25, 2026. The package version checked was google-genai 2.33.0, which requires Python 3.10 or newer. Examples use a model ID supplied by the reader instead of embedding a model name that may retire. Configuration and Python syntax were checked offline; this is not a claim of successful paid API execution.

Identify the library before changing code

Pattern in an older exampleWhat to check now
pip install google-generativeaiThe legacy Gemini Developer API library. Google’s migration guide recommends the Google Gen AI SDK.
import google.generativeai as genaiThe older module layout. Current examples use from google import genai.
from vertexai.generative_models import GenerativeModelThe deprecated generative module in the Vertex AI SDK; later SDK releases omit it.
genai.Client(...) and client.models.generate_content(...)The current client-based SDK shape. Confirm the installed version and selected backend.

Google’s Vertex SDK migration guide states that the old generative modules are absent from SDK releases after June 24, 2026. This is a migration of those modules, not a statement that every feature in google-cloud-aiplatform has disappeared. The separate Gemini migration guide covers the Developer API’s older libraries.

Start with a clean environment

Check the Python interpreter and package in the same environment that runs your program. A successful install in one virtual environment will not repair a different interpreter selected by an editor or notebook.

python --version
python -m venv .venv
# Activate the environment using the command for your shell.
python -m pip install "google-genai==2.33.0"
python -m pip show google-genai

The version pin records the version checked for this example; it is not an instruction to ignore future security or compatibility updates. Review the current release notes before upgrading. Avoid naming your own file google.py or genai.py when diagnosing an import problem: local files can obscure the package you intended to import.

Choose the backend explicitly

The official SDK documentation describes both client modes. For the Developer API, use the credential appropriate to that API. For Google Cloud, configure the project, location, enabled service and authorized identity appropriate to your deployment. Do not copy a project or credential from an unrelated account simply because an example needs one.

import os
from google import genai

def developer_client():
    return genai.Client(api_key=os.environ["GEMINI_API_KEY"])

def cloud_client():
    return genai.Client(
        vertexai=True,
        project=os.environ["GOOGLE_CLOUD_PROJECT"],
        location=os.environ["GOOGLE_CLOUD_LOCATION"],
    )

The Cloud client uses the authentication supported by the SDK and environment. A development login, a deployed service identity and a downloaded service-account key are different mechanisms. A tutorial should not tell every reader to create an administrator key as a prerequisite for a text-generation example. Grant the access required for the actual workload and follow the provider’s authentication documentation.

Pass system instructions in generation configuration

With the current Python SDK, system instructions belong in GenerateContentConfig.system_instruction. They are separate from the user’s question. Putting a made-up role="system" into an ordinary content item is not a substitute for using the documented configuration field.

import os
from google.genai import types

def ask(client, question):
    config = types.GenerateContentConfig(
        system_instruction=(
            "Explain the answer clearly. State missing information. "
            "Do not claim that an example was tested."
        ),
        max_output_tokens=512,
    )
    result = client.models.generate_content(
        model=os.environ["GEMINI_MODEL"],
        contents=question,
        config=config,
    )
    return result.text

Set GEMINI_MODEL to a model that your chosen backend currently offers for this operation. The function makes a real, potentially billable request when called. The configuration object alone does not perform a request. Keep the system instruction on every independent call that needs it; do not assume that a previous unrelated request changed the model permanently.

Instructions influence behavior; they do not establish that an answer is factually correct, authorized or safe to execute. For application rules, also validate outputs and enforce permissions in application code. A prompt that says “use only approved data” is not an access-control boundary.

To check that local boundary first, download the Ithy offline configuration check. It imports the pinned SDK, constructs a client with a deliberately invalid example key and validates generation and Live configuration objects while blocking network connections. We ran that check with version 2.33.0. It checks no real credential and makes no model request; successful authentication and output still require a separate authorized test.

Using LangChain: check the integration version too

LangChain’s current ChatGoogleGenerativeAI documentation says that version 4.0.0 moved its integration to the consolidated Google Gen AI SDK and supports the Developer API and the Google Cloud backend. It supersedes certain Gemini classes in langchain-google-vertexai. That statement does not imply that all older integrations or every Cloud model share one migration path.

import os
from langchain_google_genai import ChatGoogleGenerativeAI

model = ChatGoogleGenerativeAI(model=os.environ["GEMINI_MODEL"])
reply = model.invoke([
    ("system", "Explain the result and identify missing information."),
    ("human", "What information would you need to compare two laptops?"),
])

This is the wrapper’s message interface, rather than a claim that the underlying SDK accepts an arbitrary system-role content object. Configure the backend and credentials according to the integration version you actually install. The original SDK example above and the wrapper example are alternatives; stacking two clients is unnecessary for a single request.

Diagnose a failure by its boundary

SymptomFirst checkWhat it does not establish
Import failsInterpreter, installed distribution and local module names.That the remote API or your account is unavailable.
A field is rejectedSDK version and the documented configuration type.That changing the wording of the user prompt will fix the schema.
Authentication or permission errorSelected backend, identity, project and allowed operation.That a different model name will grant access.
Model not found or unsupported operationThe provider’s current model availability for that backend and method.That a model with a similar name supports the same method.
The answer ignores an instructionThe submitted configuration and the model’s actual output.That a system instruction is an enforceable guarantee.

Keep a minimal reproduction with synthetic input. Record the package version, backend, operation and error category. Remove keys, authorization headers, private prompts and customer data before sharing it. Reproduce the failing boundary before changing several dependencies at once.

A migration checklist you can actually verify

  1. Identify the old import and installed package.
  2. Select one backend and confirm an appropriate model is available.
  3. Move request configuration into the documented current type.
  4. Test imports and configuration construction independently from a network call.
  5. Run a small authorized request in your own environment and inspect its output.
  6. Test streaming, tools or structured output separately if your application uses them.

A successful text example does not prove that streaming, function calling, safety settings or Live API sessions work in the same application. The Live API guide explains the separate authentication, audio and connection boundaries.

For a correction, send the specific claim and a supporting source through Ithy Help. Research methodology · More research guides.