Good Bye Vertex AI SDK

approx. 2800 words

13 min

minherz

Last Modified: Aug 16, 2025

If you did not notice, the Generative AI part of Vertex AI SDK is now deprecated. It means that new versions of this SDK will not update generative AI functions and these functions will be completely removed from SDK versions in 2026. You can find more info about it in the deprecation notice.

In 2024, the Generative AI module was introduced to the Vertex AI SDK. The way it was published for different programming languages introduced quite a confusion. For example, in Python a developer had to install the google-cloud-aiplatform package and then to import vertexai while in Go a name of the installed module was cloud.google.com/go/vertexai and the import statement had to import "cloud.google.com/go/vertexai/genai". In 2025, Google released a new GenAI SDK that was called to replace the collection of VertexAI SDKs for different languages. The new SDK has a more intuitive interface that is similar across different programming languages.

After releasing the GenAI SDK the Vertex AI SDK was announced for deprecation. If you use one of the recent Vertex AI SDK versions you will see a deprecation message in your build logs. Google published a comprehensive migration guide from Vertex AI to GenAI SDK. I migrated code in my observability of Gen AI application examples to Gen AI and below you can find a short summary of changes you need to do for the migration. The description addresses the use of SDK for text generation. For guidelines of migrating multi-modal interactions, please see the migration guide.

Migrating from Vertex AI to Gen AI

The migration is composed of the three steps:

Adding Gen AI SDK module (or package) into the project and local environment
Migrate initialization code to use Gen AI SDK
Migrate code that calls inference API to generate content based on a text prompt and to show changes in getting the generated content from the API response.

The following paragraphs show these migration steps for four languages: Go, Java, NodeJS and Python. You can also look at the before and **after** migration code versions of the example application in the four languages (Note: the “after” version includes migration from Google Cloud Trace exporter to OTLP Trace exporter).

Note

As you update dependencies and import statements, and change code your IDE will likely flag unused old imports and variables. It’s often best to make all the code changes first and then use your IDE’s features to ‘organize imports’ or ’tidy up’ the code to resolve these warnings cleanly.

STEP 1: Add Gen AI SDK

This step installs the Gen AI SDK module (or package) to the local environment and updates configuration file(s) where necessary.

Go

Install google.golang.org/genai package.

go get google.golang.org/genai

NOTE: The update of the go.mod file is postponed to Step 3 after code migration is complete.

Java

Update the dependency configuration to use Gen AI SDK. If you use maven then open the pom.xml file and find Vertex AI SDK dependency. The dependency group should look like:

<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-vertexai</artifactId>
    <version>1.16.0</version>
</dependency>

Note that the version can be different. Replace this dependency with the one of the Gen AI SDK:

<dependency>
    <groupId>com.google.genai</groupId>
    <artifactId>google-genai</artifactId>
    <version>1.12.0</version>
</dependency>

Check the repository for the latest available version.

If you use gradle, open the build.gradle file and find Vertex AI SDK dependency. The dependency should be in one of the dependencies{} groups and look like an external library dependancy:

implementation 'com.google.cloud:google-cloud-vertexai:1.16.0'

Replace this dependency with the one of the Gen AI SDK:

implementation 'com.google.genai:google-genai:1.12.0'

Use Kotlin syntax if your project uses Kotlin.

Note

Gen AI SDK implicitly depends on the commons-logging package. If you use Spring framework or another package that utilizes Apache Common Logging, you will see warnings in your build logs informing about multiple versions of the commons-logging package. To resolve these warnings consider updating your dependency configuration by excluding the commons-logging package like below:

<dependency>
    <groupId>com.google.genai</groupId>
    <artifactId>google-genai</artifactId>
    <version>1.12.0</version>
    <exclusions>
        <exclusion>
            <groupId>commons-logging</groupId>
            <artifactId>commons-logging</artifactId>
        </exclusion>
    </exclusions>
</dependency>

The gradle dependency will look like:

implementation 'com.google.genai:google-genai:1.12.0' {
    exclude group: 'commons-logging', module: 'commons-logging'
}

NodeJS

Install the @google/genai module into your local environment.

npm install "@google/genai"

It automatically adds the package to the package.json. Open the package.json and remove the @google-cloud/vertexai package of the Vertex AI SDK. Search for the text “@google-cloud/vertexai" and delete the line that looks like (you may have different version):

"@google-cloud/vertexai": "^1.9.3",

NOTE that you will need to synchronize the package-lock.json file to reflect the changes.

Python

Install the [google-genai](https://pypi.org/project/google-genai/) package into your local environment.

pip install google-genai

Open the requirements.txt and replace the Vertex AI SDK package with the Gen AI SDK package. Search for the text google-cloud-aiplatform and delete the line that looks similar to below (you may have different version expression):

google-cloud-aiplatform==1.59.0

Then add the google-genai dependency by adding a line similar to:

google-genai~=1.0.0

The above example declares dependency on the version 1 of Gen AI SDK with the latest minor and patch versions.

STEP 2: Migrate initialization code to use Gen AI SDK

The migration of the initialization code introduces changes to the way the SDK client is initialized and instantiated and also removes instantiation of the GenAI model object. The new SDK client can be initialized in three different modes:

Gemini API mode that use API key
Vertex AI mode that is linked to specific Google Cloud project and requires location (Google Cloud region)
Vertex AI express mode that use API key

The Gemini API mode lets you use Google’s Gen AI models without having an account on Google Cloud. The Vertex AI mode is for use with workloads that are mainly deployed on Google Cloud and can leverage access to Vertex AI APIs directly. The last mode has been introduced in 2025 and allows you to try out Vertex AI API on Google Cloud without creating a Google Cloud account. Learn more about express mode in documentation.

If your application runs on Google Cloud you can use the Metadata server of your compute platforms (GCE, GKE, Cloud Run ,etc) to retrieve its project ID and region instead of coding it into your application.

Keep in mind that the code will use the model version value in Step 3 instead of the Gen AI model instantiation.

Go

The Vertex AI SDK client initialization code looks very similar to the Gen AI SDK client initialization code.

Vertex AI SDK client initialization:

import "cloud.google.com/go/vertexai/genai"
//...
var client *genai.Client
//...
client, err = genai.NewClient(ctx,"your-project-id","your-region")
defer client.Close()

Gen AI SDK client initialization creates an instance of the genai.Client. The Gemini API mode with API key initialization looks like the following.

import "google.golang.org/genai"
//...
var client *genai.Client
//...
client, err = genai.NewClient(ctx, &genai.ClientConfig{
        API:     "you-gemini-api-key",
        Backend: genai.BackendGeminiAPI,
})

The ctx variable should be set to the current context or initiated using:

ctx := context.Background()

Replace the Vertex AI SDK initialization with one for Gen AI SDK:

Find and replace all import statements of "cloud.google.com/go/vertexai/genai" with "google.golang.org/genai".
Replace SDK initialization code.
Remove calls to the Close() method of the client instance because Gen AI SDK does not require “closing” the client.
Remove code that calls the method GenerativeModel() of the Vertex AI SDK client. Note to keep the model version value.

To initialize Gen AI SDK client to work with Vertex AI use the following call:

import "google.golang.org/genai"
//...
var client *genai.Client
//...
client, err = genai.NewClient(ctx, &genai.ClientConfig{
        Project:  "your-vertex-project-id",
        Location: "your-vertex-region",
        Backend:  genai.BackendVertexAPI,
})

To initialize Gen AI SDK client to work with Vertex AI in express mode using API key use the following call:

import "google.golang.org/genai"
//...
var client *genai.Client
//...
client, err = genai.NewClient(ctx, &genai.ClientConfig{
        API:     "your-vertex-api-key",
        Backend: genai.BackendVertexAPI,
})

You can customize the client using the ClientConfig argument.

To interact with the Metadata server you can use the cloud.google.com/go/compute/metadata package.

Java

Replace the Vertex AI SDK initialization with one for Gen AI SDK.

Vertex AI SDK initialization creates an instance of the com.google.cloud.vertexai.VertexAI class:

var vertexAI = new VertexAI("your-project-id", "your-region");

Gen AI SDK client initialization creates an instance of the com.google.genai.Client class. The Gemini API mode with API key initialization looks like the following.

var client = new Client.builder()
        .apiKey("your-gemini-api-key")
        .vertexAI(false)
        .build();

Replace the Vertex AI SDK initialization with one for Gen AI SDK:

Find and replace import statements of com.google.cloud.vertexai.VertexAI with com.google.genai.Client.
Replace SDK initialization code.
Remove import statements and code that creates instances of com.google.cloud.vertexai.GenerativeModel class. Note to keep the model version value.

To initialize Gen AI SDK client to work with Vertex AI use the following call:

var client = new Client.builder()
        .project("your-vertex-project-id")
        .location("your-vertex-region")
        .vertexAI(true)
        .build();

To initialize Gen AI SDK client to work with Vertex AI in express mode using API key use the following call:

var client = new Client.builder()
        .apiKey("your-vertex-api-key")
        .vertexAI(true)
        .build();

You can customize the client using .httpOptions() and .clientOptions() methods of the Client’s builder.

To interact with the Metadata server you can use the google-cloud-core package.

NodeJS

Replace the Vertex AI SDK initialization with one for Gen AI SDK.

Vertex AI SDK initialization creates an instance of the VertexAI from the "@google-cloud/vertexai" package.

import VertexAI from '@google-cloud/vertexai';
const vertex = new VertexAI({ project: 'your-project-id' });

Gen AI SDK client initialization creates an instance of the GoogleGenAI class from the "@google/genai" package. The Gemini API mode with API key initialization looks like the following.

import { GoogleGenAI } from '@google/genai';
const genAI = new GoogleGenAI({
        apiKey:'your-api-key',
        vertexai: false,
});

Replace the Vertex AI SDK initialization with one for Gen AI SDK:

Find and replace import statements of GoogleGenAI from @google-cloud/vertexai with imports of GoogleGenAI from @google/genai.
Replace SDK initialization code.
Remove code that calls the getGenerativeModel() method of VertexAI instance. Note to keep the model version value.

To initialize Gen AI SDK client to work with Vertex AI use the following call:

const genAI = new GoogleGenAI({
        project: 'your-vertex-project-id',
        location: 'your-vertex-region',
        vertexai: true,
});

To initialize Gen AI SDK client to work with Vertex AI in express mode using API key use the following call:

const genAI = new GoogleGenAI({
        apiKey:'your-vertex-api-key',
        vertexai: true,
});

To interact with the Metadata server you can use the gcp-metadata package.

Python

Replace the Vertex AI SDK initialization with one for Gen AI SDK.

Vertex AI SDK initializes the vertexai module.

import vertexai
vertexai.init(project='your-project-id', location='your-region')

Gen AI SDK client initialization creates an instance of the genai.Client class imported from google package. The Gemini API mode with API key initialization looks like the following.

from google import genai
client = genai.Client(
        api_key='your-gemini-api-key',
        vertexai=False)

Replace the Vertex AI SDK initialization with one for Gen AI SDK:

Find and replace import statements of "import vertexai" with imports of genai from google.
Replace SDK initialization code.
Remove import statements that import GenerativeModel from vertexai.generative_models and code that calls GenerativeModel(). Note to keep the model version value.

To initialize Gen AI SDK client to work with Vertex AI use the following call:

client = genai.Client(
        project='your-vertex-project-id',
        location='your-vertex-region',
        vertexai=True)

To initialize Gen AI SDK client to work with Vertex AI in express mode using API key use the following call:

client = genai.Client(
        api_key='your-vertex-api-key',
        vertexai=True)

You can customize the client usig the http_options parameter in the call to genai.Client().

To interact with the Metadata server you will need to implement a custom HTTP GET request following documentation.

STEP 3: Migrate content generation code

The content generation using Gen AI SDK looks similar (uses the method with the same name). The changes are in the arguments of the method and the way to retrieve the generated text from the response. The content generation using Gen AI SDK allows a caller to define the model version and set up additional parameters for the content generation such as system instructions, a creativity level and safety constraints.

Go

Replace the call to GenerateContent() method of the model with the call to Gen AI SDK client’s method. The new method call looks like the following:

res, err := client.Models.GenerateContent(
        ctx,
        modelName,
        genai.Text(prompt),
        nil)
if err != nil {
    // do error handling
}
return res.Text()

The ctx variable should be set to the current context or initiated using:

ctx := context.Background()

The modelName should have the valid model version. Consider using the same value that was used in the call to the GenerativeModel() method.

The prompt variable is a string prompt for the model.

Use an instance of the GenerateContentConfig to adjust default configuration. For example, the following call sets the “temperature” of the response to 0.75:

res, _ := client.Models.GenerateContent(
        ctx,
        modelName,
        genai.Text(prompt),
        &genai.GenerateContentConfig{
            Temperature: genai.Ptr[float32](0.75)
        },
)

After all code modifications, update the go.mod file by running the following command:

go mod tidy

Java

Replace the call to GenerateContent() method of the model with the call to Gen AI SDK client’s method. The new method call looks like the following:

var res = client.models.generateContent(model, prompt, null);
return res.text();

The modelName should have the valid model version. Consider using the same value that was used in the call to the GenerativeModel() method.

The prompt variable is a string prompt for the model.

Use an instance of the GenerateContentConfig to adjust default configuration. For example, the following call sets the “temperature” of the response to 0.75:

import com.google.genai.types.GenerateContentConfig;
//...
var cfg = new GenerateContentConfig.builder()
        .temperature(0.75f)
        .build();
var res = client.models.generateContent(model, prompt, cfg);

NodeJS

Replace the call to generateContent() method of the model with the call to Gen AI SDK client’s method. The new method call looks like the following:

const resp = await genAI.models.generateContent({
        model: modelName,
        contents: prompt,
});
return resp.text;

The modelName should have the valid model version. Consider using the same value that was used in the call to the getGenerativeModel() method.

The prompt variable is a string prompt for the model.

Use an instance of the GenerateContentConfig to adjust default configuration. For example, the following call sets the “temperature” of the response to 0.75:

const resp = await genAI.models.generateContent({
        model: modelName,
        contents: prompt,
        config: {
            temperature: 0.75,
        },
});

Python

Replace the call to generate_content() method of the model with the call to Gen AI SDK client’s method. The new method call looks like the following:

response = client.models.generate_content(
        model=modelName,
        contents=prompt)
return response.text

The modelName should have the valid model version. Consider using the same value that was used in the call to the GenerativeModel() method.

The prompt variable is a string prompt for the model.

Use an instance of the GenerateContentConfig to adjust default configuration. For example, the following call sets the “temperature” of the response to 0.75:

from google.genai import types
# ...
response = client.models.generate_content(
        model=modelName,
        contents=prompt,
        config=types.GenerateContentConfig(
            temperature=0.75))

Error handling

Error handling is implemented using language-specific syntax. There are collections of error types that you can choose to handle to differentiate between errors returned by SDK from other types of the errors.

Go

Use the genai.APIError type.

import "errors"
//...
client, err = genai.NewClient(ctx, &genai.ClientConfig{
        API:     "you-gemini-api-key",
        Backend: genai.BackendGeminiAPI,
})
if err != nil {
    var apiErr *genai.APIError
    if errors.as(err, &apiErr) {
        // handle SDK error
    }
}

Java

Use the classes in the genai.errors namespace.

import com.google.genai.errors.*;
//...
try {
    var client = new Client.builder()
            .apiKey("your-gemini-api-key")
            .vertexAI(false)
            .build();
} catch (BaseException ex) {
    // handle SDK error
}

The namespace includes ApiException and other classes to support gradual error handling. The above example uses a “catch all” pattern. A further processing of the exception type is recommended to identify a specific error case.

NodeJS

Use the ApiError class.

import '@google/genai/errors';
//...
try {
    const genAI = new GoogleGenAI({
            apiKey:'your-api-key',
            vertexai: false,
    });
} catch (error) {
    if (error instanceof errors.ApiError) {
        // handle SDK error
    }
}

Python

Use the APIError class.

from google.genai import errors
//...
try:
    client = genai.Client(
            api_key='your-gemini-api-key',
            vertexai=False)
except errors.APIError as e:
    // handle SDK error

Summary

Migrating from Vertex AI SDK to Gen AI SDK is a straightforward process. Using the above instructions and falling back to the comprehensive guide in documentation, you should be able to migrate your code quickly with a little or no delay.

Migrating to Gen AI SDK gives you many benefits including:

Homogenous interface across different programming languages
Support of three different models of working with Gen AI in Google Cloud (Gemini, Vertex and express mode)
Use of the latest version of Gen AI SDK
Access to more features (e.g. customize safety settings at inference level)

There are a lot of resources available about the Gen AI SDK, Vertex, Gemini and migration. Here are a few to begin with:

Old and new versions of the AI application from Observability for AI Developers example in four languages (Go, Java, NodeJS and Python) (and also the diff)
Migrate to the Google GenAI SDK documentation
Generative AI beginner’s guide
Google Gen AI SDK documentation