Back to Details

gemini-agents-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Gemini Enterprise Agent Platform - Agents API Skill

Gemini Enterprise Agent平台 - 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 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平台（Agent平台）上以编程方式管理自定义Agent资源。

Agents API构成了平台的控制平面。它允许开发者配置、检索、更新和删除定制化的有状态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请求都必须包含从应用默认凭据（ADC）获取的Bearer令牌，并指向生产环境全局端点。

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 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平台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（长期运行操作）

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是一个长期运行操作（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. 列出Agent

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?"}]
  }]
}
有关使用已配置Agent运行对话的完整说明、Python和TS/JS代码块以及流式设置，请参考**
gemini-interactions-api
**技能指南（
../gemini-interactions-api/SKILL.md
）。