How to Configure RAG Engine in Agent Platform: Complete Setup Guide

Configure a RAG Engine in Google Agent Platform by initializing the Vertex AI SDK, creating a Rag Corpus through rag.create_corpus(), uploading files via rag.upload_file(), and grounding model responses using the RAG Engine tool in client.models.generate_content().

The Agent Platform RAG Engine enables you to augment generative AI responses with context from a managed knowledge base. According to the google/skills repository, configuring this system involves three core layers: environment preparation, corpus management, and retrieval-augmented generation. This guide walks through each step using the official Python SDKs with working code examples derived from skills/cloud/agent-platform-rag-engine-management/SKILL.md.

Environment Setup and Authentication

Before interacting with the RAG Engine, authenticate to Google Cloud and install the required SDKs.

# Authenticate with GCP

gcloud auth login
gcloud auth application-default login

# Create a dedicated virtual environment

python3 -m venv ~/rag_agent_venv
source ~/rag_agent_venv/bin/activate

# Install the Agent Platform SDKs

pip install google-cloud-aiplatform google-genai

Initialize the Vertex AI SDK

After authentication, initialize the SDK with your project ID and region. This step is required before any corpus operations.

import vertexai
from vertexai.preview import rag

# Replace placeholders with your own values

PROJECT_ID = "my-gcp-project"
REGION = "us-central1"

vertexai.init(project=PROJECT_ID, location=REGION)

Corpus Management Operations

A Rag Corpus stores the documents that ground your AI responses. As implemented in google/skills, you can discover existing corpora or create new ones through the rag module.

Listing Existing Corpora

Use rag.list_corpora() to discover available corpora. The method supports automatic pagination.

# Automatic pagination – returns a full list

all_corpora = list(rag.list_corpora())
print(f"Found {len(all_corpora)} corpora:")
for c in all_corpora:
    print(f"- {c.display_name} ({c.name})")

Creating a New Rag Corpus

If no suitable corpus exists, create one using rag.create_corpus() with a display name and description.

new_corpus = rag.create_corpus(
    display_name="My RAG Corpus",
    description="Grounded knowledge for internal docs"
)
print("Created corpus:", new_corpus.name)

Uploading Files to the Corpus

Upload documents using rag.upload_file(). Construct the corpus name using the format projects/{PROJECT_ID}/locations/{REGION}/ragCorpora/{corpus_id}.

corpus_name = f"projects/{PROJECT_ID}/locations/{REGION}/ragCorpora/{new_corpus.id}"

# Upload a PDF file

rag.upload_file(
    corpus_name=corpus_name,
    file_path="/path/to/document.pdf",
    display_name="document.pdf"
)

# Upload a text file

rag.upload_file(
    corpus_name=corpus_name,
    file_path="/path/to/notes.txt",
    display_name="notes.txt"
)

Retrieval and Grounded Generation

Once your corpus contains files, you can retrieve relevant passages and generate grounded answers.

Retrieve Relevant Contexts

Execute a retrieval query using rag.retrieval_query(). Specify the rag_corpora list and similarity_top_k to control result count.

query = "What are the security best practices for Cloud Storage?"

response = rag.retrieval_query(
    rag_corpora=[corpus_name],
    text=query,
    similarity_top_k=3
)

for ctx in response.contexts.contexts:
    print("▶", ctx.text[:200], "…")
    print("   source:", ctx.source_uri)

Generate Answers with the RAG Engine Tool

For content generation, attach a RAG Engine tool to your model request. This requires the google-genai client and explicit configuration of the VertexRagStore.

from google import genai
from google.genai import types

client = genai.Client(enterprise=True, project=PROJECT_ID, location=REGION)

rag_tool = types.Tool(
    retrieval=types.Retrieval(
        vertex_rag_store=types.VertexRagStore(
            rag_resources=[
                types.VertexRagStoreRagResource(rag_corpus=corpus_name)
            ],
            rag_retrieval_config=types.RagRetrievalConfig(
                top_k=3,
                filter=types.RagRetrievalConfigFilter(
                    vector_similarity_threshold=0.5
                ),
            ),
        )
    )
)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Explain the Cloud Storage security checklist.",
    config=types.GenerateContentConfig(tools=[rag_tool])
)

print("Grounded answer:", response.text)

Safety Considerations and Confirmation Tiers

The Agent Platform RAG Engine implements tiered safety controls according to the source documentation:

• Tier R actions include listing corpora and retrieval queries. These are read-only operations that execute without extra confirmation.
• Tier RC actions include content generation calls like client.models.generate_content(). These require explicit user approval before execution.

Review the safety guidelines in agent-platform-rag-engine-management/SKILL.md before deploying production applications.

Summary

• Environment preparation requires gcloud authentication and installation of google-cloud-aiplatform and google-genai SDKs.
• Corpus management uses rag.create_corpus() to initialize storage and rag.upload_file() to populate it with documents.
• Retrieval operations call rag.retrieval_query() with similarity_top_k parameters to fetch relevant contexts.
• Grounded generation attaches a types.Tool with VertexRagStore configuration to client.models.generate_content().
• Safety tiers distinguish between read-only Tier R operations and Tier RC generation actions requiring explicit approval.

Frequently Asked Questions

What SDKs are required to configure RAG Engine in Agent Platform?

You need two Python packages: google-cloud-aiplatform for corpus management and retrieval operations, and google-genai for grounded content generation with the RAG Engine tool. Install both via pip in a dedicated virtual environment.

How do I upload multiple files to a Rag Corpus?

While rag.upload_file() handles single files, you can invoke it multiple times for batch uploads. Alternatively, check agent-platform-rag-engine-management/references/vector-db-choices.md in the google/skills repository for bulk import options depending on your vector store backend.

What is the difference between Tier R and Tier RC actions?

Tier R covers read-only operations like rag.list_corpora() and rag.retrieval_query() that retrieve metadata and contexts without side effects. Tier RC covers client.models.generate_content() calls that produce new content, requiring explicit user confirmation before execution according to the safety policies defined in the source documentation.

How do I control the number of retrieved contexts in a query?

Pass the similarity_top_k parameter to rag.retrieval_query() or configure rag_retrieval_config.top_k in your VertexRagStore when generating content. Additionally, set vector_similarity_threshold in the RagRetrievalConfigFilter to filter results by relevance score.

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