agent-platform-endpoint-management

Agent Platform エンドポイントの管理

概要

このスキルでは、Agent Platform エンドポイントを管理する手順を説明します。 エンドポイントは、オンライン予測用の安定した URL を提供する論理的なサービングホストです。 モデルをデプロイする前に、エンドポイントを作成する必要があります。

安全性と確認レベル（重要）

ユーザーに代わってコマンドを実行する前に、依頼された操作に応じて、以下の安全性レベルを必ず守ってください。

1. レベル R：読み取り専用（list、describe、get）
   • 確認は不要です。情報を収集するため、直ちに実行してください。
2. レベル M：変更可能かつ取り消し可能（create、update）
   • 「はい」／「いいえ」の選択肢を用いた対話型の確認が必要です。確認プロンプトには、必要なフラグ（例：--region=us-central1、--display-name="..."）をすべて含む、正確なコマンド文字列をそのまま記載する必要があります。自然言語による言い換えでは不十分です。
   • 同一ターンでの実行禁止：確認プロンプトを提示したターンと同じターンで、コマンドを絶対に実行しないでください。ユーザーの返答を待ち、明示的な「はい」／承認を受けてから実行してください。
3. レベル D：破壊的かつ取り消し不能（delete）
   • 明示的な入力による確認（例：「確認しました」または「はい、削除してください」）が必要です。事前確認（先に describe を実行したり、エンドポイントが空かどうかを確認したりすること）は行わず、直ちに確認を求めてください。
   • 同一ターンでの実行禁止：入力による確認を求めたターンと同じターンで、絶対に実行しないでください。ユーザーが次のターンで返答するのを待ってください。

フェーズ 0：環境のセットアップ

重要：コマンドを実行する前に、以下の手順に従って環境が正しく初期化されていることを必ず確認してください。

1. Google Cloud 認証：Google Cloud の認証情報で認証し、Agent Platform にアクセスするためのアクティブな Application Default Credentials（ADC）を設定します。

   gcloud auth login
   gcloud auth application-default login
   

2. プロジェクトの設定：以降のコマンドで使用するアクティブなプロジェクトを設定します。

   gcloud config set project $PROJECT_ID
   

3. リージョン：以下の各コマンドには、必ず --region=$LOCATION_ID を指定してください。global は使用しないでください。リージョンが指定されていない場合は、ユーザーに確認してください。

1. エンドポイントの一覧表示（レベル R）

このコマンドを使用すると、特定のリージョンにある既存のエンドポイントを確認し、その ID を取得できます。確認は不要です。

gcloud ai endpoints list \
    --region=$LOCATION_ID

(任意) 結果を制限するには --limit=$LIMIT を使用します。--page-size=$PAGE_SIZE は API の分割単位のみを制御し、出力全体の件数は制限しません。前回のバッチから続けるには --page-token=$PAGE_TOKEN を使用してください。

重要

必ず --region を指定してください。global は使用しないでください。指定されていない場合は、ユーザーに確認してください。

2. エンドポイントの詳細表示（レベル R）

特定のエンドポイントのすべてのメタデータを取得します。確認は不要です。

gcloud ai endpoints describe $ENDPOINT_ID \
    --region=$LOCATION_ID

エンドポイントにデプロイされたモデルは、この出力では deployedModels に含まれます。Python SDK では endpoint.gca_resource.deployed_models です。aiplatform.Endpoint に deployed_models 属性はありません。

3. エンドポイントの作成（レベル M）

新しいエンドポイントリソースを作成します。親リソースはロケーションです。実行する前に、インライン確認カードによる承認が必要です。

gcloud ai endpoints create \
    --region=$LOCATION_ID \
    --display-name="my-endpoint"

このコマンドには --asynchronous フラグがありません。処理が完了するまで待機し、新しいエンドポイントのリソース名を出力します。リソース名の末尾の部分がエンドポイント ID です。

重要

必ず最初に対話型の確認を求めてください。 確認プロンプトには、コマンド文字列をそのまま必ず表示してください。例：

gcloud ai endpoints create --region=$LOCATION_ID --display-name="my-endpoint"

または、フラグを正確に表示してください。確認を求めたターンと同じターンで、このコマンドを実行しないでください。

4. エンドポイントの更新（Tier M）

表示名やラベルなどのエンドポイントメタデータを更新します。実行前にインライン確認カードが必要です。

gcloud ai endpoints update $ENDPOINT_ID \
    --region=$LOCATION_ID \
    --display-name="new-display-name"

エンドポイントを一覧表示するか、詳細を確認して、まずエンドポイントが存在するか確認してください。

重要

必ず最初に対話形式で確認を求めてください。 確認プロンプトには、必ずコマンド文字列をそのまま表示してください。例：

gcloud ai endpoints update $ENDPOINT_ID --region=$LOCATION_ID --display-name="new-display-name"

または、正確なフラグを表示してください。重要： 確認を求めるターンと同じターンに、このコマンドを実行することは固く禁じられています。確認を求めたら、必ず直ちに停止し、ユーザーの返信を待ってください。

5. エンドポイントの削除（Tier D）

エンドポイントのリソースを完全に削除します。実行前に、明示的なテキスト入力による確認が必要です。

gcloud ai endpoints delete $ENDPOINT_ID \
    --region=$LOCATION_ID

警告

エンドポイントを削除する前に、すべてのモデルをエンドポイントからデプロイ解除する必要があります。削除のテキスト確認を受け取るまでは、describe を実行しないでください。

6. トラフィック分割（Tier M）

更新時に、同じエンドポイントにデプロイされた異なるモデル間のトラフィック分割を管理できます。実行前にインライン確認カードが必要です。

# Example: Deploying a model with a specific traffic split is usually done
# via 'gcloud ai endpoints deploy-model'.

モデルのデプロイおよびデプロイ解除の手順については、agent-platform-deploy スキルを参照してください。

トラブルシューティング

• 403 権限拒否：aiplatform.admin または owner ロールが割り当てられていることを確認してください。
• クォータ超過：Cloud Console でリージョンのエンドポイントクォータを確認してください。
• リソースが使用中：削除に失敗した場合は、モデルのデプロイ解除がまだ進行中でないか確認してください。