How to Migrate from google-cloud-aiplatform to google-genai SDK: A Complete Guide

To migrate from google-cloud-aiplatform to the google-genai SDK, uninstall the legacy package, install google-genai, set the GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, and GOOGLE_GENAI_USE_ENTERPRISE environment variables, then replace from google.cloud import aiplatform with from google import genai and initialize the client with genai.Client() using short model names like gemini-3.5-flash.

The google-cloud-aiplatform SDK is deprecated for Gemini interactions, and Google now recommends the unified google-genai SDK as the single client library for all Gemini Enterprise Agent Platform features. According to the google/skills repository documentation, this migration ensures access to the latest model releases, security updates, and enterprise-grade IAM integration. Whether you are maintaining Python scripts or multi-language applications, understanding how to migrate from google-cloud-aiplatform to google-genai SDK is essential for continued support.

Why Migrate from google-cloud-aiplatform to google-genai SDK

The legacy Vertex AI SDKs—including google-cloud-aiplatform, @google-cloud/vertexai, and google-generativeai—are deprecated and no longer supported for Gemini interactions according to skills/cloud/gemini-api/SKILL.md. The new Google Gen AI SDK (google-genai for Python, @google/genai for JavaScript/TypeScript, and language-specific equivalents) provides a unified client library that consolidates all Gemini Enterprise Agent Platform features into a single package.

Using the unified SDK ensures you receive the latest model releases, automatic security updates, and seamless enterprise-grade IAM integration. As documented in skills/cloud/agent-platform-migrate-from-ai-studio/SKILL.md, the migration unlocks full support for multimodal inputs, function calling, embeddings, live streaming, batch prediction, caching, and tuning without requiring additional service-specific code.

Key Differences Between Legacy and New SDKs

Understanding the architectural changes between the legacy and new SDKs helps streamline your migration.

Package and Import Structure

• Legacy: google-cloud-aiplatform with import from google.cloud import aiplatform
• New: google-genai with import from google import genai

Client Initialization

• Legacy: Required explicit aiplatform.init(...) calls followed by aiplatform.PredictionServiceClient() instantiation
• New: Simple client = genai.Client() with no arguments required, automatically reading environment configuration

Environment Variable Handling

• Legacy: Required explicit passing of project/region parameters or reliance on Application Default Credentials (ADC) with GOOGLE_APPLICATION_CREDENTIALS
• New: Automatically reads GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, and GOOGLE_GENAI_USE_ENTERPRISE=true as documented in skills/cloud/gemini-api/SKILL.md

Model Identifiers

• Legacy: Required full Vertex AI resource names (e.g., projects/<proj>/locations/<loc>/publishers/google/models/<model>)
• New: Uses short Gemini model strings such as gemini-3.5-flash as specified in skills/cloud/gemini-api/SKILL.md

Feature Coverage

• Legacy: Limited to text generation with additional work required for multimodal or streaming capabilities
• New: Full native support for multimodal inputs, function calling, streaming, and enterprise features out-of-the-box

Step-by-Step Migration Guide

Follow these steps to transition your codebase from the deprecated google-cloud-aiplatform to the google-genai SDK.

1. Update Dependencies

Remove the legacy package and install the new unified SDK.

# Remove the old package (optional)

pip uninstall google-cloud-aiplatform

# Install the new unified SDK

pip install google-genai   # Python

npm install @google/genai   # JavaScript/TypeScript

go get google.golang.org/genai   # Go

dotnet add package Google.GenAI   # C#

2. Configure Environment Variables

Set the required environment variables that the new client automatically reads.

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="global"   # or a specific region

export GOOGLE_GENAI_USE_ENTERPRISE=true

3. Update Import Statements

Replace the legacy import with the new SDK import.

# Old

from google.cloud import aiplatform

# New

from google import genai

4. Initialize the Client

Create the client without arguments; it pulls credentials from environment variables or ADC.

client = genai.Client()

5. Update Model Calls

Replace Vertex AI resource paths with short model names.

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Explain quantum computing"
)
print(response.text)

6. Migrate Configuration Parameters

Update any generation parameters by passing them within a generation_config object if fine-grained control is needed, as the parameter names remain consistent with the legacy SDK.

7. Validate the Migration

Test the migration by running a simple generate_content call. If successful, your code now fully utilizes the new SDK.

Language-Specific Implementation Examples

The google/skills repository provides implementation patterns for multiple languages. All examples assume the environment variables above are configured.

Python

from google import genai

# Client picks up env vars automatically

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Write a short poem about sunrise."
)

print(response.text)

JavaScript / TypeScript

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

const ai = new GoogleGenAI({
  enterprise: {
    project: "YOUR_PROJECT_ID",
    location: "global",
  },
});

const resp = await ai.models.generateContent({
  model: "gemini-3.5-flash",
  contents: "Write a short poem about sunrise.",
});

console.log(resp.text);

Go

package main

import (
	"context"
	"fmt"
	"log"

	"google.golang.org/genai"
)

func main() {
	ctx := context.Background()
	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		Backend:  genai.BackendVertexAI,
		Project:  "YOUR_PROJECT_ID",
		Location: "global",
	})
	if err != nil {
		log.Fatal(err)
	}
	resp, err := client.Models.GenerateContent(
		ctx,
		"gemini-3.5-flash",
		genai.Text("Write a short poem about sunrise."),
		nil,
	)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(resp.Text)
}

Java

import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

public class GeminiDemo {
  public static void main(String[] args) {
    Client client = Client.builder()
        .enterprise(true)
        .project("YOUR_PROJECT_ID")
        .location("global")
        .build();

    GenerateContentResponse resp = client.models.generateContent(
        "gemini-3.5-flash",
        "Write a short poem about sunrise.",
        null);

    System.out.println(resp.text());
  }
}

C# / .NET

using Google.GenAI;

var client = new Client(
    project: "YOUR_PROJECT_ID",
    location: "global",
    enterprise: true
);

var response = await client.Models.GenerateContent(
    "gemini-3.5-flash",
    "Write a short poem about sunrise."
);

Console.WriteLine(response.Text);

Enterprise Architecture Notes

The Gen AI SDK abstracts the underlying Vertex AI REST endpoint (aiplatform.googleapis.com) and automatically adds the enterprise=true flag when GOOGLE_GENAI_USE_ENTERPRISE is set. This abstraction means that all Gemini Enterprise capabilities—including multimodal processing, streaming responses, and safety filters—become available without service-specific implementation code.

According to skills/cloud/agent-platform-migrate-from-ai-studio/SKILL.md, the SDK centralizes IAM handling through Application Default Credentials, respecting the roles/aiplatform.user role for service account authentication.

Summary

• The google-cloud-aiplatform SDK is deprecated for Gemini use; migrate to google-genai for continued support and security updates.
• Install google-genai and set GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, and GOOGLE_GENAI_USE_ENTERPRISE=true environment variables.
• Replace from google.cloud import aiplatform with from google import genai and initialize with genai.Client().
• Use short model identifiers like gemini-3.5-flash instead of full Vertex AI resource paths.
• The unified SDK provides native support for multimodal inputs, function calling, streaming, and batch prediction without additional configuration.

Frequently Asked Questions

Is google-cloud-aiplatform completely deprecated or just for Gemini?

The google-cloud-aiplatform package is specifically deprecated for Gemini interactions and any Enterprise Agent Platform features. According to skills/cloud/gemini-api/SKILL.md and skills/cloud/gemini-interactions-api/SKILL.md, Google marks these legacy SDKs as DO NOT USE for Gemini development, though the package may still support other Vertex AI functionalities. For all Gemini-related development, you must migrate to google-genai.

Do I need to change my IAM roles when migrating to google-genai?

No, your existing IAM configuration remains compatible. The google-genai SDK respects the standard roles/aiplatform.user role and utilizes Application Default Credentials (ADC) just like the legacy SDK. As documented in skills/cloud/agent-platform-migrate-from-ai-studio/SKILL.md, service account authentication works out-of-the-box without requiring permission changes.

Can I use the same model names when switching to the new SDK?

No, you must update your model identifiers. The legacy SDK required full Vertex AI resource paths (e.g., projects/<proj>/locations/<loc>/publishers/google/models/<model>), while the google-genai SDK uses short strings like gemini-3.5-flash. This simplification is documented in skills/cloud/gemini-api/SKILL.md and reduces boilerplate code in your applications.

What happens if I don't set GOOGLE_GENAI_USE_ENTERPRISE?

Without setting GOOGLE_GENAI_USE_ENTERPRISE=true, the client may not activate enterprise-specific features or endpoints required for the Gemini Enterprise Agent Platform. The environment variable ensures the SDK automatically appends the enterprise=true flag to API requests and accesses the correct Vertex AI backend infrastructure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}