Back to Details

gemini-managed-agents-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Gemini Enterprise Agent Platform - Managed Agents API Skill

Gemini Enterprise Agent Platform - Managed Agents API 技能

This skill provides complete instructions, REST request endpoints, and JSON payload structures to programmatically manage custom Agent resources on the Gemini Enterprise Agent Platform (Agent Platform).

The Managed Agents API forms the Control Plane of the platform. It allows developers to provision, retrieve, update, and delete tailored, stateful agent containers equipped with system instructions, sandboxed files, custom skill registries, and local/remote tools.

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

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

1. Authentication & Setup

1. 身份验证与设置

All REST requests to the Control Plane must include a Bearer token derived from Application Default Credentials (ADC), and target the production global endpoint.
所有向控制平面发送的REST请求必须包含从Application Default Credentials (ADC)获取的Bearer token，并且目标为生产环境全局端点。

1. Setup Environment Variables

1. 设置环境变量

Before running requests, set up the required project variables and access token:
bash
export PROJECT_ID="your-project-id"
export LOCATION="global"
export ACCESS_TOKEN=$(gcloud auth print-access-token)
[!IMPORTANT] API Location Support: The 
LOCATION
environment variable must be set to a regional location where the Gemini Enterprise Agent Platform's Managed Agents API is actively supported (e.g., 
global
, or other available regional endpoints).
在发送请求前，设置所需的项目变量和访问令牌：
bash
export PROJECT_ID="your-project-id"
export LOCATION="global"
export ACCESS_TOKEN=$(gcloud auth print-access-token)
[!IMPORTANT] API位置支持: 
LOCATION
环境变量必须设置为Gemini Enterprise Agent Platform的Managed Agents API当前支持的区域位置（例如
global
或其他可用的区域端点）。

2. Endpoint URL

2. 端点URL

The production Agents Control Plane endpoint is:
http
https://aiplatform.googleapis.com/v1beta1/projects/{PROJECT_ID}/locations/{LOCATION}/agents
生产环境Agents控制平面的端点为：
http
https://aiplatform.googleapis.com/v1beta1/projects/{PROJECT_ID}/locations/{LOCATION}/agents

2. Programmatic Agent Management (Control Plane CRUD)

2. 编程式Agent管理（控制平面CRUD操作）

1. Create Agent (Long-Running Operation)

1. 创建Agent（长期运行操作LRO）

To create a new agent resource, issue a 
POST
request with the custom configuration. You can mount remote files, folders, or skills directly from Google Cloud Storage buckets into the agent container's workspace. Creating an agent is a Long-Running Operation (LRO) that spawns an asynchronous job.
  • Method: 
    POST
  • Endpoint: 
    https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents
要创建新的Agent资源，发送带有自定义配置的
POST
请求。您可以直接将远程文件、文件夹或技能从Google Cloud Storage存储桶挂载到Agent容器的工作区中。创建Agent是一个长期运行操作（Long-Running Operation, LRO），会生成一个异步任务。
  • 方法: 
    POST
  • 端点: 
    https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents

Request Payload

请求负载

bash
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": "*" }
        ]
      }
    }
  }'
bash
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 Operations Response

LRO操作响应

Since agent provisioning takes a few moments, the endpoint immediately returns an operation tracking object:
json
{
  "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"
    }
  }
}
由于Agent配置需要一些时间，端点会立即返回一个操作跟踪对象：
json
{
  "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"
    }
  }
}

[Advanced] Mount Skill Registry Resources

[进阶] 挂载技能注册表资源

To mount skills directly from the Skill Registry service instead of Cloud Storage, replace the Cloud Storage source item in the payload:
json
"sources": [
  {
    "type": "skill_registry",
    "source": "projects/your-project-id/locations/global/skills/my-math-skill/revisions/123456789012",
    "target": "/.agent/skills"
  }
]
要直接从技能注册表服务挂载技能而非从Cloud Storage挂载，请替换负载中的Cloud Storage源项：
json
"sources": [
  {
    "type": "skill_registry",
    "source": "projects/your-project-id/locations/global/skills/my-math-skill/revisions/123456789012",
    "target": "/.agent/skills"
  }
]

[Advanced] Configuring Model Context Protocol (MCP) Servers

[进阶] 配置模型上下文协议（MCP）服务器

To configure Third-Party MCP servers for an agent, add the server metadata directly under the 
"tools"
parameter array inside the creation request. The platform securely routes tool execution requests to the external MCP server.
json
"tools": [
  {
    "type": "mcp",
    "name": "my-mcp-server",
    "url": "https://mcp.yourcompany.com/api",
    "headers": {
      "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN"
    }
  }
]
  • name: A descriptive name for the MCP server.
  • url: The endpoint URL of the external MCP server.
  • headers: (Optional) Custom key-value pairs containing authentication tokens (e.g. API keys, bearer tokens) required to call the server. The platform guarantees that these headers are only sent to the specified MCP server URL.
[!TIP] Overriding MCP at Interaction Time (Data Plane): You can dynamically override or supply MCP tools directly when creating a conversation interaction (Data Plane) by passing 
"type": "mcp_server"
inside the 
"tools"
payload of 
interactions.create
. Refer to the Interactions API documentation for details.
要为Agent配置第三方MCP服务器，请在创建请求的
"tools"
参数数组下直接添加服务器元数据。平台会将工具执行请求安全地路由到外部MCP服务器。
json
"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。
[!TIP] 在交互时覆盖MCP（数据平面）: 您可以在创建对话交互（数据平面）时，通过在
interactions.create
的
"tools"
负载中传递
"type": "mcp_server"
，动态覆盖或提供MCP工具。详情请参考Interactions API文档。

2. Polling the LRO Status

2. 轮询LRO状态

To track the status of agent creation and obtain the final ready resource, poll the operation URL returned in the 
name
field of the creation response.
  • Method: 
    GET
  • Endpoint: 
    https://aiplatform.googleapis.com/v1beta1/{OPERATION_NAME}
bash
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"
要跟踪Agent创建状态并获取最终就绪的资源，请轮询创建响应中
name
字段返回的操作URL。
  • 方法: 
    GET
  • 端点: 
    https://aiplatform.googleapis.com/v1beta1/{OPERATION_NAME}
bash
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"

In-Progress Response

进行中响应

json
{
  "name": "projects/1234567890/locations/global/operations/operation-987654321-abcde",
  "metadata": { ... }
}
json
{
  "name": "projects/1234567890/locations/global/operations/operation-987654321-abcde",
  "metadata": { ... }
}

Finished Success Response

成功完成响应

Once the container is ready, 
"done": true
is set, and the completed 
Agent
resource description resides inside 
"response"
:
json
{
  "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."
  }
}
容器就绪后，
"done": true
会被设置，已完成的
Agent
资源描述位于
"response"
内：
json
{
  "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. Get Agent

3. 获取Agent

Retrieve the configuration metadata, tools, and environment setup of an existing custom agent.
  • Method: 
    GET
  • Endpoint: 
    https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents/{AGENT_ID}
bash
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的配置元数据、工具和环境设置。
  • 方法: 
    GET
  • 端点: 
    https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents/{AGENT_ID}
bash
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"

Response Example

响应示例

Returns the complete configured state of the custom Agent resource:
json
{
  "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": "*" }
      ]
    }
  }
}
返回自定义Agent资源的完整配置状态：
json
{
  "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. List Agents

4. 列出Agents

Retrieve a list of all configured custom agents located under the target Google Cloud project.
  • Method: 
    GET
  • Endpoint: 
    https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents
bash
curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/agents" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json"
检索目标Google Cloud项目下所有已配置的自定义Agent列表。
  • 方法: 
    GET
  • 端点: 
    https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents
bash
curl -X GET "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/agents" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json"

Response Example

响应示例

Returns a JSON list of all configured custom Agents under the target project:
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的JSON列表：
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. Update Agent (Patching Configuration)

5. 更新Agent（补丁配置）

Modify configuration fields (such as instructions, descriptions, tools, or mounts) on a custom agent resource in place. You must specify the fields being updated using the 
update_mask
query parameter.
  • Method: 
    PATCH
  • Endpoint: 
    https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents/{AGENT_ID}?update_mask=system_instruction
bash
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."
  }'
就地修改自定义Agent资源的配置字段（例如指令、描述、工具或挂载）。您必须使用
update_mask
查询参数指定要更新的字段。
  • 方法: 
    PATCH
  • 端点: 
    https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents/{AGENT_ID}?update_mask=system_instruction
bash
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. Delete Agent

6. 删除Agent

Delete custom Agent resources when they are no longer needed to free up backend workspace containers.
  • Method: 
    DELETE
  • Endpoint: 
    https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents/{AGENT_ID}
bash
curl -X DELETE "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/agents/my-custom-agent" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"
当自定义Agent资源不再需要时，将其删除以释放后端工作区容器。
  • 方法: 
    DELETE
  • 端点: 
    https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/agents/{AGENT_ID}
bash
curl -X DELETE "https://aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/global/agents/my-custom-agent" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"

Response Example

响应示例

A successful deletion request returns an empty JSON response body with HTTP Status 
200 OK
:
json
{}
成功的删除请求会返回空的JSON响应体，HTTP状态码为
200 OK
：
json
{}

3. Interacting with Custom Agents (Data Plane)

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

Once you have programmatically created and provisioned your custom stateful agent using the Control Plane (this skill), you can execute multi-turn chat, tool execution, and streaming conversations with it using the Data Plane (Interactions API).
To interact with your custom agent:
  1. Obtain your agent's resource path name (e.g., 
    projects/{PROJECT_ID}/locations/global/agents/{AGENT_ID}
    ).
  2. Pass this resource path directly inside your data plane conversation requests under the 
    agent
     parameter.
使用控制平面（本技能）以编程方式创建并配置好自定义有状态Agent后，您可以使用数据平面（Interactions API）与其执行多轮聊天、工具执行和流式对话。
要与自定义Agent交互：
  1. 获取您的Agent资源路径名称（例如
    projects/{PROJECT_ID}/locations/global/agents/{AGENT_ID}
    ）。
  2. 在数据平面对话请求的**
    agent
    **参数中直接传递此资源路径。

Python Example

Python示例

python
interaction = client.interactions.create(
    agent="projects/your-project-id/locations/global/agents/my-custom-agent",
    input="Hello! Who are you?"
)
python
interaction = client.interactions.create(
    agent="projects/your-project-id/locations/global/agents/my-custom-agent",
    input="Hello! Who are you?"
)

REST / curl Example

REST / curl示例

json
{
  "agent": "projects/your-project-id/locations/global/agents/my-custom-agent",
  "input": [{
    "role": "user",
    "content": [{"type": "text", "text": "Hello! Who are you?"}]
  }]
}
Refer to the 
gemini-interactions-api
 skill guide (
../gemini-interactions-api/SKILL.md
) for full instructions, Python and TS/JS code blocks, and streaming setups to run conversations with your provisioned agents.
json
{
  "agent": "projects/your-project-id/locations/global/agents/my-custom-agent",
  "input": [{
    "role": "user",
    "content": [{"type": "text", "text": "Hello! Who are you?"}]
  }]
}
请参考**
gemini-interactions-api
**技能指南（
../gemini-interactions-api/SKILL.md
）获取完整说明、Python和TS/JS代码块以及流式设置，以便与已配置的Agent进行对话。