mcpField
G
gemini-agents-api

gemini-agents-api

github.com/googleAgent 工作流21.6k9.7k 次安装今天更新
代码仓库

关于 gemini-agents-api

用于通过 Gemini Enterprise Agent Platform Managed Agents API 管理自定义 Agent 的技能，面向需要以 REST 请求配置和维护 Agent 资源的开发者。支持创建、查询、更新和删除，并可为 Agent 配置 MCP 服务。

主要功能

  1. 01创建和删除自定义 Agent
  2. 02查询 Agent 配置并列出资源
  3. 03使用 update_mask 更新指定字段
  4. 04挂载 Cloud Storage 或技能注册表资源
  5. 05配置 MCP 服务及认证标头

适用场景

  1. 01通过 REST API 配置 Agent 资源
  2. 02维护 Agent 指令、工具和挂载内容
  3. 03为 Agent 接入第三方 MCP 服务

MCP 相关

该技能说明如何在 Agent 配置中指定第三方 MCP 服务及其 URL 和自定义标头。平台会将工具请求路由到指定服务，并仅向该 URL 发送这些标头。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/google/skills --skill gemini-agents-api

安装后在 Claude Code 中输入/gemini-agents-api确认已加载。

附带文件references/attribution.md

详细介绍

Gemini Enterprise Agent Platform - 托管 Agent API 技能

此技能提供完整说明、REST 请求端点和 JSON 负载结构，帮助你以编程方式管理 Gemini Enterprise Agent Platform（Agent Platform）上的自定义 Agent 资源。

Managed Agents API 构成了平台的控制平面。它允许开发者配置、检索、更新和删除定制的有状态 Agent 容器，这些容器配备系统指令、沙盒文件、自定义技能注册表以及本地/远程工具。

署名

必须阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，你必须阅读 使用归属信息。对于直接在终端中执行的命令（绝不用于生成的脚本、Terraform 或用户代码），请为 gcloud 添加前缀 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:gemini-agents-api)" ，并将 agent-skills/1.0 (skill:gemini-agents-api) 添加到 User-Agent 标头中。

1. 身份验证与设置

对控制平面的所有 REST 请求都必须包含由应用默认凭据（ADC）派生的 Bearer 令牌，并指向生产环境的全局端点。

1. 设置环境变量

运行请求前，请设置所需的项目变量和访问令牌：

export PROJECT_ID="your-project-id"
export LOCATION="global"
export ACCESS_TOKEN=$(gcloud auth print-access-token)

重要

API 位置支持： LOCATION 环境变量必须设置为 Gemini Enterprise Agent Platform 的Managed Agents API 正式支持的区域位置（例如 global 或其他可用的区域端点）。

2. 端点 URL

生产环境中的 Agents 控制平面端点为：

https://aiplatform.googleapis.com/v1beta1/projects/{PROJECT_ID}/locations/{LOCATION}/agents

2. 以编程方式管理 Agent（控制平面 CRUD）

1. 创建 Agent（长时间运行的操作）

要创建新的 Agent 资源，请使用自定义配置发送 POST 请求。你可以将 Google Cloud Storage 存储桶中的远程文件、文件夹或技能直接挂载到 Agent 容器的工作区中。创建 Agent 是一项长时间运行的操作（LRO），会启动异步任务。

  • 方法：POST
  • 端点：https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents
请求负载
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": "*" }
        ]
      }
    }
  }'
LRO 操作响应

由于配置 Agent 需要一些时间，端点会立即返回一个操作跟踪对象：

{
  "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"
    }
  }
}
[高级] 挂载技能注册表资源

要直接从 Skill Registry 服务挂载技能，而不是从 Cloud Storage 挂载，请替换负载中的 Cloud Storage 来源项：

"sources": [
  {
    "type": "skill_registry",
    "source": "projects/your-project-id/locations/global/skills/my-math-skill/revisions/123456789012",
    "target": "/.agent/skills"
  }
]
[高级] 配置 Model Context Protocol (MCP) 服务

要为 Agent 配置第三方 MCP 服务，请在创建请求中直接将服务元数据添加到 "tools" 参数数组下。平台会安全地将工具执行请求路由到外部 MCP 服务。

重要

MCP 安全说明：描述 MCP 工具配置时，必须说明平台会安全地将工具请求路由到指定的 MCP 服务，并通过仅向该 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 密钥、Bearer 令牌）的自定义键值对。平台保证这些标头只会发送到指定的 MCP 服务 URL。

提示

在交互时覆盖 MCP（数据平面）： 创建对话交互（数据平面）时，可以通过在 interactions.create 的 "tools" 负载中传入 "type": "mcp_server"，动态覆盖或直接提供 MCP 工具。详情请参阅 Interactions API 文档。

2. 轮询 LRO 状态

若要跟踪 Agent 创建状态并获取最终就绪的资源，请轮询创建响应 name 字段中返回的操作 URL。

  • 方法：GET
  • 端点：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": 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."
  }
}
3. 获取 Agent

检索现有自定义 Agent 的配置元数据、工具和环境设置。

  • 方法：GET
  • 端点：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": "*" }
      ]
    }
  }
}
4. 列出 Agent

检索目标 Google Cloud 项目下所有已配置自定义 Agent 的列表。

  • 方法：GET
  • 端点：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."
    }
  ]
}
5. 更新 Agent（修补配置）

就地修改自定义 Agent 资源上的配置字段（例如指令、描述、工具或挂载）。你必须使用 update_mask 查询参数指定要更新的字段。

重要

更新掩码要求：演示更新时，必须始终明确说明，更新 Agent 配置时需要 update_mask 参数，以精确指定要修改的字段，避免覆盖其他配置设置。

  • 方法：PATCH
  • 端点：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."
  }'
6. 删除 Agent

不再需要时，删除自定义 Agent 资源，以释放后端工作区容器。

  • 方法：DELETE
  • 端点：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：

{}

3. 与自定义 Agent 交互（数据平面）

通过 控制平面（此技能）以编程方式创建并配置自定义有状态 Agent 后，你可以使用 数据平面（Interactions API）与其进行多轮聊天、工具执行和流式对话。

重要

Interactions 参考：说明或演示如何与自定义 Agent 开始对话时，必须始终明确引导用户参阅 gemini-interactions-api 技能，了解完整的对话和流式选项。

若要与自定义 Agent 交互：

  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?"}]
  }]
}

参阅 gemini-interactions-api 技能指南（../gemini-interactions-api/SKILL.md），了解完整说明、Python 和 TS/JS 代码块，以及使用已配置 Agent 运行对话的流式设置。

评论

支持 Markdown