/agent-platform-rag-engine-management

name: agent-platform-rag-engine-management
metadata:
  version: "1.0.2"
  category: AiAndMachineLearning
description: >-
  Manage and query Agent Platform RAG Engine Corpora and retrieve grounded
  contexts using the Google GenAI SDK. Use when listing RAG corpora or files,
  inspecting a corpus, retrieving contexts, or generating content grounded in a
  RAG corpus. Do not use for standard database queries (use SQL/Spanner skills),
  Google Workspace RAG, or other RAG products like gRAG.

Agent Platform RAG Engine Management

This skill provides instructions on how to interact with Agent Platform RAG Engine using the Agent Platform Python SDK. You MUST use the `vertexai` Python SDK to perform RAG Engine operations, rather than raw REST calls or MCP tools, because this code is intended to be run by external clients.

Attribution

**MUST READ**: Before executing any `gcloud`, REST API, or MCP command, you MUST read [Usage Attribution](references/attribution.md). For commands executed directly in the terminal (never in generated scripts, Terraform, or user code), prefix `gcloud` with `CLOUDSDK_METRICS_REQUEST_ATTRIBUTION` and append the attribution suffix to `User-Agent` headers:

CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:agent-platform-rag-engine-management)"
User-Agent: <existing_user_agent> agent-skills/1.0 (skill:agent-platform-rag-engine-management)

Safety & Confirmation Tiers (CRITICAL)

Before executing any commands or scripts on behalf of the user, you must adhere to the following safety tiers based on the action requested:

1. **Tier R: Read-only (`list_corpora`, `list_files`, `get_corpus`, `retrieval_query`)**

• No confirmation needed. Execute immediately to gather information or

retrieve grounded contexts. 2. **Tier RC: Read-only but consumes Compute Resources (`client.models.generate_content`)**

• Requires **interactive confirmation** with 'Yes'/'No' options before

executing grounded content generation. The confirmation prompt MUST clearly explain the proposed generation execution and its key parameters (e.g., target corpus ID, query text, target model). Natural-language paraphrases without specifying exact parameters are insufficient, as explicit parameter listing is required to ensure unambiguous user approval of the specific resource and configuration.

• **Same-turn restriction**: Do not execute the generation code in the

same turn as presenting the confirmation prompt. Stop and wait for the user's reply; only execute after explicit 'Yes' / approval.

• **Gold Standard Example**:

> I will perform grounded content generation with the following > parameters. Please confirm this information before I proceed: > > * **Target Corpus ID**: `projects/123/locations/us/ragCorpora/abc` > * **Target Model**: `gemini-2.5-pro` > * **Query Text**: "What are the company policies on remote work?" > > Do you confirm? [Yes/No]

Phase 0: Environment Setup

**CRITICAL**: Before running any of the Python snippets below, you must ensure the environment is correctly initialized by following these steps:

1. **Google Cloud Authentication**: Authenticate with your Google Cloud credentials and configure active Application Default Credentials (ADC) for Agent Platform access:

    gcloud auth login
    gcloud auth application-default login

2. **Python Dependencies**: This skill needs `google-cloud-aiplatform` and `google-genai`, which the sandbox already provides. Do **not** create a virtual environment — it starts empty and hides packages the environment already provides, forcing a redundant install. Do not spend a separate command checking for them: run the snippet directly, and only if it fails with `ModuleNotFoundError`, install in the same command as the retry:

    pip install -q google-cloud-aiplatform google-genai && python3 - <<'PY'
    ...
    PY

3. **Execution**: Run each snippet as a quoted heredoc, `python3 - <<'PY'` ... `PY`, rather than `python3 -c '...'`, whose nested quotes break easily. There is no environment to activate first. When one step needs several of the snippets below (for example, list the corpora and then the files in each), combine them into one script and one command. The `vertexai.preview.rag` deprecation warning printed on stderr is expected; keep using these snippets rather than switching clients because of it.

Workflow Decision Tree

1. **Information Gathering**: Has the user provided the Project ID, Region, and Corpus ID?

• **No** -> Proceed to [1. Listing Corpora and Files] to discover the

necessary Resource Names and IDs. Only ask the user if discovery fails.

• **Yes** -> Proceed.

2. **Task Type**: What does the user want to do?

• **List Corpora and Files** -> Proceed to [1. Listing Corpora and Files].
• **Inspect a Corpus** -> Proceed to [2. Getting / Inspecting a RAG Engine

Corpus].

• **Search for Contexts** -> Proceed to [3. Retrieving Contexts].
• **Answer questions using RAG Engine** -> Proceed to [4. Answering the

User with Retrieved Context].

> [!TIP] > > **Placeholder Parameter Replacement:** The Python scripts below use bracketed > string placeholders (like `"{project_id}"`, `"{region}"`, and > `"{corpus_id}"`). You **MUST** dynamically replace these placeholders with the > actual Project ID, Region, and Corpus ID values provided in the user's prompt > (or active context) before generating, providing, or executing the scripts.

1. Listing Corpora and Files (Discovery)

If you do not know the Resource Name of the corpus or file, you MUST list them first to discover them. The SDK handles pagination automatically when converted to a list, but you can also use manual