注意：此文档集适用于 Gemini Enterprise 的 Standard 版、Plus 版、随用随付版和一线员工版。如需查看 Business 版文档，请参阅 Gemini Enterprise - Business 版帮助中心。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

注册和管理 A2A 代理

Agent2Agent (A2A) 协议是一种开放通信协议，也是智能体的通用语言。该协议使来自不同构建方和平台的代理能够相互发现、协作并安全地委托任务。本文档介绍了 Gemini Enterprise 管理员如何将使用 A2A 构建并托管在任何平台上的代理连接到 Gemini Enterprise，从而供用户在 Gemini Enterprise Web 应用中使用这些代理。

准备工作

请确保您已备好：

Gemini Enterprise Admin 角色。
启用 Discovery Engine API。如需为 Google Cloud项目启用 Discovery Engine API，请在 Google Cloud 控制台中前往 Discovery Engine API 页面。

前往 Discovery Engine API
现有的 Gemini Enterprise 应用。如需创建应用，请参阅创建应用。
使用 A2A protocol 的代理。

Gemini Enterprise 支持 A2A v0.3 流式传输机制。

如果您使用的是 A2A v1.0.0 或更高版本，请使用 SDK 提供的兼容性软件包，确保您的代理能够与早期机制搭配使用（例如，适用于 Go 的 a2acompat/a2av0 软件包或适用于 Python 的 a2a.compat.v0_3 软件包）。

提示：您必须托管并维护 A2A 代理，才能让它们在 Gemini Enterprise 中正常运行。
如果您的 A2A 智能体托管在 Cloud Run 上，直接使用默认 .run.app 网址，并且需要身份验证，请向 Discovery Engine 服务代理授予 Cloud Run Invoker (roles/run.invoker) 角色（如果 Cloud Run 位于 Apigee、负载均衡器或自定义网域后面，则不适用）：
```
gcloud projects add-iam-policy-binding <var>PROJECT_ID</var> \
   --member="serviceAccount:service-<var>PROJECT_NUMBER</var>@gcp-sa-discoveryengine.iam.gserviceaccount.com" \
   --role="roles/run.invoker"
```
替换以下内容：
- PROJECT_ID：您的项目的 ID。
- PROJECT_NUMBER：您的 Google Cloud 项目编号。

配置身份验证和授权

根据智能体托管环境和安全要求，您可以配置 Gemini Enterprise 如何向智能体进行身份验证、智能体如何代表最终用户访问资源，以及如何保护智能体端点。

Gemini Enterprise 如何对您的智能体进行身份验证

当 Gemini Enterprise 调用 A2A 智能体时，它可以根据您的托管和安全配置在请求标头中发送身份验证和授权数据：

标题说明

标题	说明
`X-Serverless-Authorization`	服务到服务 IAM 身份验证（适用于 Cloud Run）。如果您的 A2A 智能体托管在 Cloud Run 上，并且您的智能体网址是默认的 `.run.app` 网址，Gemini Enterprise 会自动为 Discovery Engine 服务代理 (`service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com`) 生成一个 Google 签名的 OIDC ID 令牌，并将您的智能体网址作为目标对象，然后将其附加到 `X-Serverless-Authorization` 标头中。如果您的代理网址使用 Apigee、负载均衡器或自定义网域，Gemini Enterprise 不会发送此标头。当 Gemini Enterprise 直接调用默认 `.run.app` 网址时，Cloud Run 入站流量基础架构会使用此标头来验证服务代理是否具有 `roles/run.invoker` IAM 角色（请参阅准备工作），然后再将请求转发到您的应用容器。
`Authorization`	最终用户 OAuth 2.0 授权（用于用户上下文和 API 访问）。如果您为 A2A 智能体配置了 OAuth 2.0 凭证（请参阅为最终用户授权配置 OAuth 2.0），Gemini Enterprise 会在登录的最终用户授予同意后，代表该用户获取 OAuth 2.0 访问令牌或 ID 令牌，并在标准 `Authorization` 标头（例如 `Bearer USER_OAUTH_TOKEN`）中发送该令牌。 Cloud Run 会将 `Authorization` 标头直接转发到您的容器，以便您的代理应用代码读取用户令牌并代表用户调用下游 API。

X-Serverless-Authorization

服务到服务 IAM 身份验证（适用于 Cloud Run）。

如果您的 A2A 智能体托管在 Cloud Run 上，并且您的智能体网址是默认的 .run.app 网址，Gemini Enterprise 会自动为 Discovery Engine 服务代理 (service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com) 生成一个 Google 签名的 OIDC ID 令牌，并将您的智能体网址作为目标对象，然后将其附加到 X-Serverless-Authorization 标头中。如果您的代理网址使用 Apigee、负载均衡器或自定义网域，Gemini Enterprise 不会发送此标头。

当 Gemini Enterprise 直接调用默认 .run.app 网址时，Cloud Run 入站流量基础架构会使用此标头来验证服务代理是否具有 roles/run.invoker IAM 角色（请参阅准备工作），然后再将请求转发到您的应用容器。

Authorization

最终用户 OAuth 2.0 授权（用于用户上下文和 API 访问）。

如果您为 A2A 智能体配置了 OAuth 2.0 凭证（请参阅为最终用户授权配置 OAuth 2.0），Gemini Enterprise 会在登录的最终用户授予同意后，代表该用户获取 OAuth 2.0 访问令牌或 ID 令牌，并在标准 Authorization 标头（例如 Bearer USER_OAUTH_TOKEN）中发送该令牌。

Cloud Run 会将 Authorization 标头直接转发到您的容器，以便您的代理应用代码读取用户令牌并代表用户调用下游 API。

配置 OAuth 2.0 以进行最终用户授权（可选）

对于 A2A 智能体，如果您的智能体必须代表最终用户访问Google Cloud 资源或执行操作，请配置 OAuth 2.0 凭证。如需详细了解身份验证和授权标头的运作方式，请参阅 Gemini Enterprise 如何对您的代理进行身份验证。

请按照以下步骤创建 OAuth 客户端 ID：

在 Google Cloud 控制台的 API 和服务页面上，前往凭证页面。

转到“凭据”页面
选择您希望代理能够访问的数据源所在的 Google Cloud 项目。例如，选择您希望智能体能够查询的 BigQuery 数据集所在的项目。
点击创建凭据并选择 OAuth 客户端 ID。
在应用类型中，选择 Web 应用。
在已获授权的重定向 URI 部分中，添加以下 URI：
- https://vertexaisearch.cloud.google.com/oauth-redirect
- https://vertexaisearch.cloud.google.com/static/oauth/oauth.html
点击创建。
在 OAuth 客户端已创建面板中，点击下载 JSON。下载的 JSON 文件包含所选Google Cloud 项目的 Client ID、Authorization URI、Token URI 和 Client secret。您需要这些详细信息才能创建授权资源。

保护 A2A 智能体端点

如需了解 Gemini Enterprise 发送到 A2A 智能体的身份验证标头，请参阅 Gemini Enterprise 如何向您的智能体进行身份验证。在保护 Agent Endpoint 或其前面的 API Gateway 时，请考虑以下事项：

智能体卡片安全方案：Gemini Enterprise 不会使用智能体卡片的 securitySchemes 和 security 字段向您的智能体进行身份验证。
API 密钥和自定义标头：Gemini Enterprise 不支持 apiKey 安全方案，也不提供向其发送给代理的请求添加静态 API 密钥或其他自定义标头值的方法。
服务代理 ID 令牌：仅当代理网址是以 .run.app 结尾的默认 Cloud Run 网址时，Gemini Enterprise 才会发送 X-Serverless-Authorization 标头。如果您的智能体网址使用自定义网域、负载均衡器或 API Gateway，Gemini Enterprise 不会发送此标头。
最终用户令牌：如果您为代理配置 OAuth 2.0，Gemini Enterprise 会在 Authorization 标头中发送 OAuth 2.0 提供商提供的最终用户令牌。

使用 Apigee 保护 Agent Endpoint

如果您通过 Apigee API 代理公开 A2A 智能体，则代理会在 Authorization 标头中收到最终用户令牌，但不会收到 X-Serverless-Authorization 标头。如需保护代理，请执行以下操作：

为代理配置 OAuth 2.0 以进行最终用户授权（使用 Google Cloud OAuth 2.0 客户端 ID 或第三方 OAuth 2.0 提供商），并在注册代理时提供这些 OAuth 2.0 详细信息。保护 Apigee API 代理时，必须配置 OAuth 2.0；请勿在注册期间跳过授权步骤。
在代理卡片中，将 url 设置为 Apigee API 代理的网址。
在 API 代理中，先验证 Authorization 标头中的最终用户令牌，然后再将请求转发到代理。根据 OAuth 2.0 提供商颁发的令牌格式选择 Apigee 政策：
- 颁发已签名 JWT 访问令牌的第三方 OAuth 2.0 提供商：使用 VerifyJWT 政策，根据提供商的公共 JSON Web 密钥集 (JWKS) URI 验证令牌签名，并验证颁发者 (iss) 和受众群体 (aud) 声明。
- Google OAuth 2.0 (accounts.google.com)：Google OAuth 2.0 访问令牌 (ya29...) 是不透明令牌，而不是已签名的 JWT。使用 ServiceCallout 政策调用 https://oauth2.googleapis.com/tokeninfo 并验证受众群体 (aud) 和 scope 字段。

向 Gemini Enterprise 注册 A2A 代理

您可以使用Google Cloud 控制台或 REST API 向 Gemini Enterprise 注册 A2A 智能体。这样一来，用户就可以在 Gemini Enterprise 应用中使用该代理。

代理注册配额和许可：向应用注册代理会消耗一个单位的项目每日代理创建配额 (discoveryengine.googleapis.com/agents_tier_enterprise_regional)。配额取决于分配给项目的 Gemini Enterprise Standard 许可数量（每位用户每天 1 个创建配额，共用）或 Plus 许可数量（每位用户每天 10 个创建配额，共用）。一线员工版许可不提供创建配额。

如果您在同一项目中的多个 Gemini Enterprise 应用或引擎中注册后端代理，则每次注册 API 调用 (agents.create) 都会计为一次代理创建，并计入此每日配额。如果一天内的注册调用次数超过已分发的标准版许可数量，则在许多应用中注册代理的自动化部署脚本或 CI/CD 流水线可能会遇到 HTTP 429 RESOURCE_EXHAUSTED: Agent creation quota exceeded。在执行多应用发布之前，请确保您的项目已分配足够的标准版许可。如需了解详情，请参阅每日创建配额。

控制台

如需使用 Google Cloud 控制台注册 A2A 代理，请按以下步骤操作：

在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。

Gemini Enterprise
点击要向其注册代理的应用的名称。
依次点击代理 > 添加代理。
在选择代理类型部分，对于通过 A2A 构建的自定义代理，点击添加。

在代理卡片 JSON 字段中，以 JSON 格式输入代理卡片详细信息。如需查看可用字段的完整列表，请参阅 Agent2Agent (A2A) Protocol 官方规范。以下示例仅使用必填字段。

例如：

{
  "protocolVersion": "0.3",
  "name": "Hello World Agent",
  "description": "Just a hello world agent",
  "url": "https://example.com/myagent",
  "iconUrl": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTkiIGhlaWdodD0iOTkiIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOmdyYXk7IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0zMyAwaDMzdjMzSDMzeiBNMCAzM2gzM3YzM0gweiBNNjYgMzNoMzN2MzNINjZ6IE0zMyA2NmgzM3YzM0gzM3oiIGZpbGw9ImJsdWUiLz48L3N2Zz4=",
  "version": "1.0.0",
  "capabilities": {
  },
  "skills": [
    {
      "id": "data-analysis",
      "name": "Data Analysis",
      "description": "Data analysis",
      "tags": []
    }
  ],
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ]
}

依次点击预览代理详细信息 > 下一步。
使用以下方法之一完成设置：
- 如果您希望代理代表您访问 Google Cloud 资源，或者如果您的 Agent Endpoint 需要 Authorization 标头（例如，在保护 Apigee API 代理时），请按照以下步骤操作：
  1. 输入您在为最终用户授权配置 OAuth 2.0（可选）中生成的客户端 ID、客户端密钥、授权 URI 和令牌 URI。
  2. 输入范围。
  3. 点击完成。
- 如果您不希望代理代表您访问 Google Cloud 资源，并且您的 Agent Endpoint 不需要 Authorization 标头，请点击跳过并完成。

REST

如需使用 REST API 注册 A2A 智能体，请按以下步骤操作：

向 Gemini Enterprise 添加授权资源（可选）
注册 A2A 智能体

将授权资源添加到 Gemini Enterprise（可选）

如果代理必须代表用户访问 Google Cloud 资源，请运行以下命令，向 Gemini Enterprise 注册您在配置授权详细信息（可选）部分中创建的授权资源：

curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/authorizations?authorizationId=AUTH_ID" \
   -d '{
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTH_ID",
      "serverSideOauth2": {
         "clientId": "OAUTH_CLIENT_ID",
         "clientSecret": "OAUTH_CLIENT_SECRET",
         "authorizationUri": "OAUTH_AUTH_URI",
         "tokenUri": "OAUTH_TOKEN_URI"
      }
   }'

替换以下内容：

PROJECT_ID：您的项目的 ID。
PROJECT_NUMBER：您的 Google Cloud 项目的编号。
ENDPOINT_LOCATION：API 请求的多区域。请指定以下某个值：
- us（表示美国多区域）
- eu（表示欧盟多区域）
- global（表示全球位置）
如需了解详情，请参阅为数据存储区指定多区域。
LOCATION：数据存储区的多区域：global、us 或 eu
AUTH_ID：授权资源的 ID。这是您定义的任意字母数字 ID。您稍后在注册需要 OAuth 支持的代理时，需要引用此 ID。
OAUTH_CLIENT_ID：您在创建 OAuth 凭证时获得的 OAuth 2.0 客户端标识符。
OAUTH_CLIENT_SECRET：您在创建 OAuth 凭证时获得的 OAuth 2.0 客户端密钥。

OAUTH_AUTH_URI：授权 URI。如需为应用授权，请使用 OAuth 凭证 JSON 文件中的详细信息构建特定的授权 URI。复制以下模板，并将占位符替换为您的特定值。

https://accounts.google.com/o/oauth2/v2/auth?client_id=OAUTH_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=YOUR_CUSTOM_SCOPES&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

YOUR_CUSTOM_SCOPES：您可以添加所需的范围。例如，以下 OAuth 范围字符串会请求对您的 Google 云端硬盘和 Google 文档的只读权限。
```
scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdocuments.readonly
```

OAUTH_TOKEN_URI：您在创建 OAuth 凭证时获得的令牌 URI。

详细了解授权 URI 参数。

为确保 URI 正常运行，请验证以下字段：

参数	价值或操作
`client_id`	替换为在下载的 JSON 中找到的 `client_id`。
`redirect_uri`	不更改。必须为 `https://vertexaisearch.cloud.google.com/static/oauth/oauth.html`。
`scope`	列出您的应用需要代表用户访问的 Google API 范围。例如，如需授予对 BigQuery 的访问权限，请使用范围 `https://www.googleapis.com/auth/bigquery`；如需授予对 Google 文档的只读权限，请使用 `https://www.googleapis.com/auth/documents.readonly`。如果您使用多个范围，请用空格分隔它们，空格在网址中会变为 `%20`。注意：如果您的 A2A 智能体托管在 Gemini Enterprise Agent Platform 上的 Agent Runtime 中，则必须创建具有 `cloud-platform` 范围的授权。例如 `&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform`。如需了解详情，请参阅使用 Agent2Agent 代理。
`include_granted_scopes`	必须为 `true`。
`response_type`	必须年满 `code` 周岁才能收到授权代码。
`access_type`	设置为 `offline`，以帮助确保您收到刷新令牌。
`prompt`	设置为 `consent`，以帮助确保始终向用户显示权限请求页面。

注册 A2A 智能体

如需使用 Gemini Enterprise 创建并注册代理，请使用 agents.create 方法。以下命令仅使用必填字段。如需查看可用字段的完整列表，请参阅 Agent2Agent (A2A) Protocol 官方规范。

运行以下命令，向 Gemini Enterprise 注册 A2A 代理：

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents \
-d '
{
  "name": "AGENT_NAME",
  "displayName": "AGENT_DISPLAY_NAME",
  "description": "AGENT_DESCRIPTION",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"PROTOCOLVERSION\",\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
  },
  "authorizationConfig": {
    "agentAuthorization": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID"
  }
}
'

替换以下内容：

ENDPOINT_LOCATION：API 请求的多区域。请指定以下某个值：
- us（表示美国多区域）
- eu（表示欧盟多区域）
- global（表示全球位置）
如需了解详情，请参阅为数据存储区指定多区域。
LOCATION：数据存储区的多区域：global、us 或 eu
PROJECT_ID：您的项目的 ID。
APP_ID：您要向其注册代理的应用的 ID。
AGENT_NAME：代理的唯一标识符。
AGENT_DISPLAY_NAME：在 Web 应用上显示的代理名称。
AGENT_DESCRIPTION：代理可以执行的操作的说明。
PROTOCOLVERSION：代理支持的 A2A protocol 版本。如需详细了解支持的版本，请参阅 A2A 版本说明。
AGENT_URL：代理的端点网址。
AGENT_VERSION：代理的版本。
INPUT_MODE：默认输入媒体类型。例如 application/json 或 text/plain。
OUTPUT_MODE：默认输出媒体类型。例如 text/plain" 或 image/png。
CAPABILITIES：包含受支持的 A2A 功能的 JSON 对象。例如 \"streaming\": true 或 \"pushNotifications\": false。
SKILLS：代理提供的 AgentSkill 对象的列表。
authorizationConfig：如果您已获取授权详细信息，并希望代理代表用户访问 Google Cloud 资源，请将 authorization_config 字段添加到您的 JSON 资源中。
- AUTH_ID：您在向 Gemini Enterprise 添加授权资源部分中为 AUTH_ID 使用的值。

命令和结果示例

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://global-discoveryengine.googleapis.com/v1alpha/projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents \
-d '
{
  "name": "Hello World Agent",
  "displayName": "Hello World Agent",
  "description": "Just a hello world agent",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"0.3.0\",\"name\":\"Hello World Agent\",\"description\":\"Just a hello world agent\",\"url\":\"https://example.com/myagent\",\"version\":\"1.0.0\",\"defaultInputModes\":[\"text\"],\"defaultOutputModes\":[\"text\"],\"capabilities\":{},\"skills\":[{\"description\":\"Chat with the Gemini agent.\",\"examples\":[\"Hello, world!\"],\"id\":\"chat\",\"name\":\"Chat Skill\",\"tags\":[\"chat\"]}]}"
  }
}
'

{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
  "displayName": "Hello World Agent",
  "description": "Just a hello world agent",
  "createTime": "2025-10-20T20:53:35.490600996Z",
  "state": "ENABLED",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"0.3.0\",\"name\":\"Hello World Agent\",\"description\":\"Just a hello world agent\",\"url\":\"https://example.com/myagent\",\"version\":\"1.0.0\",\"capabilities\":{},\"defaultInputModes\":[\"text\"],\"defaultOutputModes\":[\"text\"],\"skills\":[{\"id\":\"chat\",\"name\":\"Chat Skill\",\"description\":\"Chat with the Gemini agent.\",\"tags\":[\"chat\"],\"examples\":[\"Hello, world!\"]}]}"
  }
}

列出已关联到应用的代理

以下代码示例演示了如何获取与您的应用关联的所有代理的详细信息：

REST

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents"

将变量替换为所需值：

ENDPOINT_LOCATION：API 请求的多区域。请指定以下某个值：
- us（表示美国多区域）
- eu（表示欧盟多区域）
- global（表示全球位置）
如需了解详情，请参阅为数据存储区指定多区域。
PROJECT_ID：您的 Google Cloud 项目的 ID。
LOCATION：应用的多区域：global、us 或 eu。
APP_ID：您的 Gemini Enterprise 应用的 ID。

如果您的代理不是由 Google 预构建的，则响应的前几行中会包含一个 name 字段。此字段的值包含路径末尾的代理 ID。例如，在以下响应中，代理 ID 为 12345678901234567890：

{
"name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
...
}

命令和结果示例

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents"

{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
  "displayName": "Hello World Agent",
  "description": "Just a hello world agent",
  "createTime": "2025-10-20T20:53:35.490600996Z",
  "state": "ENABLED",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"name\":\"Hello World Agent\",\"description\":\"Just a hello world agent\",\"url\":\"https://example.com/myagent\",\"version\":\"1.0.0\",\"capabilities\":{},\"default_input_modes\":[\"text\"],\"default_output_modes\":[\"text\"],\"skills\":[{\"id\":\"chat\",\"name\":\"Chat Skill\",\"description\":\"Chat with the Gemini agent.\",\"tags\":[\"chat\"],\"examples\":[\"Hello, world!\"]}]}"
  }
}

查看 A2A 代理的详细信息

以下代码示例演示了如何检索已向 Gemini Enterprise 注册的代理的详细信息：

REST

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

将变量替换为所需值：

ENDPOINT_LOCATION：API 请求的多区域。请指定以下某个值：
- us（表示美国多区域）
- eu（表示欧盟多区域）
- global（表示全球位置）
如需了解详情，请参阅为数据存储区指定多区域。
PROJECT_ID：您的 Google Cloud 项目的 ID。
LOCATION：应用的多区域：global、us 或 eu。
APP_ID：您的 Gemini Enterprise 应用的 ID。
AGENT_ID：代理的 ID。您可以通过列出与应用关联的代理来查找代理 ID。

命令和结果示例

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://global-discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890"

{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
  "displayName": "Hello World Agent",
  "description": "Just a hello world agent",
  "createTime": "2025-10-20T20:53:35.490600996Z",
  "state": "ENABLED",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"name\":\"Hello World Agent\",\"description\":\"Just a hello world agent\",\"url\":\"https://example.com/myagent\",\"version\":\"1.0.0\",\"capabilities\":{},\"default_input_modes\":[\"text\"],\"default_output_modes\":[\"text\"],\"skills\":[{\"id\":\"chat\",\"name\":\"Chat Skill\",\"description\":\"Chat with the Gemini agent.\",\"tags\":[\"chat\"],\"examples\":[\"Hello, world!\"]}]}"
  }
}

更新 A2A 代理

您可以使用 Google Cloud 控制台或 REST API 修改已向 Gemini Enterprise 注册的现有 A2A 代理的详细信息。

控制台

如需使用 Google Cloud 控制台更新 A2A 代理，请按以下步骤操作：

在 Google Cloud 控制台中，前往 Gemini Enterprise 页面。

Gemini Enterprise
点击包含要更新的代理的应用的名称。
点击代理。
点击要更新的 A2A（自定义）代理的名称，然后点击修改。

在代理卡片 JSON 字段中，以 JSON 格式更新代理卡片详细信息。如需查看可用字段的完整列表，请参阅 Agent2Agent (A2A) Protocol 官方规范。以下示例仅使用必填字段。

例如：

{
  "protocolVersion": "0.3",
  "name": "Hello World Agent",
  "description": "Just a hello world agent",
  "url": "https://example.com/myagent",
  "iconUrl": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTkiIGhlaWdodD0iOTkiIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOmdyYXk7IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0zMyAwaDMzdjMzSDMzeiBNMCAzM2gzM3YzM0gweiBNNjYgMzNoMzN2MzNINjZ6IE0zMyA2NmgzM3YzM0gzM3oiIGZpbGw9ImJsdWUiLz48L3N2Zz4=",
  "version": "1.1.0",
  "capabilities": {
  },
  "skills": [
    {
      "id": "data-analysis",
      "name": "Data Analysis",
      "description": "Data analysis",
      "tags": []
    }
  ],
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ]
}

点击保存。

REST

如需更新已向 Gemini Enterprise 注册的 A2A 代理的详细信息，请使用 agents.patch 方法。以下命令仅使用必填字段。如需查看可用字段的完整列表，请参阅 Agent2Agent (A2A) Protocol 官方规范。

运行以下命令，使用 Gemini Enterprise 更新 A2A 代理：

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID \
-d '
{
  "name": "AGENT_NAME",
  "displayName": "AGENT_DISPLAY_NAME",
  "description": "AGENT_DESCRIPTION",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"PROTOCOLVERSION\",\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
  },
  "authorizationConfig": {
    "agentAuthorization": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID"
  }
}
'

替换以下内容：

ENDPOINT_LOCATION：API 请求的多区域。请指定以下某个值：
- us（表示美国多区域）
- eu（表示欧盟多区域）
- global（表示全球位置）
如需了解详情，请参阅为数据存储区指定多区域。
LOCATION：数据存储区的多区域：global、us 或 eu。
PROJECT_ID：您的项目的 ID。
APP_ID：您要向其注册代理的应用的 ID。
AGENT_ID：代理的 ID。您可以通过列出与应用关联的代理来查找代理 ID。
AGENT_NAME：代理的唯一标识符。
AGENT_DISPLAY_NAME：在 Web 应用上显示的代理名称。
AGENT_DESCRIPTION：代理可以执行的操作的说明。
PROTOCOLVERSION：代理支持的 A2A protocol 版本。如需详细了解支持的版本，请参阅 A2A 版本说明。
AGENT_URL：代理的端点网址。
AGENT_VERSION：代理的版本。
INPUT_MODE：默认输入媒体类型。例如 application/json 或 text/plain。
OUTPUT_MODE：默认输出媒体类型。例如 text/plain 或 image/png。
CAPABILITIES：包含受支持的 A2A 功能的 JSON 对象。例如 \"streaming\": true 或 \"pushNotifications\": false。
SKILLS：代理提供的 AgentSkill 对象的列表。
authorizationConfig：如果您已获取授权详细信息，并希望代理代表用户访问 Google Cloud 资源，请将 authorization_config 字段添加到您的 JSON 资源中。
- AUTH_ID：您在向 Gemini Enterprise 添加授权资源部分中为 AUTH_ID 使用的值。

命令和结果示例

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://global-discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890 \
-d '
{
  "name": "Hello World Agent",
  "displayName": "Hello World Agent",
  "description": "Just a hello world agent",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"0.3.0\",\"name\":\"Hello World Agent\",\"description\":\"Just a hello world agent\",\"url\":\"https://example.com/myagent\",\"version\":\"1.1.0\",\"defaultInputModes\":[\"text\"],\"defaultOutputModes\":[\"text\"],\"capabilities\":{  },\"skills\":[{\"description\":\"Chat with the Gemini agent.\",\"examples\":[\"Hello, world!\"],\"id\":\"chat\",\"name\":\"Chat Skill\",\"tags\":[\"chat\"]}]}"
  }
}
'

{
  "name": "projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
  "displayName": "Hello World Agent",
  "description": "Just a hello world agent",
  "createTime": "2025-10-20T20:53:35.490600996Z",
  "state": "ENABLED",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"name\":\"Hello World Agent\",\"description\":\"Just a hello world agent\",\"url\":\"https://example.com/myagent\",\"version\":\"1.0.0\",\"capabilities\":{},\"defaultInputModes\":[\"text\"],\"defaultOutputModes\":[\"text\"],\"skills\":[{\"id\":\"chat\",\"name\":\"Chat Skill\",\"description\":\"Chat with the Gemini agent.\",\"tags\":[\"chat\"],\"examples\":[\"Hello, world!\"]}]}"
  }P
}

删除 A2A 代理

以下代码示例演示了如何删除与您的应用关联的代理：

REST

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

将变量替换为所需值：

ENDPOINT_LOCATION：API 请求的多区域。请指定以下某个值：
- us（表示美国多区域）
- eu（表示欧盟多区域）
- global（表示全球位置）
如需了解详情，请参阅为数据存储区指定多区域。
PROJECT_ID：您的 Google Cloud 项目的 ID。
LOCATION：应用的多区域：global、us 或 eu
APP_ID：您的 Gemini Enterprise 应用的 ID。
AGENT_ID：代理的 ID。您可以通过列出与应用关联的代理来查找代理 ID。

命令和结果示例

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://global-discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890"

{
  "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890/operations/delete-agent-12345678901234567890",
  "done": true
}

后续步骤

在 Web 应用中使用您向 Gemini Enterprise 注册的代理。

注册和管理 A2A 代理 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

配置身份验证和授权

Gemini Enterprise 如何对您的智能体进行身份验证

配置 OAuth 2.0 以进行最终用户授权（可选）

保护 A2A 智能体端点

使用 Apigee 保护 Agent Endpoint

向 Gemini Enterprise 注册 A2A 代理

控制台

REST

将授权资源添加到 Gemini Enterprise（可选）

详细了解授权 URI 参数。

注册 A2A 智能体

命令和结果示例

列出已关联到应用的代理

REST

命令和结果示例

查看 A2A 代理的详细信息

REST

命令和结果示例

更新 A2A 代理

控制台

REST

命令和结果示例

删除 A2A 代理

REST

命令和结果示例

后续步骤

注册和管理 A2A 代理