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

> Migrate from google-cloud-aiplatform to google-genai SDK easily. Follow this guide to update your environment and code for seamless Gemini integration.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: migration-guide
- Published: 2026-06-11

---

**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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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.

```bash

# 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.

```bash
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.

```python

# 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.

```python
client = genai.Client()

```

### 5. Update Model Calls

Replace Vertex AI resource paths with short model names.

```python
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

```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

```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

```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

```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

```csharp
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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/skills/cloud/gemini-api/SKILL.md) and [`skills/cloud/gemini-interactions-api/SKILL.md`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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`](https://github.com/google/skills/blob/main/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.