agent-platform-endpoint-management

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Platform Endpoint Management

Agent Platform端点管理

Overview

概述

This skill provides procedural knowledge for managing Agent Platform Endpoints. Endpoints are logical serving hosts that provide a stable URL for online predictions. You must create an endpoint before you can deploy a model to it.

本技能提供管理Agent Platform端点的流程知识。端点是为在线预测提供稳定URL的逻辑服务主机。在将模型部署到端点之前，您必须先创建一个端点。

Safety & Confirmation Tiers (CRITICAL)

安全与确认级别（至关重要）

Before executing any commands on behalf of the user, you MUST adhere to the following safety tiers based on the action requested:

Tier R: Read-only (
list
,
describe
,
get
)
- No confirmation needed. Execute immediately to gather information.
Tier M: Mutating & Reversible (
create
,
update
)
- Requires interactive confirmation with 'Yes'/'No' options. The confirmation prompt MUST contain the exact, literal command string with all required flags (e.g.
```
--region=us-central1
```
  ,
```
--display-name="..."
```
  ) — natural-language paraphrases are NOT sufficient.
- Same-turn restriction: NEVER execute the command in the same turn as presenting the confirmation prompt. Stop and wait for the user's reply; only execute after explicit 'Yes' / approval.
Tier D: Destructive & Irreversible (
delete
)
- Requires explicit typed confirmation (e.g. "I confirm" or "Yes, delete it"). Ask for confirmation IMMEDIATELY — before any pre-flight checks (don't
```
describe
```
  first, don't check if the endpoint is empty first).
- Same-turn restriction: NEVER execute in the same turn as asking for typed confirmation. Wait for the user to reply in a new turn.

在代表用户执行任何命令之前，您必须根据请求的操作遵循以下安全级别：

Tier R：只读操作（
list
、
describe
、
get
）
- 无需确认。立即执行以收集信息。
Tier M：可变更且可撤销操作（
create
、
update
）
- 需要交互式确认，提供“是/否”选项。确认提示必须包含完整的命令字符串及所有必要参数（例如
```
--region=us-central1
```
  、
```
--display-name="..."
```
  ）——自然语言表述是不够的。
- 同轮次限制：绝对不能在展示确认提示的同一轮次执行命令。停止并等待用户回复；仅在收到明确的“是”或批准后执行。
Tier D：破坏性且不可撤销操作（
delete
）
- 需要明确的输入确认（例如“我确认”或“是的，删除它”）。立即请求确认——在任何预检检查之前（不要先执行
```
describe
```
  ，也不要先检查端点是否为空）。
- 同轮次限制：绝对不能在请求输入确认的同一轮次执行命令。等待用户在新的轮次中回复。

Phase 0: Environment Setup

阶段0：环境设置

CRITICAL: Before running any commands, you MUST ensure the environment is correctly initialized by following these steps:

Google Cloud Authentication: Authenticate with your Google Cloud credentials and configure active Application Default Credentials (ADC) for Agent Platform access:
bash
```
gcloud auth login
gcloud auth application-default login
```
Set Project: Configure the active project for subsequent commands:
bash
```
gcloud config set project $PROJECT_ID
```
Region: Always specify
```
--region=$LOCATION_ID
```
on each command below. Do NOT use
```
global
```
. Ask the user to specify the region if not provided.

至关重要：在运行任何命令之前，您必须按照以下步骤确保环境已正确初始化：

Google Cloud身份验证：使用您的Google Cloud凭据进行身份验证，并为Agent Platform访问配置有效的应用默认凭据（ADC）：
bash
```
gcloud auth login
gcloud auth application-default login
```
设置项目：为后续命令配置活跃项目：
bash
```
gcloud config set project $PROJECT_ID
```
区域：在以下每个命令中始终指定
```
--region=$LOCATION_ID
```
。请勿使用
```
global
```
。如果用户未提供区域，请询问用户指定。

1. Listing Endpoints (Tier R)

1. 列出端点（Tier R）

Use this command to discover existing endpoints in a specific region and retrieve their IDs. No confirmation is required.

bash

gcloud ai endpoints list \
    --region=$LOCATION_ID

[!IMPORTANT] Always specify the
--region
. Do NOT use 'global'. Ask the user to specify if not provided.

使用此命令发现特定区域中的现有端点并获取其ID。无需确认。

bash

gcloud ai endpoints list \
    --region=$LOCATION_ID

[!IMPORTANT] 始终指定
--region
。请勿使用'global'。如果用户未提供，请询问用户指定。

2. Describing an Endpoint (Tier R)

2. 描述端点（Tier R）

Retrieve the full metadata for a specific endpoint. No confirmation is required.

bash

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

获取特定端点的完整元数据。无需确认。

bash

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

3. Creating an Endpoint (Tier M)

3. 创建端点（Tier M）

Create a new endpoint resource. The parent resource is the location. Action requires an inline confirmation card before proceeding.

bash

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

[!IMPORTANT] You MUST seek interactive confirmation first. Your confirmation prompt MUST show the literal command string. For example:
bash
gcloud ai endpoints create --region=$LOCATION_ID --display-name="my-endpoint"
Or the exact flags. Do not execute this command in the same turn as proposing the confirmation.

创建新的端点资源。父资源是区域。 操作前需要内嵌确认卡片。

bash

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

[!IMPORTANT] 您必须先寻求交互式确认。 您的确认提示必须显示完整的命令字符串。例如：
bash
gcloud ai endpoints create --region=$LOCATION_ID --display-name="my-endpoint"
或确切的参数。请勿在提出确认请求的同一轮次执行此命令。

4. Updating an Endpoint (Tier M)

4. 更新端点（Tier M）

Update endpoint metadata such as display name or labels. Action requires an inline confirmation card before proceeding.

bash

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

Check if the endpoint exists first by either listing or describing the endpoint.

[!IMPORTANT] You MUST seek interactive confirmation first. Your confirmation prompt MUST show the literal command string. For example:
bash
gcloud ai endpoints update $ENDPOINT_ID --region=$LOCATION_ID --display-name="new-display-name"
Or the exact flags. CRITICAL: You are strictly prohibited from executing this command in the same turn as asking for confirmation. When you ask for confirmation, you MUST stop immediately and wait for the user to reply.

更新端点元数据，例如显示名称或标签。 操作前需要内嵌确认卡片。

bash

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

先通过列出或描述端点来检查端点是否存在。

[!IMPORTANT] 您必须先寻求交互式确认。 您的确认提示必须显示完整的命令字符串。例如：
bash
gcloud ai endpoints update $ENDPOINT_ID --region=$LOCATION_ID --display-name="new-display-name"
或确切的参数。 至关重要：严禁在请求确认的同一轮次执行此命令。当您请求确认时，必须立即停止并等待用户回复。

5. Deleting an Endpoint (Tier D)

5. 删除端点（Tier D）

Permanently delete an endpoint resource. Action requires explicit typed confirmation before proceeding.

bash

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

[!WARNING] All models must be undeployed from the endpoint before it can be deleted. Do not run
describe
until AFTER you have received typed confirmation to delete.

永久删除端点资源。 操作前需要明确的输入确认。

bash

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

[!WARNING] 在删除端点之前，必须将所有模型从端点中卸载。在收到输入确认删除之前，请勿执行
describe
。

6. Traffic Splitting (Tier M)

6. 流量分配（Tier M）

You can manage traffic split between different models deployed on the same endpoint during an update. Action requires an inline confirmation card before proceeding.

bash

undefined

您可以在更新期间管理同一端点上部署的不同模型之间的流量分配。 操作前需要内嵌确认卡片。

bash

undefined

Example: Deploying a model with a specific traffic split is usually done

via 'gcloud ai endpoints deploy-model'.


Refer to the `agent-platform-deploy` skill for instructions on deploying and
undeploying models.


有关模型部署和卸载的说明，请参考`agent-platform-deploy`技能。

Troubleshooting

故障排查

403 Permission Denied: Ensure
```
aiplatform.admin
```
or
```
owner
```
role is assigned.
Quota Exceeded: Verify the region's endpoint quota in the Cloud Console.
Resource Busy: If a deletion fails, check if models are still being undeployed.

403权限拒绝：确保已分配
```
aiplatform.admin
```
或
```
owner
```
角色。
配额超出：在Cloud Console中验证区域的端点配额。
资源繁忙：如果删除失败，请检查是否仍有模型正在卸载中。