
Agent Platform 端点管理实战指南基于 gcloud CLI 的 Endpoint 全生命周期操作与安全确认机制【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本指南以 agent-platform-endpoint-management 技能文档为核心系统讲解 Google Cloud Agent Platform 中 serving endpoint在线预测端点的创建、查询、更新与删除等全生命周期管理操作并完整呈现该技能内置的三级安全确认机制Tier R / Tier M / Tier D。读完本文你将掌握 endpoint 与模型部署之间的先后关系、gcloud ai endpoints系列命令的完整用法与分页参数以及如何在 Agent 场景下规范、安全地执行变更类与销毁类操作并知晓如何与模型部署、在线推理等相邻技能衔接协作。Endpoint 是什么模型部署前的必要前置资源Agent Platform 中Endpoint 是逻辑上的 serving host服务宿主它对外提供一个稳定的 URL 用于在线预测online prediction。同一个 endpoint 上可以部署多个模型并通过流量切分traffic splitting控制各模型收到的请求比例。关键约束原文明确强调必须先创建 endpoint才能向其中部署模型deploy a model。因此 endpoint 管理与模型部署是两个强耦合但职责不同的阶段——endpoint 管理技能负责资源的创建与维护而模型上/下线由 agent-platform-deploy 技能负责。从技能元数据看本技能适用于以下场景创建create、列出list、描述describe、更新update、删除deleteserving endpoint排查 endpoint 相关的权限permission、配额quota或资源占用resource busy类错误。同时它明确划定了边界不用于向 endpoint 部署模型也不用于运行模型评估后者属于agent-platform-eval-flywheel。这种职责分离是该技能体系的显著设计——每个技能只解决一个窄领域问题。三级安全确认机制Agent 执行前的硬性规则技能开篇即定义了一套Safety Confirmation Tiers安全确认分级这是整套操作流程的行为红线按操作的破坏性从低到高分为三档层级覆盖动作确认要求Tier R只读list、describe、get无需确认立即执行以收集信息Tier M变更且可逆create、update需要交互式确认Yes/No 选项确认提示中必须包含字面量命令字符串含全部必需参数如--regionus-central1、--display-name...不允许用自然语言转述代替同轮次限制展示确认提示的同一轮内严禁执行命令必须停下等待用户回复Tier D销毁且不可逆delete需要显式输入确认例如用户必须输入 I confirm 或 Yes, delete it确认请求必须在任何预检动作describe、检查 endpoint 是否为空之前立即发出同样受同轮次限制约束这套分级与仓库中其他技能如 agent-platform-deploy、gcloud的安全体系一脉相承变更类操作必须人机确认、销毁类操作必须显式书面确认、只读类操作放行执行。对于 Agent 自动化场景这能有效防止因幻觉生成的命令被静默执行而造成的不可逆损失。Phase 0环境初始化任何命令之前必做在执行任何gcloud ai endpoints命令前必须完成环境初始化# 1. 登录 Google Cloud 账号并为 Agent Platform 配置活跃的 ADCApplication Default Credentials gcloud auth login gcloud auth application-default login # 2. 设置活跃项目 gcloud config set project $PROJECT_ID其中$PROJECT_ID为你的 Google Cloud 项目 ID。第三条硬性约定每条命令都必须显式携带--region$LOCATION_ID禁止使用global。如果用户没有提供 region应主动向用户询问而不是自行猜测。这一约定与 gcloud 技能中的 Project and Location Scoping 原则一致Google Cloud 的许多资源是区域级的省略位置参数会触发交互式选择提示导致无 TTY 环境下命令挂起同时显式指定区域可以避免误操作到错误的资源范围。列出与描述 EndpointTier R 只读操作1. 列出 Endpoint发现现有端点使用gcloud ai endpoints list发现指定区域内已存在的 endpoint 并获取其 ID。该操作属于 Tier R无需确认即可执行gcloud ai endpoints list \ --region$LOCATION_ID分页与数据裁剪参数原文明确给出--limit$LIMIT限制返回的 endpoint 总数分页时必用--page-size$PAGE_SIZE控制 API 每次请求的块大小chunking--page-token$PAGE_TOKEN用于获取下一页结果。[!IMPORTANT] 始终指定--region不要使用global。若用户未提供须先询问用户。结合 gcloud 技能的Data Reduction数据精简强制规则Agent 在执行 list 类命令时还应当考虑追加--format投影或--filter过滤避免无约束 list 把大量冗余 JSON 灌入上下文窗口。例如gcloud ai endpoints list --region$LOCATION_ID --limit10 --formatjson(name, displayName)而在 agent-platform-inference 技能中gcloud ai endpoints list被进一步定位为唯一的权威活跃端点来源single source of truth——判断一个 tuned 模型或自部署模型是否处于可服务状态必须以该命令的实时输出为准不能依赖历史记录中已失效的 endpoint 标识。2. 描述 Endpoint获取完整元数据获取某个具体 endpoint 的完整元数据。同样属于 Tier R无需确认gcloud ai endpoints describe $ENDPOINT_ID \ --region$LOCATION_ID该命令的输出价值远超看一眼在 agent-platform-inference 的 Custom Endpoints 章节中正是通过gcloud ai endpoints describe ENDPOINT_ID --regionREGION --formatjson来判定deployedModels[].model字段决定调用方法——含gemini走:generateContent匹配 OSS 发布方meta/、google/gemma-、deepseek-ai/、qwen/等走/chat/completions否则大概率走:predictdedicatedEndpointDns字段决定调用域名——非空表示专用端点dedicated endpoint必须使用该 DNS 而非共享的REGION-aiplatform.googleapis.com主机为空则表示共享端点使用共享主机。同理agent-platform-eval-flywheel 在评估 BYOMBring-Your-Own-Model端点前也会先执行gcloud ai endpoints describe确认端点存在并捕获dedicatedEndpointDns以传给scripts/endpoint_evaluation.py的--dedicated_endpoint_dns参数。其底层调用逻辑可见于 endpoint_evaluation.pyrun_inference以chatCompletions请求格式向端点 URL POST 请求并从predictions[].choices[0].message.content解析模型响应。可见describe 拿到 ID 与 DNS → 构造请求是端点推理的标准链路。创建 EndpointTier M 变更操作创建一个新的 endpoint 资源其父资源parent resource是 location区域。执行前必须给出内联确认卡片。gcloud ai endpoints create \ --region$LOCATION_ID \ --display-namemy-endpoint[!IMPORTANT]必须先寻求交互式确认。确认提示必须展示字面量命令字符串例如gcloud ai endpoints create --region$LOCATION_ID --display-namemy-endpoint或展示完全一致的参数。禁止在提出确认的同一轮次内执行该命令。--display-name是端点的展示名称建议使用有业务语义的命名。在跨项目复制并部署 1PFirst-PartyTuned 模型的场景中见 copy_deploy_guide.md端点命名惯例为${publisher_model_id-tuned}如gemini-3-flash-tuned默认值为copy-tuned——创建后用gcloud ai endpoints list --filterdisplay_name${NAME}反查新端点的数字 ID形如projects/${PROJECT_NUMBER}/locations/${REGION}/endpoints/${NEW_ENDPOINT_ID}供后续部署使用。创建 endpoint 时还可以考虑是否启用专用端点dedicated endpoint根据 agent-platform-inference 对dedicated_endpoint_enabled的说明一旦启用专用端点请求将无法再通过共享 DNS 发送必须改用专属的dedicatedEndpointDns格式为ENDPOINT_ID.REGION-PROJECT_NUM.prediction.vertexai.goog。因此在创建阶段就要根据模型流量需求规划好端点类型。更新 EndpointTier M 变更操作更新 endpoint 的元数据如 display name 或 labels标签。执行前必须给出内联确认卡片。gcloud ai endpoints update $ENDPOINT_ID \ --region$LOCATION_ID \ --display-namenew-display-name前置检查先通过list或describe确认 endpoint 确实存在再进行更新。[!IMPORTANT]必须先寻求交互式确认。确认提示必须展示字面量命令字符串例如gcloud ai endpoints update $ENDPOINT_ID --region$LOCATION_ID --display-namenew-display-name或展示完全一致的参数。关键约束严禁在询问确认的同一轮次内执行该命令。当发出确认请求后必须立即停下并等待用户回复。除了显示名称与标签update还被用于启用安全类能力。在 google-cloud-solution-hybrid-search-alloydb 的架构建议中可以看到gcloud ai endpoints update也用于在 AI 端点上启用 Model Armor模型防护可见 update 是端点运行期配置调整的统一入口。删除 EndpointTier D 销毁操作永久删除一个 endpoint 资源。执行前必须获得显式输入的确认。gcloud ai endpoints delete $ENDPOINT_ID \ --region$LOCATION_ID[!WARNING] 删除前endpoint 上所有模型必须已解除部署undeployed。在收到用户显式输入确认之前不要先执行describe即不要先做预检。确认方式示例用户必须显式输入 I confirm 或 Yes, delete it 之类的内容Agent 才能继续。这一先确认、后预检的顺序设计非常关键删除是彻底且不可逆的技能刻意禁止 Agent 在执行删除前先去查询端点状态——因为预检动作本身会消耗时间、产生歧义而销毁操作一旦误触发后果严重。在 agent-platform-deploy 的清理脚本中端点的删除同样要求先 undeploy-model 再 delete endpoint且--quiet标志在脚本化清理时被使用以避免交互挂起。流量切分Traffic SplittingTier M 变更操作可以在一次 update 过程中管理部署在同一个 endpoint 上不同模型之间的流量切分traffic split。该操作属于 Tier M执行前必须给出内联确认卡片# 示例以指定流量切分部署模型通常通过 gcloud ai endpoints deploy-model 完成流量切分的核心用途是灰度发布与 A/B 测试让新版本模型承接小比例流量观察效果后再逐步放量。其详细操作deploy-model及undeploy-model不在本技能范围内应转交 agent-platform-deploy 技能处理——该技能完整覆盖从 Model Garden 发现可部署模型gcloud ai model-garden models list与list-deployment-config、部署成本估算scripts/calculate_cost.py、异步部署与状态轮询到解除部署与资源清理的整条链路。从源码结构看这也是技能仓库刻意做的职责拆分endpoint 生命周期管理归本技能模型生命周期管理归 deploy 技能两者通过deploy-model/undeploy-model命令衔接。常见故障排查技能针对三类高频错误给出了明确处置路径403 Permission Denied权限拒绝确保账号被授予aiplatform.admin或owner角色。这与 copy_deploy_guide.md 中若 P4SA 绑定失败可尝试为用户账号在目标项目添加roles/aiplatform.admin的兜底方案相互印证——aiplatform.admin是 Agent Platform 资源管理所需的核心角色。Quota Exceeded配额超限到 Cloud Console 核对所选区域的 endpoint 配额。注意 endpoint 配额是按区域核算的跨区域迁移或选择配额更充裕的区域是常见解法。Resource Busy资源占用若删除失败检查是否有模型仍在解除部署undeploy过程中。正如上文所述endpoint 上存在已部署模型时无法删除必须先等待 undeploy 完成。与相邻技能的完整协作链路理解本技能在仓库技能体系中的位置有助于在实际工作中正确路由任务。从技能元数据与源码交叉验证可以总结出如下分工场景应使用的技能关键命令/入口创建/列出/描述/更新/删除 endpoint本技能agent-platform-endpoint-managementgcloud ai endpoints create/list/describe/update/delete部署/解除部署模型、成本估算、部署状态agent-platform-deploygcloud ai model-garden models deploy、gcloud ai endpoints undeploy-model、scripts/calculate_cost.py对已部署端点发起推理调用agent-platform-inferencegcloud ai endpoints describe获取dedicatedEndpointDns按模型类型选择:generateContent//chat/completions/:predict端点级模型评估agent-platform-eval-flywheelgcloud ai endpoints describescripts/endpoint_evaluation.pygcloud 命令语法验证与安全护栏gcloud执行前先gcloud help leaf_command验证叶子级语法其中一条值得强调的实操链路是describe 驱动推理gcloud ai endpoints describe $ENDPOINT_ID --region$LOCATION_ID --formatjson输出中的deployedModels[].model与dedicatedEndpointDns字段直接决定后续推理请求走哪个方法、打哪个域名详见 agent-platform-inference 第 4 节。这意味着本技能提供的 describe/list 能力是整个 Agent Platform 在线推理与评估工作流的事实基础。总结本文围绕 agent-platform-endpoint-management 完整复现了 Agent Platform endpoint 管理的全部核心内容endpoint 与模型部署的前置依赖关系、Tier R/M/D 三级安全确认机制、环境初始化三步骤、gcloud ai endpoints的 list/describe/create/update/delete 全命令族含分页参数--limit/--page-size/--page-token、流量切分的概念与边界以及权限/配额/资源占用三类故障的处置方法并结合仓库中的 gcloud、agent-platform-deploy、agent-platform-inference 与 agent-platform-eval-flywheel 技能做了源码级交叉印证。掌握这套命令与安全规范即可在 Agent 自动化场景下安全、合规地完成 endpoint 的完整生命周期管理并为后续的模型部署、在线推理与质量评估打下坚实基础。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考