☰

企业官网建设流程全解析

首页 / 建站日记 / 企业官网建设流程全解析
Gemini Enterprise Agent Platform 托管 Agents API 实战：用 Control Plane 以编程方式管理自定义 Agent 资源
2026/9/13 11:50:57 网站建设 项目流程

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 Platform（Agent Platform）上以 REST 方式编程化地创建、配置、查询、更新与删除有状态、服务端托管的自定义 Agent 资源的开发者。读完本文，你将掌握 Control Plane 的核心 CRUD 操作（含长时任务 LRO 轮询、Cloud Storage 目录挂载、Skill Registry 技能挂载、第三方 MCP 服务器接入），并了解如何将编排好的 Agent 交给 Data Plane（Interactions API）执行多轮对话，形成「先托管、后交互」的完整闭环。

一、背景：为什么需要 Managed Agents API

Gemini 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 Credentials（ADC）派生的 Bearer token，并指向生产环境的全局端点。

1. 设置环境变量

export PROJECT_ID="your-project-id" export LOCATION="global" 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 Operation（LRO）：接口不会同步返回最终资源，而是立即返回一个异步作业跟踪对象，由客户端轮询其状态。

  • Method：POST
  • Endpoint：https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents

请求负载（Request Payload）

curl -X POST "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "Content-Type: application/json; charset=utf-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 Storage（GCS）桶挂载文件、目录或技能到容器工作区，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" } } ]

参数说明：

  • name：MCP 服务器的描述性名称。
  • 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。

  • Method：GET
  • Endpoint：https://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 与 List

1. Get Agent：获取单个 Agent 详情

检索某个已存在自定义 Agent 的配置元数据、工具与环境设置。

  • Method：GET
  • Endpoint：https://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：列出项目下所有 Agent

  • Method：GET
  • Endpoint：https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents
curl -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参数是必需的，用于精确指明被修改的字段，避免误覆盖其他既有配置。

  • Method：PATCH
  • Endpoint：https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents/{AGENT_ID}?update_mask=system_instruction
curl -X PATCH "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/agents/my-custom-agent?update_mask=system_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 不再需要时，删除它可释放后端的工作区容器资源。

  • Method：DELETE
  • Endpoint：https://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 Plane（Interactions API）与之进行多轮聊天、工具执行和流式对话。

[!IMPORTANT]Interactions 引用要求：在说明或演示如何与自定义 Agent 开始对话时，必须始终引导用户参考gemini-interactions-api技能获取完整的对话与流式选项。

交互步骤

  1. 取得 Agent 的资源路径名（例如projects/{PROJECT_ID}/locations/global/agents/{AGENT_ID}）。
  2. 在数据平面对话请求中，将该资源路径直接放入agent参数。

Python 示例

interaction = client.interactions.create( agent="projects/your-project-id/locations/global/agents/my-custom-agent", input="Hello! 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=）的核心区别。
  • 使用统一 SDK：Python 使用google-genai >= 2.3.0，JS/TS 使用@google/genai >= 2.3.0；旧版 SDK（如google-cloud-aiplatform、@google-cloud/vertexai、google-generativeai）在 Interactions 上不受支持。
  • 单轮 → 多轮：Interactions 默认有状态（store=True），下一轮通过previous_interaction_id引用上一轮状态，实现真正意义上的多轮记忆。
  • 流式输出：stream=True返回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 /interactions（agent=<resource path>，发起多轮/流式对话） → PATCH /agents/{AGENT_ID}?update_mask=...（按需调整配置） → DELETE /agents/{AGENT_ID}（释放资源）

十、参考与延伸

  • 本文主体技能：skills/cloud/gemini-agents-api/SKILL.md
  • 数据平面配套技能：skills/cloud/gemini-interactions-api/SKILL.md
  • Skill Registry（技能挂载资源来源）：skills/cloud/agent-platform-skill-registry/SKILL.md，其 REST 调用实现见 skill_registry_ops.py
  • 技能安装方式与技能总览：README.md
  • 本仓库 License：LICENSE

需要注意的是，本文中的请求示例与响应为仓库技能文档提供的可用形态，实际部署前应结合 Agent Platform 当前开放的base_agent模板、区域支持与 API 版本确认参数取值；涉及生产环境时，请将网络allowlist与 MCP headers 等安全配置按最小权限原则收紧。

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

标签： 网站建设 企业官网 项目流程 UI设计 前端开发

热门文章

文章分类

标签云

网站建设 响应式设计 用户体验 SEO优化 前端开发 小程序 电商平台 性能优化

相关文章

您可能感兴趣的其他内容

电力系统调频与Simulink建模实践
2026/9/13 11:50:13 网站建设

电力系统调频与Simulink建模实践

1. 电力系统调频的基本概念与挑战 电力系统频率稳定是电网安全运行的核心指标之一。当发电功率与用电负荷出现瞬时不平衡时&#xff0c;系统频率就会发生波动。传统电力系统中&#xff0c;火电机组通过调速器实现的一次调频和通过自动发电控制&#xff08;AGC&#xff09;实现的…...

阅读更多 →
ZYNQ-7020实战入门：Vitis+PetaLinux+SD卡启动全流程
2026/9/13 11:50:00 网站建设

ZYNQ-7020实战入门：Vitis+PetaLinux+SD卡启动全流程

1. 这不是“教科书”&#xff0c;而是一份从焊锡烟味里熬出来的ZYNQ入门实录你手头刚拆封的那块正点原子领航者开发板&#xff0c;板子背面还带着出厂时的防静电膜&#xff0c;USB线插在电脑上&#xff0c;Vitis软件界面弹出“Project Creation Wizard”——这时候最要命的不是…...

阅读更多 →
Vector 安全策略全解：从代码治理、供应链防护到漏洞披露的工程实践
2026/9/13 11:49:49 网站建设

Vector 安全策略全解：从代码治理、供应链防护到漏洞披露的工程实践

Vector 安全策略全解&#xff1a;从代码治理、供应链防护到漏洞披露的工程实践 【免费下载链接】vector A high-performance observability data pipeline. 项目地址: https://gitcode.com/GitHub_Trending/vect/vector 导读 本文基于 Vector 官方安全策略&#xff08;…...

阅读更多 →

需要专业的网站建设服务？

联系我们获取免费的网站建设咨询和方案报价，让我们帮助您实现业务目标

立即咨询