agent-platform-prompt-management

使用指南

要有效使用此技能：

1. 通过 Python 执行操作：在执行环境中使用 run_command 运行以下 Python 代码片段，代表用户管理 Agent Platform 中的提示词。不要让用户代为执行，也不要在获得批准后声称无法访问。

2. 禁止搜索文件系统：不要尝试在文件系统中查找用于这些操作的 Python 文件或脚本。

安全与确认等级（重要）

在代表用户执行任何命令或脚本之前，必须遵循以下安全等级，具体取决于所请求的操作，以防意外修改或永久删除提示词资源：

1. R 级：只读（list、get）

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

2. M 级：可变更且可撤销（create）

   • 创建提示词前，必须通过交互方式让用户选择“是”或“否”进行确认，以防意外增加资源或配置错误。确认提示必须清楚说明拟创建的提示词及其关键参数（例如显示名称、模板文本、目标模型）。仅用自然语言转述而不明确列出参数是不够的。

   • 同轮限制：展示确认提示的同一轮中不得执行创建代码。停止并等待用户回复；只有在用户明确回复“是”或批准后才能执行。

   • 卡片中的每个参数都必须有用户原话作为依据。目标模型由用户选择，而不是默认值：如果用户没有指定模型，就必须先询问，再构建卡片。不要沿用此处示例或 references/create.md 中出现的模型。

   • 标准示例——对于这样一位用户：“创建一个名为 Customer Support Greeting、使用 gemini-2.5-pro 模型的提示词，模板为 Hello {{user_name}}, how can I help...”：

     我将在 Agent Platform 中创建提示词，参数如下。请先确认这些信息，再继续：

     • 显示名称：Customer Support Greeting
     • 目标模型：gemini-2.5-pro
     • 模板文本：“Hello {{user_name}}, how can I help...”

     是否确认？[是/否]

3. D 级：破坏性且不可撤销（delete）

   • 删除提示词前，必须要求用户输入明确的确认语（例如“I confirm”或“Yes, delete it”），以防生产环境中的提示词资源意外永久丢失。进行任何预检查之前，都必须先征求确认。

   • 同轮限制：提出输入确认语的请求后，绝对不得在同一轮执行操作。等待用户在新一轮回复。

   • 标准示例：

     我将从 Agent Platform 永久删除以下提示词。此操作不可撤销。请明确输入确认语（例如“I confirm”），再继续：

     • 提示词 ID：prompt_12345abc
     • 显示名称：Legacy Outdated Prompt

     请输入确认语以继续。

阶段 0：环境设置

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

1. Google Cloud 身份验证：使用你的 Google Cloud 账号进行身份验证，并配置有效的应用默认凭据（ADC），以访问 Agent Platform：

   gcloud auth login
   gcloud auth application-default login
   

2. Python 依赖项：此技能需要 google-cloud-aiplatform 和 google-genai。不要创建虚拟环境——虚拟环境初始为空，并且会隐藏环境已提供的包，导致重复安装。先检查，只安装缺少的依赖项：

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

3. 执行：使用普通的 python3 运行 Python 代码片段。无需先激活任何环境。

提示

**替换占位参数：**下面的 Python 脚本使用大写字符串占位符（例如 "PROJECT_ID"、"LOCATION_ID"、"PROMPT_ID" 和 "MODEL_ID"）。在生成或提供脚本之前，你必须根据用户提示中提供的实际 Project ID、Region、Prompt ID 和目标模型值（或从上下文中发现的值）动态替换这些占位符。如果用户没有提供其中某个值，请询问——不能用猜测的值替代占位符。

1. 通过 Agent Platform SDK 管理提示词

该 SDK 在预览模块中提供了一个高级 Prompt 类。

创建提示词（Tier M）

需要在 Agent Platform 中创建新的托管提示词时使用。

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

列出提示词（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}")

检索并使用提示词（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")
# Attributes on retrieved Prompt:
# - retrieved_prompt.prompt_id (e.g. "123456789...")
# - retrieved_prompt.prompt_data (template text string)
# - retrieved_prompt.model_name (target model)
# - retrieved_prompt.prompt_name (display name, or
#   retrieved_prompt._dataset.display_name)
# Versions are supported: prompts.get(prompt_id="PROMPT_ID", version_id="2")

# Assemble with variables (kwargs must match template variable names)
assembled = retrieved_prompt.assemble_contents(text="The quick brown fox...")
print(assembled)

删除提示词（Tier D）

重要：必须将数字提示词 ID（例如 "1234567890123456789"）传递给 prompts.delete()。SDK 会在内部使用 vertexai.init() 中的项目和位置构造完整的资源路径。

需要确认：作为 Tier D（破坏性）操作，Agent 必须暂停，并要求用户明确输入提示词 ID 进行高门槛的再次确认，然后才能执行删除代码。此操作不可逆。用户输入确认（例如“我确认”）后，立即通过 run_command 执行删除代码。

重要

**绝不能在收到用户下一轮回复之前预先执行任何删除代码。**绝不能推测或假设用户会确认。在同一轮并行询问确认并运行代码，属于严重的安全违规行为。

import vertexai
from vertexai.preview import prompts

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

prompts.delete(prompt_id="PROMPT_ID")

删除后的验证

当用户要求列出提示词或检查某个提示词是否已删除时，请列出提示词，并明确说明已删除的提示词 ID 是否仍然存在。如果未找到，请明确确认：“我已验证，ID 为 <PROMPT_ID> 的提示词已不再存在于该项目中。”

2. 最佳实践

• 幂等性：
  • Tier R（List、Get）：天然幂等。
  • Tier D（Delete）：对不存在或已删除的资源再次执行删除操作时会返回 NOT_FOUND。将其视为成功。
• 占位符：在提示词模板中使用标准占位符语法（将变量名括在双花括号中）。
• 版本管理：更新生产环境中的提示词时，务必标记或记录版本 ID。
• 模型引用：提示词创建时会关联目标模型 ID，代码片段中使用 "MODEL_ID" 占位符表示。与其他占位符一样，此占位符必须替换，并根据用户所说的内容进行替换——如果用户没有指定模型，请询问。不要替换为看似合理的当前模型，例如 gemini-2.5-pro。
• 底层架构：使用 Dataset API 时，务必使用正确的 metadata_schema_uri 和嵌套的 metadata 结构，以确保 Agent Platform Studio 和 Prompts SDK 能识别该提示词。