AI Skills
agent-platform-prompt-management

agent-platform-prompt-management

熱門

在 Agent Platform 中管理與編排提示詞（Prompt）。當你需要建立、列出、擷取、控管版本或刪除 Agent Platform 託管的提示詞時使用。請勿用於模型訓練、將模型部署至端點，或管理非 Agent Platform 的提示詞。

1.5萬星標
1206分支
更新於 2026/7/31
獲取技能源代碼

相關技能

sherpa-onnx-tts39萬sherpa-onnx-tts38萬latency-critical-systems24萬
SKILL.md
唯讀
名稱
agent-platform-prompt-management
描述

在 Agent Platform 中管理與編排提示詞（Prompt）。當你需要建立、列出、擷取、控管版本或刪除 Agent Platform 託管的提示詞時使用。請勿用於模型訓練、將模型部署至端點，或管理非 Agent Platform 的提示詞。

使用指南

若要有效使用此 Skill：

  1. 產生程式碼：提供下方 Python 程式碼片段給使用者，協助他們在 Agent Platform 中管理提示詞。

  2. 無需搜尋檔案系統：執行這些操作時，請勿嘗試在檔案系統中尋找 Python 檔案或腳本。

安全與確認分級（關鍵規則）

在代表使用者執行任何命令或腳本之前，你必須根據要求的操作遵循以下安全分級，以防止意外變更或永久刪除提示詞資源：

  1. Tier R：唯讀（list、get）

    • 無需確認。立即執行以收集資訊。

  2. Tier M：變更且可逆（create）

    • 執行建立提示詞之前，必須進行帶有「是/否」（Yes/No）選項的互動式確認，以避免資源無意間過度擴增或設定錯誤。確認提示訊息必須清楚說明預計建立的提示詞及其關鍵參數（例如：顯示名稱、範本內文、目標模型）。僅用自然語言模糊概括而未列出具體參數是不夠的。

    • 同對話輪次限制：切勿在提出確認提示的同一個對話輪次中直接執行建立程式碼。請停下來等待使用者回覆，僅在取得明確的「是」或同意後才執行。

    • 黃金標準範例：

      我將在 Agent Platform 中建立包含以下參數的提示詞。請在繼續前確認此資訊：

      • 顯示名稱：Customer Support Greeting
      • 目標模型：gemini-2.5-pro
      • 範本內文："Hello {{user_name}}, how can I help..."

      請確認是否繼續？[Yes/No]

  3. Tier D：毀滅性且不可逆（delete）

    • 執行刪除提示詞之前，必須要求使用者手動輸入明確確認文字（例如：「我確認」或「是的，刪除它」），以防止意外永久遺失正式環境的提示詞資產。在進行任何事前檢查之前，就必須先要求確認。

    • 同對話輪次限制：絕不可在要求手動輸入確認的同一輪次中執行刪除。必須等待使用者在新的輪次中回覆。

    • 黃金標準範例：

      我將從 Agent Platform 永久刪除以下提示詞。此操作無法復原。請在繼續之前明確輸入您的確認文字（例如：「我確認」）：

      • 提示詞 ID：prompt_12345abc
      • 顯示名稱：Legacy Outdated Prompt

      請輸入確認文字以繼續。

Phase 0：環境設定

關鍵注意事項：在使用者執行下方任何 Python 程式碼片段之前，你必須建議他們按照以下步驟確認環境已正確初始化：

  1. Google Cloud 驗證：登入您的 Google Cloud 帳戶，並設定用於存取 Agent Platform 的有效應用程式預設憑證（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"）。在產生或提供腳本之前，你必須根據使用者提示詞（或已獲取的上下文）提供的實際專案 ID、區域（Region）及提示詞 ID 動態替換這些佔位符。

1. 透過 Agent Platform SDK 管理提示詞

SDK 在 preview 模組中提供了高階的 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")
# 支援版本指定：prompts.get(prompt_id="PROMPT_ID", version_id="2")

# 帶入變數進行組合（kwargs 必須與範本中的變數名稱一致）
assembled = retrieved_prompt.assemble_contents(text="The quick brown fox...")
print(assembled)

刪除提示詞（Tier D）

關鍵注意事項：呼叫 prompts.delete() 時，必須傳入純數字的提示詞 ID（例如 "1234567890123456789"）。SDK 會在內部使用 vertexai.init() 設定的專案與區域自動構建完整的資源路徑。

必須進行確認：作為 Tier D（毀滅性）操作，Agent 在產生或提供刪除程式碼之前，必須暫停並要求使用者再次手動輸入提示詞 ID 進行高阻力的明確確認。此操作無法復原。

[!IMPORTANT]

在收到使用者於新輪次中的回覆之前，絕不可預先提供或執行任何刪除程式碼。 切勿推測或假設使用者一定會給予確認。在同一個輪次中同時要求確認並提供程式碼屬於嚴重的安全違規。

import vertexai
from vertexai.preview import prompts

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

prompts.delete(prompt_id="PROMPT_ID")

2. 最佳實踐

  • 冪等性（Idempotency）：
    • Tier R（List、Get）：天然具備冪等性。
    • Tier D（Delete）：對不存在或已被刪除的資源重複執行刪除會傳回 NOT_FOUND，應視為執行成功。
  • 佔位符（Placeholders）：在提示詞範本中使用標準佔位符語法（將變數名稱包裹於雙大括號中）。
  • 版本控管（Versioning）：更新正式環境的提示詞時，務必標記或記錄版本 ID。
  • 模型參照（Model Reference）：建立提示詞時指定目標模型 ID（例如 gemini-2.5-pro），以確保行為一致。
  • 底層 Schema（Underlying Schema）：使用 Dataset API 時，請務必使用正確的 metadata_schema_uri 與巢狀 metadata 結構，以確保提示詞能被 Agent Platform Studio 及 Prompts SDK 正確辨識。