Agent2Agent (A2A) 协议是一种开放通信协议,也是代理的通用语言。它使来自不同构建方和平台的代理能够相互发现、协作并安全地委托任务。本文档介绍了 Gemini Enterprise 管理员如何将使用 A2A 构建并托管在任何平台上的代理连接到 Gemini Enterprise,从而供用户在 Gemini Enterprise Web 应用中使用这些代理。
准备工作
请确保您已备好:
启用 Discovery Engine API。如需为 Google Cloud项目启用 Discovery Engine API,请在 Google Cloud 控制台中前往 Discovery Engine API 页面。
现有的 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-redirecthttps://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/locations/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或euAUTH_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=consentOAUTH_TOKEN_URI:您在创建 OAuth 凭证时获得的令牌 URI。
向 Gemini Enterprise 注册 A2A 代理
您可以使用Google Cloud 控制台或 API 向 Gemini Enterprise 注册 A2A 代理。这样一来,用户就可以在 Gemini Enterprise 应用中使用该代理。
控制台
如需使用 Google Cloud 控制台注册 A2A 代理,请按以下步骤操作:
在 Google Cloud 控制台中,前往 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" ] }依次点击预览代理详情 > 下一步。
使用以下方法之一完成设置:
如果您希望代理代表您访问 Google Cloud 资源,请按以下步骤操作:
输入您在获取授权详细信息部分中生成的客户端 ID、客户端密钥、授权 URI 和令牌 URI。
输入范围。
点击完成。
如果您不希望代理代表您访问 Google Cloud 资源,请点击跳过并完成。
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或euPROJECT_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 使用的值。
列出已关联到应用的代理
以下代码示例演示了如何获取与您的应用关联的所有代理的详细信息:
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 代理,请按以下步骤操作:
在 Google Cloud 控制台中,前往 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 使用的值。
删除 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 注册的代理。