python-aiplatform: evaluating models and shipping ADK agents from a renamed SDK

The SDK changed its product name faster than its import path

The distribution on PyPI is still named google-cloud-aiplatform, and setup.py still describes it as the "Vertex AI API client library". The README now heads itself "Google Gemini Enterprise Agent Platform SDK for Python" and carries a note that the platform "was formerly known as Vertex AI". So the code you import is vertexai, the product you read about has a new name, and the two have not converged yet.

The rename is not only cosmetic. It also warns that the agent_engines module will be rebranded as runtimes in an upcoming major release, and that the sandboxes, sessions and memory_banks modules will move directly under the top-level client object. It spells out the mapping: client.agent_engines.sandboxes becomes client.sandboxes, client.agent_engines.sandboxes.snapshots becomes client.sandboxes.snapshots, client.agent_engines.sessions.events becomes client.sessions.events, client.agent_engines.runtimes.revisions becomes client.runtimes.revisions, and client.agent_engines.memories becomes client.memory_banks. Code written against the old paths will keep working for now, then break on a major bump. The advice given for anyone who wants to avoid unexpected updates is to pin the SDK version to < 2.0.0, which is a blunt instrument for a package whose recent releases are all in the 2.x line.

Two install commands and a client that demands a project and a location

Installation is unremarkable, which is a good sign for a client library that most teams will pull into an existing virtual environment. The README gives a plain pip command and a uv variant for the same distribution:

pip install google-cloud-aiplatform
uv pip install google-cloud-aiplatform

The first real use is a client object that needs two arguments before anything else happens:

import vertexai
from vertexai import types

# Instantiate GenAI client from Vertex SDK
# Replace with your project ID and location
client = vertexai.Client(project='my-project', location='us-central1')

The project identifier and the location are positional to the point of being structural: the client is bound to one Google Cloud project in one region, and the example values are placeholders you are told to replace. Note what the example does not contain. There is no credential setup, no service account instruction, no environment variable, and no mention of Application Default Credentials. If your environment already authenticates to Google Cloud, that is an invisible dependency of this tutorial. If it does not, the install page gives you nothing to go on, and you will need the product documentation for the platform rather than the SDK page.

Evaluation is a two-pass contract, not a single call

The evaluation story in the SDK is the clearest part of the documented surface, and it is split into two calls that you chain. The first generates model responses from a set of prompts, and the second scores those responses against metrics you name.

inference_results = client.evals.run_inference(
    model="gemini-2.5-flash-preview-05-20",
    src=prompts_df
)

The src argument is a pandas DataFrame with a prompt column and a reference column, and the example fills in four prompts with their expected answers. The second call takes those results and a list of metrics:

eval_result = client.evals.evaluate(
    dataset=inference_results,
    metrics=[
        types.Metric(name='exact_match'),
        types.Metric(name='rouge_l_sum'),
        types.RubricMetric.TEXT_QUALITY,
    ]
)

The list mixes two styles: string-named metrics such as exact_match and rouge_l_sum, and a rubric constant, types.RubricMetric.TEXT_QUALITY. That is a useful signal about the design, since a rubric metric and a lexical overlap metric are evaluated by different machinery behind the same call. The pandas dependency is not optional either, since setup.py lists a metadata extra that pulls pandas >= 1.0.0 and numpy >= 1.15.0. Two details deserve a second look before you build a pipeline on this: the model identifier in the example carries a preview suffix, and the split between inference and evaluation means a scoring run always costs a generation run unless you keep the results object around.

AdkApp is the seam between a local agent and a managed runtime

Agent work in this SDK is built around Agent Development Kit agents wrapped in an AdkApp object. You write a plain Python function as a tool, then hand it to an Agent along with a model and a name:

from google.adk.agents import Agent
from vertexai.agent_engines import AdkApp

app = AdkApp(agent=Agent(
    model="gemini-3.5-flash",        # Required.
    name='currency_exchange_agent',  # Required.
    tools=[get_exchange_rate],       # Optional.
))

The comments in that sample are worth reading, because the required and optional fields are marked inline. With the app in hand you can stream a query locally before any remote resource is involved:

async for event in app.async_stream_query(
    user_id="user-id",
    message="What is the exchange rate from US dollars to SEK today?",
):
    print(event)

The tool in the example calls a public exchange rate API over plain requests, so the tool boundary is ordinary Python and the agent is the part that talks to the platform. Deployment then goes through client.agent_engines.create, and the sample line for it is cut off mid-call, so the exact arguments are not visible here. What the example does say, in a comment of its own, is to replace that call with client.runtimes.create in a future major release. The local streaming path is therefore the part you can actually verify from the documentation today.

Most of the repository is generated client surface

The top-level layout explains what kind of project this is. Alongside the usual scaffolding, which includes setup.py, noxfile.py, mypy.ini, .flake8, .coveragerc, a pre-commit config and a .kokoro directory, there are three large package trees: google/, vertexai/ and agentplatform/. setup.py collects every package whose name starts with google, vertexai or agentplatform, and separately relocates the vertex_ray packages so they can be imported as a top-level name. The version is not hardcoded in setup.py at all; it is read out of google/cloud/aiplatform/version.py at build time.

The optional dependency groups are narrow and tell you what the extra features cost you. A profiler extra pulls tensorboard-plugin-profile with the range >= 2.4.0, < 2.18.0, and werkzeug with the range >= 2.0.0, < 4.0.0, and the metadata extra mentioned earlier carries pandas and numpy. Behind the generated surface sit a tests/ directory, an sdk_schema_tests/ directory and a testing/ directory, plus a samples/ tree that includes model-builder and snippets subdirectories and a generated_samples directory.

Automation is visible in the root: release-please-config.json with a matching manifest, renovate.json for dependency updates, and owlbot.py, which is the script that generated code usually arrives through. That combination means the hand-written part of the repository is the vertexai/ layer and the samples, while the google/ tree is regenerated on a schedule.

Where the documentation runs out: credentials, versions, rollback

Several gaps matter for anyone deciding whether to adopt this package. Authentication is the largest one. The tutorial creates a client with a project and a location and nothing else, so the credentials path is assumed rather than shown, and a reader with a fresh service account and no ambient Google Cloud login has to go elsewhere to find out how the client authenticates.

Version handling is the second. The evaluation example uses gemini-2.5-flash-preview-05-20 while the ADK example uses gemini-3.5-flash, so two different naming shapes appear in adjacent sections, one of them a preview build. The rebrand warning adds a third axis of instability, and the SDK does not document a compatibility window for the client.agent_engines paths, nor a rollback procedure. The CHANGELOG.md file exists at the repository root, but the SDK page gives no guidance on reading it or on what a major bump will remove beyond the table of moved modules.

Practical consequence: teams that want predictable behaviour have to pin, and the only pinning advice given is to stay below version 2.0.0. Whether that is a reasonable trade depends on whether you want the evaluation helpers and the ADK wrapper more than you want a stable import path.

Two routes that do not need the SDK client at all

The obvious alternative is to skip the client layer and call the platform over its HTTP API with the standard library or your own HTTP library. The trade is straightforward. What you lose is everything the SDK packages for you: the client object that binds a project and a location in one line, the evals helpers that chain run_inference and evaluate, the types module with named metrics and rubric constants, and the AdkApp wrapper that turns an ADK agent into something you can stream and then deploy. What you gain is a dependency you do not have to pin, and no exposure to the client.agent_engines rename at all, since you never touch the client object. For a project that needs a single endpoint, that is often the cheaper end of the trade.

The second alternative is at the agent layer rather than the API layer. An ADK agent is an ordinary object, and AdkApp.async_stream_query shows it being driven in process. You can host such an agent yourself and talk to it over your own service, which keeps the runtime and its scaling outside the platform, but you give up the managed runtime that the deployment path exists to provide, along with the revisions and snapshots visible in the module mapping. The choice is not SDK versus no SDK so much as managed runtime versus your own infrastructure, and the SDK sits on one side of it.

A fast release cadence and an Apache-2.0 licence

Activity is not in question here. The last push to the repository was on 2026-10-20, and three tagged releases landed in the three weeks before it: v2.3.0 on 2026-09-30, v2.4.0 on 2026-10-07 and v2.5.0 on 2026-10-14. Minor versions a week apart, on top of a major line that is already past 2.0, means an upgrade cadence you should plan for rather than something you set up once.

The licence field on the repository says Apache-2.0, and setup.py carries the standard Apache 2.0 header. In practical terms that lets you modify the SDK and redistribute it, subject to the notice and licence conditions, and it carries no warranty. This is not legal advice, and it does not extend to the platform you are calling: the Google Cloud service, the models you invoke and the data you send are governed by their own terms, which are outside this repository. The same caution applies to the optional dependencies, since pandas, numpy, werkzeug and tensorboard-plugin-profile each ship under their own licences.

For a team deciding on the package itself, the licence is the least interesting part. The interesting part is that the same activity that keeps the evaluation helpers current is what makes the rename and the weekly releases a planning problem.

Editorial conclusion

Adopt python-aiplatform if your team already runs on Google Cloud and wants evaluation, ADK agents and managed agent runtimes behind one installed client object. Do not adopt it for a one-off HTTP call, and do not start on version 2.x without reading the rename table, because client.agent_engines, client.agent_engines.sandboxes, client.agent_engines.sessions and client.agent_engines.memories all change path in the next major release. Before you commit, check three things: the pin you will set, the model identifier you pass to run_inference, and the credentials setup your environment supplies, none of which the SDK page spells out. The licence field on the repository says Apache-2.0, so the code can be vendored, but the trademark and service terms of the platform are a separate matter.

Frequently asked questions

Official sources

1. googleapis/python-aiplatform on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases