Google’s Gen AI Python SDK 3.0 Changes Three Defaults. Check Before You Upgrade

A library can change without your application changing a line—and still alter what endpoint it calls, which transport is installed, or the shape of a value your code reads. Google’s Gen AI Python SDK 3.0.0 makes all three possibilities concrete. If your service calls Gemini through the Developer API, relies on httpx, or consumes CodeExecutionResultStep.result, this is a migration to review rather than a routine patch. ^[1]

One major version, three separate contracts

The first breaking change is the default Gemini Developer API version. Version 3.0 uses v1 where earlier releases defaulted to v1beta. The release notes explicitly say the default change does not affect Gemini Enterprise / Vertex AI clients, which continue to use v1beta1. That distinction matters: “Gemini API” is not one uniform endpoint contract, and a team can have both client types in the same codebase. ^[1]

Google supports an explicit api_version in HttpOptions and a GOOGLE_GENAI_API_VERSION environment variable. An explicit code setting takes precedence, according to the release notes. This creates a useful migration choice: if your application depends on a particular API surface, state that dependency rather than inheriting a default that may shift in a future upgrade. ^{[1] [2]}

The second change is transport. The package now installs and selects httpx2 by default; httpx is no longer installed unless the optional extra is requested. A simple import alias may be enough for ordinary code, but transport-specific types are not interchangeable. Timeout, connection-pool, mock-transport and authentication objects must match the active client implementation. ^[1]

The third change is a response type. CodeExecutionResultStep.result is no longer always a string; it is a union that can represent multimodal content. Code that assumes result.strip() or logs the value as plain text should branch on the actual variant first. Text-only JSON remains unchanged, but that does not mean every result can be handled as text. ^[1]

The migration checklist that catches the real risk

Start by identifying which service your client targets. Search for vertexai, enterprise, project/location settings, and explicit API-version values. Then inspect how the client is constructed in each environment: a local developer shell, a container image and a production deployment can resolve optional dependencies differently.

Next, search for direct imports of httpx, custom client instances, mock transports, exception classes and HttpOptions transport arguments. A test suite that only mocks the SDK’s public method may not reveal that your production code catches an exception type from the old HTTP library. Test timeouts, retries, TLS and connection cleanup through the configuration you actually ship. The SDK documentation also recommends closing synchronous and asynchronous clients so their underlying connections are released. ^[2]

Finally, enumerate every use of CodeExecutionResultStep.result. Parse by type, decide which variants your product supports, and make unsupported variants produce an intentional error or visible fallback. Keep a regression fixture for text-only output and add one for the structured result your application expects. The task is not to anticipate every possible multimodal payload; it is to stop treating a value with a declared union type as a string by accident. ^[1]

Test the contract, not just the import

A practical upgrade test has at least three layers. A client-level test verifies which API version is selected for each provider mode. A transport test confirms the intended client and exception handling are active. An application test verifies response parsing and user-visible behavior for the result variants the product consumes.

Run those checks with the exact pinned dependency set and environment variables used in deployment. If you cannot upgrade immediately, pin a compatible range and document the reason; do not rely on an unbounded dependency that could move production across the same boundary later. Google’s repository warns users who need to avoid the major-version changes to stay below 3.0, while the release notes document explicit configuration options for teams that need to retain the previous API and HTTP defaults. ^{[1] [2]}

That is the larger lesson in a fast-moving model SDK: version numbers are only a signal to inspect the contract. Your application’s assumptions live in endpoint selection, transport behavior, response shapes and the dependencies that happen to be installed. Write those assumptions down, test them, and an upgrade becomes a controlled change instead of an outage disguised as a package update.

For related context, see our guide to date-pinned API contracts in Google Compute Engine and streaming responses through an API gateway.