Three Pitfalls We Encountered When Migrating from vertexai.rag to agentplatform

Introduction

One day, while locally developing a Google Chat bot, I got this warning:

UserWarning: The `vertexai.rag` module is deprecated and will be removed in a future version.
Please migrate to the `agentplatform` client.

vertexai.rag is deprecated? The official documentation says nothing about it. But the warning was added in google-cloud-aiplatform >= 1.160.0. I didn't want to ignore it and suddenly have things break, so I decided to migrate.

To cut to the chase, the API rewrite itself was straightforward, but there were 3 undocumented pitfalls. In this article, I'll share the issues I actually ran into and how I dealt with them.

Prerequisites & Environment

• google-cloud-aiplatform: 1.156.0 → upgraded to 1.158.0 or higher
• Python 3.14 (Cloud Functions 2nd gen)
• APIs being migrated: rag.retrieval_query(), rag.import_files(), rag.list_files(), rag.delete_file()

Investigating the Deprecation

The first thing I wanted to know was: "Is it actually deprecated?"

The official Google Cloud deprecated products/features list has no mention of vertexai.rag. However, checking the source code, I found that warnings.warn() was explicitly added to vertexai/rag/__init__.py in google-cloud-aiplatform v1.160.0.

There's a time lag between the official documentation and the implementation. Given that the warning is there, I decided it was better to migrate early if the destination agentplatform module was stable.

Note that agentplatform is not a separate package — it's a module within the google-cloud-aiplatform package. No additional installation is needed; you can use it with import agentplatform.

The API Rewrite Itself Is Simple

Here's the mapping for the main methods:

The biggest change is the shift from module-level functions to methods on a client instance. Global initialization via aiplatform.init() is no longer needed; instead, you reuse an instance of agentplatform.Client.

from google.cloud import aiplatform
from vertexai import rag

aiplatform.init(project="my-project", location="asia-northeast1")

response = rag.retrieval_query(
    text=query,
    rag_resources=[rag.RagResource(rag_corpus=corpus_name)],
    rag_retrieval_config=rag.RagRetrievalConfig(
        top_k=5,
        filter=rag.Filter(vector_distance_threshold=0.6),
    ),
)

import agentplatform
from agentplatform import types as ap_types
from google.genai import types

client = agentplatform.Client(project="my-project", location="asia-northeast1")

response = client.rag.retrieve_contexts(
    vertex_rag_store=types.VertexRagStore(
        rag_resources=[
            types.VertexRagStoreRagResource(rag_corpus=corpus_name),
        ],
    ),
    query=ap_types.RagQuery(
        text=query,
        rag_retrieval_config=types.RagRetrievalConfig(
            top_k=5,
            filter=types.RagRetrievalConfigFilter(
                vector_distance_threshold=0.6,
            ),
        ),
    ),
)

The response structure (such as response.contexts.contexts[].text) remains the same, so only the call site needs to change.

Everything went smoothly up to this point. The trouble came next.

Pitfall 1: Type Ownership Is Split Across Two Modules

This is the thing that tripped me up the most during migration.

Types in agentplatform are scattered across two modules:

The tricky part is that locally, importing from either module raises no errors. Because agentplatform.types appears to re-export google.genai.types internally, even hasattr() checks pass.

But when deployed to production (Cloud Functions), this happened:

AttributeError: module 'agentplatform._genai.types' has no attribute 'VertexRagStore'

Perhaps due to subtle differences in module resolution order between local and Cloud Functions environments, agentplatform.types.VertexRagStore cannot be found in production.

Fix: I confirmed the correct owner of each type and clearly separated which types to import from google.genai.types and which to import from agentplatform.types.

# Types to import from google.genai.types
from google.genai import types
# types.VertexRagStore, types.RagRetrievalConfig, etc.

# Types to import from agentplatform.types
from agentplatform import types as ap_types
# ap_types.RagQuery, ap_types.ImportRagFilesConfig, etc.

Pitfall 2: pandas Is a Hidden Required Dependency

Right after deploying, a different error appeared:

ModuleNotFoundError: No module named 'pandas'

Tracing the cause, the agentplatform._genai.rag module imports _gcs_utils at the module level, and that _gcs_utils does import pandas at the top level.

In other words, when using the RAG features of agentplatform, pandas is an implicit required dependency. In google-cloud-aiplatform's pyproject.toml, pandas is listed as an optional dependency, but it is not optional in the RAG module's import path.

Fix: Added pandas>=1.0.0 to pyproject.toml.

dependencies = [
    "google-cloud-aiplatform>=1.158.0",
    "pandas>=1.0.0",  # Required by module-level import in agentplatform.rag
]

Since the old vertexai.rag API worked without pandas, this issue only surfaces during migration.

Pitfall 3: RAG Methods in agentplatform Are Added Incrementally Per Version

The methods on agentplatform.Client.rag were not all added at once — they were added incrementally across versions:

If you need import_files, >=1.156.0 is not enough — >=1.158.0 is the minimum requirement. Since the official documentation doesn't mention this incremental addition, you may scratch your head when you get an AttributeError even after upgrading the version.

Fix: Explicitly specified >=1.158.0 in pyproject.toml to pin a version where all required methods are available.

Note on the Changed Return Value of list_files

This isn't quite a pitfall, but the return value of list_files has changed and deserves attention.

# Old: iterable
for rf in rag.list_files(corpus_name=corpus):
    print(rf.display_name)

# New: ListRagFilesResponse object
response = client.rag.list_files(name=corpus)
for rf in response.rag_files or []:
    print(rf.display_name)

The old API returned a generator, but the new API returns a ListRagFilesResponse object. The .rag_files property holds the list of files (which may be None), so guarding with or [] is the safe approach.

Summary

Here's what I learned from migrating from vertexai.rag to agentplatform.Client.rag:

The API mapping itself is straightforward, so if you're aware of these pitfalls, the migration should take less than half a day. I hope this is helpful for anyone else considering the same migration.