agent-platform-prompt-management

使用指南

为高效使用本 Skill，请遵循以下原则：

1. 生成代码：将下文中的 Python 代码片段提供给用户，协助其管理 Agent Platform 中的 Prompt。

2. 无需搜索文件系统：切勿尝试在本地文件系统中查找或搜索执行这些操作的 Python 文件或脚本。

安全与确认分级（重要）

代表用户执行任何命令或脚本前，你必须根据请求的操作严格遵守以下安全分级要求，以防意外修改或永久删除 Prompt 资源：

1. Tier R：只读操作（list、get）

   • 无需确认：立即执行以收集信息。

2. Tier M：修改类且可逆操作（create）

   • 在执行创建 Prompt 操作前，必须进行交互式确认（提供“是”/“否”选项），以防止意外创建多余资源或产生错误配置。确认提示中必须清晰明确地说明拟创建 Prompt 的具体参数（如显示名称 display name、模板文本 template text、目标模型 target model）。仅使用模糊的自然语言概述而不列出具体参数是不合规的。

   • 单 Turn 限制：切勿在发送确认提示的同一 Turn 内直接执行创建代码。必须暂停并等待用户回复；仅在用户明确选择“是”或批准后再执行。

   • 标准范例：

     我将在 Agent Platform 中创建具有以下参数的 Prompt，请在继续之前核对确认：

     • Display Name: Customer Support Greeting
     • Target Model: gemini-2.5-pro
     • Template Text: "Hello {{user_name}}, how can I help..."

     请问是否确认创建？[是/否]

3. Tier D：破坏性且不可逆操作（delete）

   • 在执行 Prompt 删除前，必须要求用户手动打字输入明确确认信息（例如“我确认”或“确认删除”），以防生产环境中的 Prompt 资产被误删。在进行任何预检（pre-flight checks）之前就必须要求确认。

   • 单 Turn 限制：绝不能在要求用户打字确认的同一 Turn 内执行删除操作。必须等待用户在新的 Turn 中做出回复。

   • 标准范例：

     我将从 Agent Platform 中永久删除以下 Prompt，此操作无法撤销。请在继续前手动打字输入确认信息（例如：“我确认”）：

     • Prompt ID: prompt_12345abc
     • Display Name: Legacy Outdated Prompt

     请打字输入确认信息以继续。

阶段 0：环境准备

重要：在用户运行以下任何 Python 代码片段之前，你必须提醒用户按以下步骤确保环境已正确初始化：

1. Google Cloud 身份认证：登录你的 Google Cloud 账号，并配置用于访问 Agent Platform 的有效应用默认凭据（Application Default Credentials，简称 ADC）：

   gcloud auth login
   gcloud auth application-default login
   

2. Python 依赖库：本 Skill 需要用到 google-cloud-aiplatform 和 google-genai。请勿创建虚拟环境 —— 虚拟环境初始为空，会遮蔽系统环境中已有的包，从而导致重复安装。请先检测环境，仅安装缺失的依赖：

   python3 -c "import vertexai, google.genai" \
     || pip install google-cloud-aiplatform google-genai
   

3. 执行代码：直接使用 python3 运行 Python 代码片段即可，无需提前激活任何虚拟环境。

[!TIP]

占位符参数替换：下文的 Python 脚本使用了大写字符串占位符（如 "PROJECT_ID"、"LOCATION_ID" 和 "PROMPT_ID"）。在生成或提供脚本前，你必须将这些占位符动态替换为用户 Prompt（或解析出的上下文）中提供的实际 Project ID、Region 和 Prompt ID。

1. 通过 Agent Platform SDK 管理 Prompt

SDK 在 preview 模块中提供了一个高层级的 Prompt 类。

创建 Prompt（Tier M）

当需要在 Agent Platform 中创建新的托管 Prompt 时使用。

• 参考文档：有关详细说明和 Python 代码片段，请参阅 create.md。

列出 Prompt（Tier R）

import vertexai
from vertexai.preview import prompts

vertexai.init(project="PROJECT_ID", location="LOCATION_ID")

all_prompts = prompts.list()
for p in all_prompts:
    print(f"Name: {p.display_name}, ID: {p.prompt_id}")

获取与使用 Prompt（Tier R）

import vertexai
from vertexai.preview import prompts

vertexai.init(project="PROJECT_ID", location="LOCATION_ID")

retrieved_prompt = prompts.get(prompt_id="PROMPT_ID")
# 支持指定版本：prompts.get(prompt_id="PROMPT_ID", version_id="2")

# 填充变量进行组装（kwargs 必须与模板变量名保持一致）
assembled = retrieved_prompt.assemble_contents(text="The quick brown fox...")
print(assembled)

删除 Prompt（Tier D）

重要：你必须向 prompts.delete() 传入纯数字的 Prompt ID（例如 "1234567890123456789"）。SDK 会基于 vertexai.init() 中配置的项目与位置在内部自动构建完整的资源路径。

必须请求确认：由于此操作属于 Tier D（破坏性操作），Agent 在生成或提供删除代码前，必须暂停并要求用户输入高门槛的二次打字确认（明确核对 Prompt ID）。此操作不可撤销。

[!IMPORTANT]

在新的 Turn 中收到用户回复前，绝对不要提前提供或执行任何删除代码。 切勿擅自推测或假设用户一定会同意。在同一个 Turn 中既发起确认请求又给出代码，属于严重违规的安全行为。

import vertexai
from vertexai.preview import prompts

vertexai.init(project="PROJECT_ID", location="LOCATION_ID")

prompts.delete(prompt_id="PROMPT_ID")

2. 最佳实践

• 幂等性：
  • Tier R（列出、获取）：天然具备幂等性。
  • Tier D（删除）：对不存在或已被删除的资源重复执行删除操作会返回 NOT_FOUND，应直接视为操作成功。
• 占位符：在 Prompt 模板中统一使用标准占位符语法（双大括号包裹变量名）。
• 版本控制：更新生产环境中的 Prompt 时，切记打上标签或记录版本 ID。
• 模型引用：创建 Prompt 时请明确指定目标模型 ID（例如 gemini-2.5-pro），以确保效果的一致性。
• 底层 Schema：使用 Dataset API 时，务必使用正确的 metadata_schema_uri 以及嵌套的 metadata 结构，以确保该 Prompt 能被 Agent Platform Studio 及 Prompts SDK 正确识别。