注册和管理 A2A 代理

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

准备工作

请确保您已备好：

Discovery Engine Admin 角色。
现有的 Gemini Enterprise 应用。如需创建应用，请参阅创建应用。
使用 A2A protocol 的代理。

配置授权详细信息

为代理创建 OAuth 2.0 凭证，以便代理能够代表用户访问 Google Cloud 资源（例如 BigQuery 表）。

获取授权详细信息

请按照以下步骤获取授权详细信息。

在 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。您需要这些详细信息才能创建授权资源：

向 Gemini Enterprise 添加授权资源

运行以下命令以向 Gemini Enterprise 注册授权资源：

REST

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_ID/loca
   tions/LOCATION/authorizations?authorizationId=AUTH_ID" \
   -d '{
      "name": "projects/PROJECT_ID/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。
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：您在创建 OAuth 凭证时获得的授权 URI。其格式如下： https://accounts.google.com/o/oauth2/v2/auth?client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fbigquery&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
OAUTH_TOKEN_URI：您在创建 OAuth 凭证时获得的令牌 URI。

向 Gemini Enterprise 注册 A2A 代理

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

控制台

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

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

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

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

例如：

{
  "protocolVersion": "v1.0",
  "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"
  ]
}

依次点击导入代理 > 下一步。
输入授权详细信息，然后点击完成。

REST

如需使用 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!\"]}]}"
  }
}

更新 A2A 代理

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

控制台

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

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

Gemini Enterprise
点击要向其注册代理的应用的名称。
点击代理。
点击要更新的 A2A 代理的名称，然后点击修改。

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

例如：

{
  "protocolVersion": "v3.0",
  "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
}

列出已关联到应用的代理

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

curl

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 注册的代理的详细信息：

curl

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 代理

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

curl

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 添加授权资源

REST

向 Gemini Enterprise 注册 A2A 代理

控制台

REST

命令和结果示例

更新 A2A 代理

控制台

REST

命令和结果示例

列出已关联到应用的代理

curl

命令和结果示例

查看 A2A 代理的详细信息

curl

命令和结果示例

删除 A2A 代理

curl

命令和结果示例

后续步骤

注册和管理 A2A 代理