gemini-managed-agents-api

Gemini Enterprise Agent 平台 - 托管 Agent API 技能

本技能提供完整的说明、REST 请求端点和 JSON 载荷结构，用于以编程方式管理 Gemini Enterprise Agent 平台（Agent Platform）上的自定义 Agent 资源。

托管 Agent API 构成了平台的控制平面。它允许开发者配置、检索、更新和删除定制的有状态 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 平台的托管 Agent 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"
    }
  }
}

[高级] 挂载技能注册表资源

如需直接从技能注册表服务而非 Cloud Storage 挂载技能，请替换载荷中的 Cloud Storage 来源项：

"sources": [
  {
    "type": "skill_registry",
    "source": "projects/your-project-id/locations/global/skills/my-math-skill/revisions/123456789012",
    "target": "/.agent/skills"
  }
]

[高级] 配置模型上下文协议（MCP）服务

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

"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 查询参数指定要更新的字段。

• 方法：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）与其进行多轮聊天、工具执行和流式对话。

如需与自定义 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": [{
    "role": "user",
    "content": [{"type": "text", "text": "Hello! Who are you?"}]
  }]
}

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