agent-platform-prompt-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Usage Guide

使用指南

To use this skill effectively:

Generate Code: Provide the Python snippets below to the user to help them manage prompts in Agent Platform.
No File System Search: Do not try to find Python files or scripts on the file system for these operations.

要有效使用此技能：

生成代码：向用户提供以下Python代码片段，帮助他们在Agent Platform中管理提示词。
无需文件系统搜索：不要尝试在文件系统中查找用于这些操作的Python文件或脚本。

Phase 0: Environment Setup

阶段0：环境设置

CRITICAL: Before the user runs any of the Python snippets below, you MUST advise them to ensure the environment is correctly initialized by following these steps:

Google Cloud Authentication: Authenticate with your Google Cloud account and configure active Application Default Credentials (ADC) for Agent Platform access:
bash
```
gcloud auth login
gcloud auth application-default login
```

Virtual Environment: Create and activate a dedicated virtual environment:

bash

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

Install Dependencies: Install the required Agent Platform SDKs:
bash
```
pip install google-cloud-aiplatform google-genai
```
Execution: Advise the user that every time they execute a Python snippet, they must ensure this virtual environment is activated first.

[!TIP] Placeholder Parameter Replacement: The Python scripts below use uppercase string placeholders (like
"PROJECT_ID"
,
"LOCATION_ID"
, and
"PROMPT_ID"
). You MUST dynamically replace these placeholders with the actual Project ID, Region, and Prompt ID values provided in the user's prompt (or discovered context) before generating or providing the scripts.

关键提示：在用户运行以下任何Python代码片段之前，您必须建议他们按照以下步骤确保环境已正确初始化：

Google Cloud身份验证：使用您的Google Cloud账户进行身份验证，并为Agent Platform访问配置有效的应用默认凭据（ADC）：
bash
```
gcloud auth login
gcloud auth application-default login
```

虚拟环境：创建并激活专用虚拟环境：

bash

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

安装依赖：安装所需的Agent Platform SDK：
bash
```
pip install google-cloud-aiplatform google-genai
```
执行说明：建议用户每次执行Python代码片段时，必须先确保此虚拟环境已激活。

[!提示] 占位符参数替换：以下Python脚本使用大写字符串占位符（如
"PROJECT_ID"
,
"LOCATION_ID"
, 和
"PROMPT_ID"
）。在生成或提供脚本之前，您必须将这些占位符动态替换为用户提示中提供的（或从上下文获取的）实际项目ID、区域和提示词ID值。

1. Managing Prompts via Agent Platform SDK

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

The SDK provides a high-level

Prompt

class in the preview module.

SDK在预览模块中提供了高级

Prompt

类。

Create a Prompt (Tier M)

创建提示词（M级）

Use when you need to create a new managed prompt in Agent Platform.

Reference: See create.md for detailed instructions and Python snippets.

适用于需要在Agent Platform中创建新的托管提示词的场景。

参考文档：详细说明和Python代码片段请参见create.md。

List Prompts (Tier R)

列出提示词（R级）

python

from vertexai.preview import prompts

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

python

from vertexai.preview import prompts

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

Retrieve and Use a Prompt (Tier R)

检索并使用提示词（R级）

python

from vertexai.preview import prompts

retrieved_prompt = prompts.get(prompt_id="projects/PROJECT_ID/locations/LOCATION_ID/prompts/PROMPT_ID")

python

from vertexai.preview import prompts

retrieved_prompt = prompts.get(prompt_id="projects/PROJECT_ID/locations/LOCATION_ID/prompts/PROMPT_ID")

Versions are supported: prompts.get(prompt_id=..., version_id="2")

支持版本控制：prompts.get(prompt_id=..., version_id="2")

Assemble with variables

结合变量使用

assembled = retrieved_prompt.assemble(text="The quick brown fox...") print(assembled)

undefined

assembled = retrieved_prompt.assemble(text="The quick brown fox...") print(assembled)

undefined

Delete a Prompt (Tier D)

删除提示词（D级）

CRITICAL: You must use the full resource name (e.g.,

projects/PROJECT_ID/locations/LOCATION_ID/prompts/PROMPT_ID

) when deleting a prompt. Do not pass just the numeric ID.

Confirmation Required: As a Tier D (Destructive) operation, the agent MUST pause and request explicit, high-friction typed re-confirmation of the prompt resource name from the user before generating or providing the deletion code. The action is irreversible.

[!IMPORTANT] NEVER pre-emptively provide or execute any deletion code before receiving the user's response in a new turn. You must never speculate or assume that confirmation will be given. Asking for confirmation and providing the code in a single parallel turn is a severe safety violation.

python

from vertexai.preview import prompts

关键提示：删除提示词时必须使用完整资源名称（例如

projects/PROJECT_ID/locations/LOCATION_ID/prompts/PROMPT_ID

），不要仅传递数字ID。

需要确认：作为D级（破坏性）操作，智能体必须暂停并请求用户以明确、高门槛的输入方式重新确认提示词资源名称，然后才能生成或提供删除代码。此操作不可逆。

[!重要提示] 在收到用户新回合的回复之前，绝不要预先提供或执行任何删除代码。 您绝不能猜测或假设用户会确认。在同一回合中同时请求确认并提供代码属于严重的安全违规行为。

python

from vertexai.preview import prompts

Always use full resource name

始终使用完整资源名称

resource_name = "projects/PROJECT_ID/locations/LOCATION_ID/prompts/PROMPT_ID" prompts.delete(prompt_id=resource_name)

undefined

resource_name = "projects/PROJECT_ID/locations/LOCATION_ID/prompts/PROMPT_ID" prompts.delete(prompt_id=resource_name)

undefined

2. Best Practices

2. 最佳实践

Idempotency:
- Tier R (List, Get): Inherently idempotent.
- Tier D (Delete): Re-running a delete on a non-existent or already deleted resource returns NOT_FOUND. Treat this as success.
Placeholders: Use the standard placeholder syntax (variable name enclosed in double curly braces) in your prompt templates.
Versioning: Always tag or record version IDs when making updates to production prompts.
Model Reference: Specify the target model ID (e.g.,
```
gemini-2.5-pro
```
) when creating the prompt to ensure consistency.
Underlying Schema: When using the Dataset API, always use the correct
```
metadata_schema_uri
```
and nested
```
metadata
```
structure to ensure the prompt is recognized by Agent Platform Studio and the Prompts SDK.

幂等性:
- R级（列出、获取）：天生具有幂等性。
- D级（删除）：对不存在或已删除的资源重新执行删除操作会返回NOT_FOUND，将此视为操作成功。
占位符：在提示词模板中使用标准占位符语法（变量名称用双大括号括起）。
版本控制：在更新生产环境中的提示词时，始终标记或记录版本ID。
模型参考：创建提示词时指定目标模型ID（例如
```
gemini-2.5-pro
```
）以确保一致性。
底层架构：使用Dataset API时，始终使用正确的
```
metadata_schema_uri
```
和嵌套的
```
metadata
```
结构，以确保提示词能被Agent Platform Studio和Prompts SDK识别。