agent-platform-prompt-management

使用ガイド

このスキルを効果的に使用するには、次の手順に従ってください。

1. Python を使って操作を実行する：実行環境で run_command を使って以下の Python スニペットを実行し、ユーザーに代わって Agent Platform のプロンプトを管理します。実行をユーザーに委ねたり、承認を得た後にアクセスできないと主張したりしないでください。

2. ファイルシステムを検索しない：これらの操作に使用する Python ファイルやスクリプトを、ファイルシステム上で探そうとしないでください。

安全性と確認の階層（重要）

ユーザーに代わってコマンドやスクリプトを実行する前に、プロンプトリソースの誤った変更や恒久的な削除を防ぐため、依頼された操作に応じて以下の安全性の階層を守る必要があります。

1. 階層 R：読み取り専用（list、get）

   • 確認は不要です。情報を収集するため、すぐに実行します。

2. 階層 M：変更可能かつ取り消し可能（create）

   • 意図しないリソースの増加や設定ミスを防ぐため、プロンプトを作成する前に、「Yes」／「No」の選択肢を含む対話形式の確認が必要です。確認メッセージでは、提案するプロンプト作成の内容と主なパラメーター（表示名、テンプレートテキスト、対象モデルなど）を明確に説明する必要があります。パラメーターを指定せずに自然言語で言い換えるだけでは不十分です。

   • 同一ターンの制限：確認メッセージを提示したターン内に、作成コードを実行してはいけません。停止してユーザーの返信を待ち、「Yes」または明示的な承認を受けてから実行します。

   • カード内の各パラメーターはすべて、ユーザーの発言に基づいている必要があります。対象モデルはユーザーが選択するものであり、デフォルト値はありません。ユーザーがモデルを指定していない場合は、カードを作成する前に確認してください。ここや references/create.md の例に登場するモデルを引き継いではいけません。

   • 優れた例 — 「gemini-2.5-pro 用に、Customer Support Greeting という名前のプロンプトを、テンプレート Hello {{user_name}}, how can I help... で作成して」と依頼したユーザーの場合：

     以下のパラメーターで Agent Platform にプロンプトを作成します。実行する前に、内容をご確認ください。

     • 表示名：Customer Support Greeting
     • 対象モデル：gemini-2.5-pro
     • テンプレートテキスト：「Hello {{user_name}}, how can I help...」

     この内容でよろしいですか？［Yes／No］

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 アカウントで認証し、Agent Platform にアクセスするための Application Default Credentials（ADC）を 有効に設定します。

   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. 実行：Python スニペットは、そのまま python3 で実行します。先に 有効化する環境はありません。

ヒント

プレースホルダーパラメーターの置換：以下の Python スクリプトでは、大文字の 文字列プレースホルダー（"PROJECT_ID"、"LOCATION_ID"、"PROMPT_ID"、 "MODEL_ID" など）を使用しています。スクリプトを生成または提示する前に、 ユーザーのプロンプト（または判明しているコンテキスト）で指定された実際の Project ID、リージョン、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）

重要：prompts.delete() には数値のプロンプト ID（例： "1234567890123456789"）を渡す必要があります。SDK は vertexai.init() の プロジェクトとロケーションを使用して、完全なリソースパスを内部で構築します。

確認が必要です：Tier D（破壊的）操作であるため、削除コードを実行する前に、 エージェントは一旦処理を停止し、ユーザーにプロンプト 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（一覧取得、取得）：本質的にべき等です。
  • Tier D（削除）：存在しないリソース、またはすでに削除されたリソースに対して削除を再実行すると、NOT_FOUND が返されます。これを成功として扱います。
• プレースホルダー：プロンプトテンプレートでは、標準のプレースホルダー構文（変数名を二重波括弧で囲む）を使用します。
• バージョン管理：本番環境のプロンプトを更新するときは、必ずバージョン ID をタグ付けするか記録します。
• モデル参照：プロンプトは対象モデル ID を指定して作成します。スニペットではこれを "MODEL_ID" プレースホルダーとして示しています。他のプレースホルダーと同様に、これは必ず置き換える必要があります。ユーザーの発言に基づいて置き換えます。モデル名が指定されていない場合は、ユーザーに確認してください。gemini-2.5-pro のような、もっともらしい現行モデルに置き換えてはいけません。
• 基盤となるスキーマ：Dataset API を使用する際は、プロンプトが Agent Platform Studio と Prompts SDK に認識されるよう、必ず正しい metadata_schema_uri とネストされた metadata 構造を使用します。