注册和管理 A2A 代理

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

准备工作

请确保您已备好：

  • Gemini Enterprise 管理员角色。

  • 启用 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 代理，您可以使用 OAuth 2.0 凭据来控制最终用户对 A2A 代理的访问权限。不过，如果代理在 Cloud Run 上运行并使用 Identity and Access Management 进行访问权限控制，则不需要 OAuth 2.0 凭据。

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

    转到“凭据”页面

  2. 选择您希望代理能够访问的数据源所在的 Google Cloud 项目。例如，选择您希望代理能够查询的 BigQuery 数据集所在的项目。

  3. 点击创建凭据并选择 OAuth 客户端 ID。

  4. 在应用类型中，选择 Web 应用。

  5. 在已获授权的重定向 URI 部分中，添加以下 URI：

    • https://vertexaisearch.cloud.google.com/oauth-redirect
    • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html

  6. 点击创建。

  7. 在 OAuth 客户端已创建面板中，点击下载 JSON。 下载的 JSON 文件包含所选Google Cloud 项目的 Client ID、Authorization URI、Token URI 和 Client secret。您需要这些详细信息才能创建授权资源。

向 Gemini Enterprise 注册 A2A 代理

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

控制台

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

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

    Gemini Enterprise

  2. 点击要向其注册代理的应用的名称。

  3. 依次点击代理 > 添加代理。

  4. 在选择代理类型部分，对于通过 A2A 构建的自定义代理，点击添加。

  5. 在代理卡片 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"
  ]
}

  6. 依次点击预览代理详情 > 下一步。

  7. 使用以下方法之一完成设置：

    • 如果您希望代理代表您访问 Google Cloud 资源，请按以下步骤操作：

      1. 输入您在配置授权详细信息（可选）中生成的客户端 ID、客户端密钥、授权 URI 和令牌 URI。

      2. 输入范围。

      3. 点击完成。

    • 如果您不希望代理代表您访问 Google Cloud 资源，请点击跳过并完成。

REST

如需使用 REST API 注册 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。
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 资源中。

列出已关联到应用的代理

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

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",
...
}

查看 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。

更新 A2A 代理

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

控制台

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

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

    Gemini Enterprise

  2. 点击包含要更新的代理的应用的名称。

  3. 点击代理。

  4. 点击要更新的 A2A（自定义）代理的名称，然后点击修改。

  5. 在代理卡片 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"
  ]
}

  6. 点击保存。

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 资源中。

删除 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。

后续步骤

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