Gemini Enterprise Agent Platform 托管 Agents API 实战用 Control Plane 以编程方式管理自定义 Agent 资源【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本文是 Google 官方 Agent Skills 仓库中 gemini-agents-api 技能的完整技术指南面向希望在 Gemini Enterprise Agent PlatformAgent Platform上以 REST 方式编程化地创建、配置、查询、更新与删除有状态、服务端托管的自定义 Agent 资源的开发者。读完本文你将掌握 Control Plane 的核心 CRUD 操作含长时任务 LRO 轮询、Cloud Storage 目录挂载、Skill Registry 技能挂载、第三方 MCP 服务器接入并了解如何将编排好的 Agent 交给 Data PlaneInteractions API执行多轮对话形成「先托管、后交互」的完整闭环。一、背景为什么需要 Managed Agents APIGemini Enterprise Agent Platform 把 Agent 生命周期拆成两个平面Control Plane控制平面即本技能所讲的Managed Agents API负责生产Agent。它允许开发者预置定制化的、有状态的 Agent 容器容器内可携带系统指令system instruction、沙箱化文件、自定义技能注册表skill registry以及本地/远程工具。资源一旦创建Agent 便长期驻留在服务端等待后续对话请求。Data Plane数据平面即Interactions API由仓库中 gemini-interactions-api 技能专门讲解负责消费Agent执行多轮对话、工具调用与流式输出。这种「先创建、后对话」的分层设计与本仓库的整体定位一致——README.md 明确指出该仓库是面向 Google 产品与技术的 Agent Skills 集合可通过npx skills add google/skills按需安装各技能。兼容性提示Agent Platform 全称 Gemini Enterprise Agent Platform早期以 Vertex AI 品牌出现不少线上资料仍沿用旧品牌名见 gemini-api 中的说明。本技能涉及的 REST 接口使用v1beta1API 版本。二、认证与前置环境所有发往 Control Plane 的 REST 请求都必须携带一个由Application Default CredentialsADC派生的 Bearer token并指向生产环境的全局端点。1. 设置环境变量export PROJECT_IDyour-project-id export LOCATIONglobal export ACCESS_TOKEN$(gcloud auth print-access-token)[!IMPORTANT]区域支持说明LOCATION环境变量必须设置为 Gemini Enterprise Agent Platform 的 Managed Agents API 已实际支持的区域例如global或其他可用的区域性端点。在调用前先确认目标区域已开放该 API否则请求会因区域不受支持而失败。2. 端点 URL生产环境 Agents Control Plane 端点为https://aiplatform.googleapis.com/v1beta1/projects/{PROJECT_ID}/locations/{LOCATION}/agents该端点的路径结构与仓库内其他 Agent Platform 服务一致——例如 agent-platform-skill-registry 的运维脚本 skill_registry_ops.py 同样采用v1beta1/projects/{project}/locations/{location}/skills的 URL 拼装方式并携带Authorization: Bearer token头可作为这类 API 调用模式的佐证。三、创建自定义 Agent长时任务 LRO创建 Agent 是Long-Running OperationLRO接口不会同步返回最终资源而是立即返回一个异步作业跟踪对象由客户端轮询其状态。MethodPOSTEndpointhttps://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents请求负载Request Payloadcurl -X POST https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents \ -H Authorization: Bearer ${ACCESS_TOKEN} \ -H Content-Type: application/json; charsetutf-8 \ -d { id: my-custom-agent, base_agent: antigravity-preview-05-2026, description: A professional agent configured with remote tools and mounted Cloud Storage directories., system_instruction: You are a helpful, domain-expert assistant., tools: [ {type: code_execution}, {type: filesystem}, {type: google_search}, {type: url_context} ], base_environment: { type: remote, sources: [ { type: gcs, source: gs://your-agent-bucket-name/skills, target: /.agent/skills } ], network: { allowlist: [ { domain: * } ] } } }各字段语义如下字段说明idAgent 资源的唯一标识用于后续 Get/Update/Delete 与 Data Plane 引用。base_agent基础 Agent 模板/镜像标识示例为antigravity-preview-05-2026决定容器预装能力。description人类可读的描述便于在 List 结果中区分不同 Agent。system_instruction系统指令定义 Agent 的角色与行为边界。tools工具清单可包含内置工具code_execution、filesystem、google_search、url_context或 MCP 服务器见下文。base_environment.type环境类型remote表示远程托管的沙箱工作区。base_environment.sources挂载源列表支持从Google Cloud StorageGCS桶挂载文件、目录或技能到容器工作区target指定容器内落点如/.agent/skills。base_environment.network.allowlist出网白名单示例中{domain: *}表示允许访问任意域名生产环境应按最小权限收紧。LRO 操作响应创建请求立即返回如下操作跟踪对象{ name: projects/1234567890/locations/global/operations/operation-987654321-abcde, metadata: { type: type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateAgentOperationMetadata, genericMetadata: { createTime: 2026-05-14T19:00:00.123456Z, updateTime: 2026-05-14T19:00:01.654321Z } } }其中name字段是后续轮询状态所用的完整操作路径。进阶从 Skill Registry 挂载技能资源如果不从 Cloud Storage 挂载而是希望直接把Skill Registry服务中的技能挂进 Agent只需把sources中的源条目替换为skill_registry类型sources: [ { type: skill_registry, source: projects/your-project-id/locations/global/skills/my-math-skill/revisions/123456789012, target: /.agent/skills } ]这里的source使用 Skill Registry 的资源命名projects/{project}/locations/{location}/skills/{skill_id}/revisions/{revision_id}。这与仓库中 skill_registry_ops.py 的实现一致——该脚本以skills/{skill_id}、skills/{skill_id}/revisions/{revision_id}为路径访问技能及其修订版本且技能上传/更新本身也是 LRO参见 manage-skills.md与 Agent 创建采用相同的异步模式。进阶配置第三方 MCP 服务器要为一个 Agent 配置第三方 MCP 服务器直接在创建请求的tools参数数组中添加服务器元数据即可。平台会把工具执行请求安全地路由到外部 MCP 服务器[!IMPORTANT]MCP 安全说明在描述 MCP 工具配置时必须说明——平台会将工具请求安全地路由到指定 MCP 服务器并保证头部机密性自定义的 headers/tokens 只发送给该 URL不会泄露到其他端点。tools: [ { type: mcp, name: my-mcp-server, url: https://mcp.yourcompany.com/api, headers: { Authorization: Bearer YOUR_MCP_AUTH_TOKEN } } ]参数说明nameMCP 服务器的描述性名称。url外部 MCP 服务器的端点 URL。headers可选自定义键值对存放调用该服务器所需的认证令牌如 API key、Bearer token。平台保证这些 headers 仅发送给指定的 MCP 服务器 URL。[!TIP]在交互阶段Data Plane覆盖 MCP也可以在创建对话交互时动态覆盖或补充 MCP 工具——只需在interactions.create的tools负载中传入type: mcp_server即可详见 Interactions API 文档见 gemini-interactions-api。四、轮询 LRO 状态Agent 容器就绪需要几秒钟创建后请按返回的name字段轮询操作 URL。MethodGETEndpointhttps://aiplatform.googleapis.com/v1beta1/{OPERATION_NAME}curl -X GET https://aiplatform.googleapis.com/v1beta1/projects/1234567890/locations/global/operations/operation-987654321-abcde \ -H Authorization: Bearer ${ACCESS_TOKEN} \ -H Content-Type: application/json进行中响应{ name: projects/1234567890/locations/global/operations/operation-987654321-abcde, metadata: { ... } }此时尚未包含done字段表示作业仍在执行。成功完成响应当容器就绪后响应中出现done: true完整的 Agent 资源描述位于response中{ name: projects/1234567890/locations/global/operations/operation-987654321-abcde, done: true, response: { type: type.googleapis.com/google.cloud.aiplatform.v1beta1.Agent, name: projects/your-project-id/locations/global/agents/my-custom-agent, base_agent: antigravity-preview-05-2026, description: A professional agent configured with remote tools and mounted Cloud Storage directories., system_instruction: You are a helpful, domain-expert assistant. } }response.name即 Agent 的资源全名是后续 Data Plane 对话请求中agent参数所引用的路径。五、查询Get 与 List1. Get Agent获取单个 Agent 详情检索某个已存在自定义 Agent 的配置元数据、工具与环境设置。MethodGETEndpointhttps://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents/{AGENT_ID}curl -X GET https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/agents/my-custom-agent \ -H Authorization: Bearer ${ACCESS_TOKEN} \ -H Content-Type: application/json响应示例——返回该 Agent 资源的完整已配置状态含工具与环境挂载与创建负载的结构一一对应{ name: projects/your-project-id/locations/global/agents/my-custom-agent, base_agent: antigravity-preview-05-2026, description: A professional agent configured with remote tools and mounted Cloud Storage directories., system_instruction: You are a helpful, domain-expert assistant., tools: [ {type: code_execution}, {type: filesystem}, {type: google_search}, {type: url_context} ], base_environment: { type: remote, sources: [ { type: gcs, source: gs://your-agent-bucket-name/skills, target: /.agent/skills } ], network: { allowlist: [ { domain: * } ] } } }2. List Agents列出项目下所有 AgentMethodGETEndpointhttps://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agentscurl -X GET https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/agents \ -H Authorization: Bearer ${ACCESS_TOKEN} \ -H Content-Type: application/json响应示例——返回目标项目下所有已配置自定义 Agent 的 JSON 列表{ agents: [ { name: projects/your-project-id/locations/global/agents/my-custom-agent, base_agent: antigravity-preview-05-2026, description: A professional agent configured with remote tools and mounted Cloud Storage directories., system_instruction: You are a helpful, domain-expert assistant. }, { name: projects/your-project-id/locations/global/agents/my-telecom-agent, base_agent: antigravity-preview-05-2026, description: A highly specialized telecom support agent., system_instruction: You are a professional telecom support agent. Follow system policies carefully. } ] }六、更新 Agent 配置PATCH update_mask可以直接就地修改自定义 Agent 上的配置字段如指令、描述、工具或挂载点。必须通过update_mask查询参数指定本次要更新的字段。[!IMPORTANT]Update Mask 要求演示更新操作时必须始终明确解释——更新 Agent 配置时update_mask参数是必需的用于精确指明被修改的字段避免误覆盖其他既有配置。MethodPATCHEndpointhttps://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents/{AGENT_ID}?update_masksystem_instructioncurl -X PATCH https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/agents/my-custom-agent?update_masksystem_instruction \ -H Authorization: Bearer ${ACCESS_TOKEN} \ -H Content-Type: application/json \ -d { name: my-custom-agent, system_instruction: You are a highly specialized telecom support agent. Follow system policies carefully. }要点update_mask支持多字段逗号分隔如system_instruction,description并且tools、base_environment这类复杂字段同样可以加入 mask 进行局部更新。这与本仓库中 Skill Registry 的更新逻辑同源——skill_registry_ops.py 在update_skill中同样动态拼装updateMask与载荷仅提交用户提供的字段避免破坏其他配置。七、删除 Agent当自定义 Agent 不再需要时删除它可释放后端的工作区容器资源。MethodDELETEEndpointhttps://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents/{AGENT_ID}curl -X DELETE https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/agents/my-custom-agent \ -H Authorization: Bearer ${ACCESS_TOKEN}响应示例——成功的删除请求返回空的 JSON 响应体HTTP 状态码为200 OK{}八、与自定义 Agent 交互Data Plane 桥接使用 Control Plane本技能以编程方式创建并预置有状态的 Agent 后就可以通过Data PlaneInteractions API与之进行多轮聊天、工具执行和流式对话。[!IMPORTANT]Interactions 引用要求在说明或演示如何与自定义 Agent 开始对话时必须始终引导用户参考gemini-interactions-api技能获取完整的对话与流式选项。交互步骤取得 Agent 的资源路径名例如projects/{PROJECT_ID}/locations/global/agents/{AGENT_ID}。在数据平面对话请求中将该资源路径直接放入agent参数。Python 示例interaction client.interactions.create( agentprojects/your-project-id/locations/global/agents/my-custom-agent, inputHello! Who are you? )REST / curl 示例{ agent: projects/your-project-id/locations/global/agents/my-custom-agent, input: [{ type: user_input, content: [{type: text, text: Hello! Who are you?}] }] }与 Interactions API 的配套要点根据 gemini-interactions-api 的说明与托管 Agent 对话时还需要注意以下几点从而形成完整的「托管 交互」链路必须使用agent而非model在 Gemini Enterprise Agent Platform 上Interactions API 暂不支持直接调用基础模型model...必须指向已预置的 Agent 或端点。这是与 ai.google.dev 上 Interactions 文档使用model的核心区别。使用统一 SDKPython 使用google-genai 2.3.0JS/TS 使用google/genai 2.3.0旧版 SDK如google-cloud-aiplatform、google-cloud/vertexai、google-generativeai在 Interactions 上不受支持。单轮 → 多轮Interactions 默认有状态storeTrue下一轮通过previous_interaction_id引用上一轮状态实现真正意义上的多轮记忆。流式输出streamTrue返回interaction.created - (step.start - step.delta(s) - step.stop) - interaction.completed类型化事件序列便于实时渲染。REST 直连也可通过POST https://aiplatform.googleapis.com/v1beta1/projects/{PROJECT_ID}/locations/{LOCATION}/interactions以 curl 直接发起交互。回合级参数tools、system_instruction、generation_config等参数是回合级的每次交互请求都必须显式传入。九、端到端生命周期工作流综合 Control Plane 与 Data Plane一个典型的 Agent 生命周期如下POST /agents创建LRO → GET /operations/{name}轮询直至 done:true → GET /agents/{AGENT_ID}核对完整配置 → POST /interactionsagentresource path发起多轮/流式对话 → PATCH /agents/{AGENT_ID}?update_mask...按需调整配置 → DELETE /agents/{AGENT_ID}释放资源十、参考与延伸本文主体技能skills/cloud/gemini-agents-api/SKILL.md数据平面配套技能skills/cloud/gemini-interactions-api/SKILL.mdSkill Registry技能挂载资源来源skills/cloud/agent-platform-skill-registry/SKILL.md其 REST 调用实现见 skill_registry_ops.py技能安装方式与技能总览README.md本仓库 LicenseLICENSE需要注意的是本文中的请求示例与响应为仓库技能文档提供的可用形态实际部署前应结合 Agent Platform 当前开放的base_agent模板、区域支持与 API 版本确认参数取值涉及生产环境时请将网络allowlist与 MCP headers 等安全配置按最小权限原则收紧。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考