前言¶

企业里做问答、知识库助手，往往要把文档灌进 RAG 语料库，再查有哪些 corpus、里面有哪些文件、检索片段是否命中，最后用模型做 grounded 生成。这些步骤分散在 Vertex AI SDK、资源名规则和 GenAI 调用之间，Agent 很容易拼错 projects/.../ragCorpora/... 或混用不合适的 API。

下面介绍 Google 官方仓库里的 agent-platform-rag-engine-management Skill（当前 metadata 版本 1.0.1）。它把「发现语料库 → 查看详情 → 检索上下文 → 可选的 grounded 生成」写成固定工作流，并规定必须用 vertexai Python SDK，而不是裸 REST 或 MCP。

这是什么¶

• 定位：管理与查询 Agent Platform RAG Engine 的 Corpora，并用 Google GenAI SDK 检索 grounding 内容、在指定 corpus 上生成 grounded 回答。
• 维护方：Google，收录于 google/skills 的 AI/ML 类 Skill。
• 适用对象：已在 Google Cloud 上使用 Agent Platform RAG Engine、希望由编码 Agent 按官方步骤执行运维与检索的开发者。
• 明确不覆盖：标准数据库查询（应使用 SQL/Spanner 相关 Skill）、Google Workspace RAG、以及 gRAG 等其他 RAG 产品。

Skill 正文说明：操作应由外部客户端执行，因此 必须 通过 Agent Platform Python SDK（vertexai）完成 RAG Engine 相关调用。

核心功能¶

Skill 按任务类型组织能力，与官方描述一致：

工作流决策上：若用户未提供 Project ID、Region、Corpus ID，应先做「列举 corpora / files」做发现；已知 ID 则按任务直接进入对应章节。脚本中的 {project_id}、{region}、{corpus_id} 占位符必须在执行前替换为真实值。

安全与确认分级（Agent 必遵守）¶

官方将操作分为两级，写 Skill 的 Agent 在执行前要对齐：

1. Tier R（只读）：list_corpora、list_files、get_corpus、retrieval_query — 无需确认，可直接执行。
2. Tier RC（只读但消耗计算）：client.models.generate_content 的 grounded 生成 — 必须先交互确认（Yes/No），且须列出 Target Corpus ID、Target Model、Query Text 等确切参数；不得在同一轮对话里先弹确认又立刻执行，须等用户明确同意后再跑代码。

安装与启用¶

Skill 随 Google 官方 Skills 仓库分发，安装方式以仓库 README 为准：

npx skills add google/skills

按提示选择要安装的 Skill（可只选 Agent Platform RAG Engine Management）、目标 Agent 以及作用域（项目或全局）。环境若无 npx，需先安装 Node.js。更新已安装 Skill：

npx skills update

Skill 源码目录：

https://github.com/google/skills/tree/main/skills/cloud/agent-platform-rag-engine-management

本文未核实 Cursor、Codex CLI、Claude Code 各自的 Skill 挂载差异，仅以 npx skills add 为准。

环境准备（Phase 0）¶

在运行 Skill 中的 Python 片段前，先做认证与依赖准备。

1. Google Cloud 认证（配置 Application Default Credentials）：

gcloud auth login
gcloud auth application-default login

2. Python 依赖：需要 google-cloud-aiplatform 与 google-genai。Skill 建议直接运行脚本；若报 ModuleNotFoundError，再在同一条命令里安装并重试：

pip install -q google-cloud-aiplatform google-genai && python3 - <<'PY'
# 你的脚本
PY

3. 执行方式：推荐 python3 - <<'PY' ... PY 的 heredoc，避免 python3 -c 引号嵌套问题。多步操作（例如先 list corpora 再 list files）应合并为一次脚本、一次命令。stderr 上出现 vertexai.preview.rag 的 deprecation 警告可忽略，仍按 Skill 中的 preview API 使用。

典型用法¶

初始化与语料库资源名¶

所有示例先 vertexai.init(project="{project_id}", location="{region}")。单个 corpus 的资源名格式为：

projects/{project_id}/locations/{region}/ragCorpora/{corpus_id}

1. 发现 corpora 与文件¶

不知道 corpus 或 file 的 Resource Name 时，必须先列举。自动分页示例：

import vertexai
from vertexai.preview import rag

vertexai.init(project="{project_id}", location="{region}")

all_corpora = list(rag.list_corpora())
print(f"Found {len(all_corpora)} corpora in total.")
for c in all_corpora:
    print(f"Corpus Name: {c.name} | Display Name: {c.display_name}")

针对某一 corpus 列举文件：

corpus_name = (
    "projects/{project_id}/locations/{region}/ragCorpora/{corpus_id}"
)
files = list(rag.list_files(corpus_name=corpus_name))
for f in files:
    print(f"File: {f.display_name} | Resource: {f.name}")

2. 查看语料库详情¶

corpus = rag.get_corpus(name=corpus_name)
print(f"Corpus Name: {corpus.name}")
print(f"Display Name: {corpus.display_name}")

3. 检索上下文（不调用生成模型）¶

根据自然语言 query 从 corpus 拉取相关片段；若无命中，向用户说明使用的 corpus 与 query。可在同一脚本内尝试调大 similarity_top_k：

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

for context in response.contexts.contexts:
    print(f"Context text: {context.text}")
    print(f"Source: {context.source_uri}")

4. 基于语料库的 grounded 生成¶

使用 google.genai 客户端，将 RAG Engine corpus 配置为 VertexRagStore 工具，再 generate_content。此步属于 Tier RC，Agent 须先按 Skill 要求完成参数确认，再在下一轮执行：

from google import genai
from google.genai import types

client = genai.Client(enterprise=True, project="{project_id}", location="{region}")
corpus_name = (
    "projects/{project_id}/locations/{region}/ragCorpora/{corpus_id}"
)

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="What is the speed of light?",
    config=types.GenerateContentConfig(tools=[rag_tool]),
)
print(response.text)

官方示例中的模型名为 gemini-2.5-flash；确认生成时 Skill 示例使用 gemini-2.5-pro 作为说明模板，实际以你确认的模型为准。

适用场景与注意¶

适合谁

• 已在 Agent Platform 上创建 RAG Engine corpus，需要 Agent 帮忙做资源发现、文件清单、检索抽检和 grounded 问答原型。
• 希望统一走 vertexai.preview.rag + GenAI SDK，避免 Agent 自行拼凑 REST 或误用其他 RAG 产品 Skill。

限制与坑

• 依赖有效的 GCP 项目、区域与 IAM；未配置 ADC 时脚本会认证失败。
• Grounded 生成会产生推理费用，Skill 强制二次确认，人工也应核对 corpus 与 query，避免误用生产语料。
• 不要用本 Skill 替代 Spanner/SQL、Workspace RAG 或 gRAG 场景。
• Sandbox 若自带上述 Python 包，Skill 明确不建议新建空虚拟环境，以免看不到预装依赖。

结尾¶

agent-platform-rag-engine-management 把 Agent Platform RAG Engine 的列举、检查、检索与 grounded 生成收敛成可复现的 SDK 步骤，并区分只读与耗算力操作。若你正在用 Google Cloud 企业 Agent 与 RAG Engine，可通过官方 Skills 安装后交给 Agent 按正文执行。

官方地址：https://github.com/google/skills/tree/main/skills/cloud/agent-platform-rag-engine-management