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

创建数据代理

本文档介绍了如何在 BigQuery 中创建、修改、管理和删除数据代理。

在 BigQuery 中，您可以与数据智能体进行对话，使用自然语言询问有关 BigQuery 数据的问题。数据代理包含表元数据和特定于用例的查询处理指令，用于定义回答用户有关一组知识源（例如您选择的表、视图或用户定义的函数 [UDF]）问题的最佳方式。

准备工作

验证是否已为您的 Google Cloud 项目启用结算功能。
启用 BigQuery、Gemini Data Analytics、Gemini for Google Cloud和 Knowledge Catalog API。
启用 API 所需的角色
如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。
启用 API

所需的角色

如需使用数据智能体，您必须拥有与您的使用情形相符的 Identity and Access Management (IAM) 权限。以下部分列出了所需角色，具体取决于您是创建和发布代理、在 Gemini Enterprise 中预配代理，还是在各种平台上发现和使用代理。如需了解详情，请参阅 Conversational Analytics API IAM 角色。

创建、修改、发布、共享和删除代理：
- 在项目中创建数据代理：项目的 Gemini Data Analytics Data Agent Creator (roles/geminidataanalytics.dataAgentCreator)。此角色会自动授予您对所创建数据代理的 Gemini Data Analytics 数据代理所有者角色。
- 如需修改、共享或删除数据代理，您需要拥有该代理或项目的 Gemini Data Analytics 数据代理所有者角色 (roles/geminidataanalytics.dataAgentOwner)。
- 如需在项目中修改数据代理，您需要拥有以下角色：针对项目的 Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor)。
- 如需查看项目中的数据代理，请为项目分配 Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer) 角色。
在 Gemini Enterprise 中配置智能体：
- 如要让已发布的代理可供 Gemini Enterprise 中的用户使用，您需要在 Gemini Enterprise 管理控制台中拥有注册和管理 A2A 代理的权限。
发现和使用代理：
- 如需与数据代理对话，请使用 Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser)。
- 如需查看项目中的所有数据代理，请使用 Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer)。
- 如需在数据洞察中与 Gemini 提供支持的对话界面互动，您需要拥有 BigQuery Studio User (roles/bigquery.studioUser) 或 Gemini for Google Cloud User (roles/cloudaicompanion.user) 角色，这两个角色均提供 cloudaicompanion.topics.create 权限。在项目级层授予这些角色。用户还需要数据洞察 Asset Viewer (roles/datastudio.viewer) 角色。
向智能体添加知识来源：
- 项目的 Data Catalog Viewer (roles/datacatalog.viewer)。

如需进行对话，请参阅对话所需的角色。

智能体代表您执行操作并使用您的权限。智能体只能访问您有权访问的数据和资源。

最佳做法

对话式分析会自动为您运行查询，以回答您的问题。请考虑以下可能增加查询费用的因素：

表格尺寸较大
在查询中使用数据联接
查询中频繁调用 AI 函数

生成数据分析

您可以选择在 Knowledge Catalog 中为要用作知识源的任何表生成数据洞见。

生成的分析洞见提供表元数据，数据代理可以使用这些元数据来帮助生成您的问题的回答。

如果您未提前生成分析洞见，那么在创建数据代理时，当您选择表作为知识源后，系统会自动生成分析洞见。

使用示例数据代理

如果您不熟悉如何为对话式分析配置代理，可以选择查看为每个Google Cloud 项目生成的预定义示例代理。您可以与该模型对话，并查看其参数以了解其创建方式，但无法修改该模型。

如需查看示例代理，请执行以下操作：

在 Google Cloud 控制台中，前往 BigQuery 代理页面。

前往“代理”
选择智能体目录标签页。
在 Google 提供的示例代理部分下，点击示例代理卡片。

创建数据代理

以下部分介绍了如何创建数据代理。

创建代理后，您可以修改其设置。

初始步骤

在 Google Cloud 控制台中，前往 BigQuery 代理页面。

前往“代理”
选择智能体目录标签页。
点击新建代理 (New agent)。系统会打开新建代理页面。
在编辑器部分的代理名称字段中，输入数据代理的描述性名称，例如 Q4 sales data 或 User activity logs。
在数据代理说明字段中，输入数据代理的说明。好的说明会解释智能体的用途、使用的数据，并帮助您了解何时应与此数据智能体对话，例如 Ask questions about customer orders and revenue。
在知识来源部分，点击添加来源。系统会打开添加知识源页面。
在近期部分中，选择要用作知识源的任何表、视图、图或 UDF。在 Google Cloud 控制台中，UDF 的前缀为“fx”指示符。
如需查看其他知识来源，请选择 显示更多。
可选：添加未在最近部分中列出的知识来源：
1. 在搜索部分中，在搜索表字段中输入来源名称，然后按 Enter 键。来源名称不必完全一致。
2. 在搜索结果部分中，选择一个或多个来源。
点击添加。系统会重新打开新的代理页面。

自定义表格和字段说明

为了提高数据代理的准确性，您可以选择提供额外的表元数据。只有数据代理会使用此元数据，它不会影响源表。

创建表格和字段说明时，请遵循以下最佳实践：

您可以使用这些说明来了解数据代理如何理解架构。如果代理提供的说明建议正确无误，您可以接受这些建议。
如果您配置了这些说明后，数据代理仍未显示对架构的理解，请手动调整说明以提供正确的信息。

请按照以下步骤配置表和字段说明：

在知识来源部分中，点击表格对应的自定义链接。
创建表说明。您可以在表说明字段中输入说明，也可以接受 Gemini 给出的建议。
在字段部分，查看 Gemini 建议的字段说明。
选择要接受的任何字段说明，然后点击接受建议。选择要拒绝的所有说明，然后点击拒绝建议。
点击字段旁边的修改，手动修改任何字段说明。系统会打开修改字段窗格。
1. 在说明字段中，输入字段说明。
2. 如需保存字段说明，请点击更新。
如需保存说明和字段更新，请点击更新。系统会重新打开新的客服人员页面。
针对需要自定义的每个表格重复上述步骤。

创建智能体指令

智能体应能理解用户问题的上下文，而无需任何自定义指令。仅当您需要以其他上下文功能（例如自定义表格和字段元数据或经过验证的查询）尚不支持的方式更改代理的行为或改进上下文时，才需要为代理创建自定义指令。

在指令部分中，在智能体指令字段中为数据智能体输入指令。由于数据代理会使用这些指令来了解用户问题的背景信息并提供回答，因此请尽可能清晰地编写指令。

如果您未从智能体获得令人满意的答案，请添加结构化上下文，例如说明、示例或术语表。如果您仍然没有获得满意的回答，请添加自定义指令，如以下表格中的示例所示。

如需查看更多指令示例，请点击显示示例。

信息类型	说明	示例
关键字段	用于分析的最重要字段。	“此表格中最重要的字段是：客户 ID、商品 ID、订单日期。”
过滤和分组	代理应用于对数据进行过滤和分组的字段。	“如果问题涉及时间轴或‘随时间变化’，请务必使用 order_created_date 列。”“如果有人说‘按产品’，则按 product_category 列进行分组。”
默认过滤	默认情况下要过滤的字段。	“除非另有说明，否则始终按 order_status = 'Complete' 过滤数据。”
同义词和业务术语	关键字段的替代术语。	“如果有人询问‘收入’或‘销售额’，请使用 total_sale_amount 列。”“我们将 purchase_count > 5 的客户视为‘忠实’客户。”
排除的字段	数据代理应避免使用的字段。	“请勿使用以下字段：推断的交易日期、推断的城市。”
联接关系	两个或更多个表之间的关系，以及用于联接这些表的列。代理必须使用标准 SQL JOIN 对列对进行联接，以合并数据。请参阅“示例”列。	客户活动 `order_items.user_id` = `users.id` （将销售与客户相关联） `events.user_id` = `users.id` （将网站活动与已登录的客户相关联）

创建经过验证的查询

代理会通过以下两种方式使用经过验证的查询：

如果智能体可以使用经过验证的查询来回答您提出的问题，为了确保回答可信，智能体会完全按照书写方式调用该查询。
如果代理无法使用经过验证的查询来回答问题，它仍会使用该查询作为参考，以了解数据和查询数据的最佳实践。

您可以从系统生成的列表中选择已验证的查询，也可以自行创建查询。

如需为数据代理创建经过验证的查询（以前称为黄金查询），请执行以下操作：

选择一个或多个 Gemini 建议的已验证查询：
1. 在已验证的查询部分，点击查看建议。系统会打开查看建议的经过验证的查询页面。
2. 查看建议的经过验证的查询。选择适用于您的使用情形的任何选项。
3. 点击添加。系统会重新打开新的代理页面。
如需创建自己的经过验证的查询，请点击添加查询。系统会打开添加已验证的查询页面。
1. 在问题字段中，输入经过验证的查询所回答的用户问题。
2. 点击生成 SQL，让 Gemini 生成与您指定的用户问题对应的已验证查询。
3. 您可以选择修改经过验证的查询。
4. 点击运行，并验证查询是否返回了您预期的结果。
5. 点击添加。系统会重新打开新的代理页面。
根据需要重复上述步骤，以创建更多已验证的查询。

创建参数化验证查询

参数化验证查询可从用户的问题中提取值，供对话式分析代理使用，并提供量身定制的结果。

分析师和构建者可以创建包含这些值占位符的可重复使用的 SQL 模板。模板会在运行时动态替换参数，从而回答比常规已验证查询更广泛的用户问题。

当用户提出的问题与模板的模式匹配时，对话式分析代理会从问题中提取参数值，例如产品名称、区域和日期。然后，它会将这些值注入参数化查询中。查询模板中的匹配回答会显示为已验证。

参数化验证查询可显著增强验证查询的功能和灵活性。它们可确保在各种输入下提供一致且可信的答案，并减少需要维护的单个查询数量。

工作原理

数据分析师等专家使用模板问题（例如“@product 在 @region 的销售额是多少？”）定义经过验证的查询。然后，专家使用 SQL 参数创建或修改经过验证的查询，如以下示例所示：

SELECT * FROM sales WHERE region = @region AND product = @product

保存经过验证的查询后，用户可以向对话式分析代理提出自然语言问题，例如“北美地区的笔记本电脑销量是多少？”

为了回答用户的问题，智能体执行了以下步骤：

将问题与参数化验证查询关联的模式进行匹配。该代理使用自然语言理解 (NLU) 来识别并提取用户问题中 @region（北美）和 @product（笔记本电脑）的值。
将提取的值替换为 SQL 模板中的 @region 和 @product 占位符。
运行完整的 SQL 查询；例如，SELECT * FROM sales WHERE region = 'North America' AND product = 'Laptops'。
将结果返回给用户。匹配项始终标记为已验证。

有关如何创建有效的参数化查询的提示

使用清晰的参数名称。为参数使用描述性名称，例如 @start_date 而不是 @d1。
创建详细的参数说明。对话式分析的大语言模型 (LLM) 会使用参数说明从用户问题中识别参数及其值。例如，num_enrollments 是有效的参数名称，而 number of student enrollments from ages 5-14 是参数说明，可提供有关查询的更多背景信息。
确保数据类型一致。确保 SQL 查询预期的数据类型与可能从用户问题中提取的数据类型相匹配。
提供明确界定的范围。为常见且重要的疑问模式创建模板，这些疑问模式的查询构建复杂或逻辑不直观。这样做有助于 LLM 返回最佳结果。
全面测试。使用各种自然语言措辞进行测试，以确保参数提取正确无误。

创建参数化验证查询

您可以从系统生成的列表中选择已验证的查询，也可以自行创建查询。

在创建或修改查询之前，请先根据自然语言模式和您的问题起草查询。例如，如果您问“我们是否知道美国东部仓库中有机香蕉的总库存量？”，您可以将问题改写为参数化验证查询“@region 仓库中 @product 的总库存量是多少？”代理会将此问题转换为 SQL 查询，您可以使用默认值更新该查询。

如需为数据代理创建参数化验证查询，您可以在创建新代理时创建新查询，也可以为新代理或现有代理修改现有验证查询。

以下说明使用经过验证的示例查询来配置参数。

选择现有的 Gemini 建议的已验证查询

在新代理或现有代理的已验证的查询部分中，点击查看建议。系统会打开查看建议的经过验证的查询页面。
选中建议的已验证查询旁边的复选框。
在查询窗口中，点击 显示更多以展开查询说明。
如需打开现有查询，请点击修改。
如需完成查询配置，请参阅为已验证的查询配置参数。

创建代理，然后创建经过验证的查询

请参阅初始步骤，然后继续完成其余配置步骤，以实现已验证的查询。
在 Google Cloud 控制台中，点击新代理的已验证的查询部分中的添加查询。系统会打开添加经过验证的查询页面。
如需完成查询配置，请参阅为已验证的查询配置参数。

为已验证的查询配置参数

在问题字段中，输入经过验证的查询所回答的用户问题。
如需指定参数，请使用 @ 符号，后跟参数名称。此语法用于标识可从用户问题中提取值的占位符。使用自然语言问题，展示参数在用户问题中的使用方式。例如：“@region 仓库中 @product 的总库存是多少？”

点击 Generate SQL。相应 SQL 如下例所示：

   SELECT
       SUM(stock) AS total_stock
   FROM
       inventory
   WHERE
       product_id = @product
       AND region = @region;

如需向查询中的占位符添加默认值，请点击管理查询参数，然后点击添加查询参数。
对于第一个参数，系统会显示四个字段，分别是名称、类型、值和说明。
- 在名称字段中，复制问题中的 @product 并将其粘贴到此字段中。
- 在类型部分，选择字符串。
- 对于值，输入 organic bananas。
- 对于说明，请输入尽可能具体的说明。例如，位于区域性仓库中的商品。
对于第二个参数，请点击添加查询参数。
- 在名称字段中，复制问题中的 @region 并将其粘贴到此字段中。
- 在类型部分，选择字符串。
- 对于值，输入 US-EAST。
- 在说明中，尽可能具体地输入说明，例如 a regional warehouse where products are located.
填写完两个参数的字段后，点击保存。

测试参数化验证查询

点击运行，并验证查询是否返回了您预期的结果。
如需在后续界面中测试针对用户的查询，请复制整个问题字段。
点击保存以退出添加查询界面，然后返回到代理的修改页面。
在代理的修改页面上，将之前复制的问题字段粘贴到预览窗口中。
1. 将 @product 变量替换为 organic bananas。
2. 将 @region 变量替换为 US-EAST。
按 Enter 键。查看结果，在这种情况下，有效答案是美国东部区域的香蕉总库存量，例如 1,000。
如需创建或修改其他已验证的查询，请根据需要重复上述步骤。

现在，您已保存查询，用户可以提出以下问题：“我们是否知道美国东部仓库中有机香蕉的总库存？”然后，对话式分析会执行以下操作：

将此问题与模式进行匹配。
从问题中提取 @product 参数作为 @product =“organic bananas”，并提取 @region 参数作为“US-EAST”。
执行查询：SELECT SUM(stock) AS total_stock FROM inventory WHERE product_id = 'organic bananas' AND region = 'US-EAST';
返回计算出的 total_stock。

创建或查看术语表中的术语

您可以创建特定于代理的 BigQuery 自定义术语表术语，也可以查看从 Knowledge Catalog 导入的适用于您为代理选择的知识来源的业务术语库术语。

由于 Knowledge Catalog 中的业务术语库术语会全局应用于 BigQuery 资源，因此如果您使用 Knowledge Catalog，请在 Knowledge Catalog 中创建和管理业务术语库术语，而不是为各个代理创建和管理。
如果您需要修改从 Knowledge Catalog 导入的业务术语库术语，则必须在 Knowledge Catalog 中修改这些术语，然后返回到 BigQuery 才能看到修改后的术语。
BigQuery 自定义词汇表术语会保留在 BigQuery 中。不会显示在 Knowledge Catalog 中。
如果您未使用 Knowledge Catalog，则可以为需要为特定代理定义的术语创建 BigQuery 自定义词汇表术语。

请按照以下步骤为代理创建自定义词汇表术语：

在代理编辑器页面的词汇表部分中，点击添加术语。
在自定义条款部分，您可以修改或删除任何现有的自定义条款。
如需创建一个或多个新学期，请点击创建学期。
1. 输入术语、定义和一个或多个同义词，并以英文逗号分隔。
2. 如需创建学期，请点击添加。
3. 如果您想删除新字词，请点击删除。
如需创建更多自定义条款，请重复上述步骤。

如需查看从 Knowledge Catalog 导入的业务术语库术语，请按以下步骤操作：

在代理编辑器页面的词汇表部分中，点击添加术语。
前往名为从 Dataplex 导入的页面部分。
如需在 Knowledge Catalog 中修改导入的术语，请点击前往 Dataplex 术语库。
在 Knowledge Catalog 中修改术语后，您可以返回代理Editor页面查看修改后的术语。

配置设置

在设置部分，您可以配置以下可选设置：

在模型部分中，选择用户在与智能体对话时可以使用哪些类型的模型。默认情况下，预览版和正式版模型均可用。处于预览版状态的模型可能会使用全球端点。
创建标签，帮助您整理Google Cloud 资源。标签是键值对，可用于将相关对象组合在一起或者与其他 Google Cloud 资源组合在一起。
1. 在设置部分，点击管理标签。
2. 点击添加标签。
3. 在键和值字段中，输入标签的键值对。
4. 如果您想添加更多标签，请再次点击添加标签。
5. 如需删除标签，请点击删除。
6. 完成后，点击添加。系统会重新打开新的代理页面。
为数据代理处理的查询设置大小限制。在设置部分中，在结算字节数上限字段中输入一个值。您必须将此限制设置为 10485760 或更高值，否则您会收到以下错误消息：

Value error. In BigQuery on-demand pricing charges are
rounded up to the nearest MB, with a minimum of 10 MB of data processed
per query. So, max bytes billed must be set to greater or equal to
10485760.

如果您未指定值，则 maximum bytes billed 默认设置为项目的每日查询使用量配额。除非您指定了自定义配额，否则每日使用量配额不受限制。

继续阅读下一部分，了解如何将代理置于草稿模式或发布代理。

预览并发布代理

在预览部分中，在提出问题字段中输入示例用户问题，然后按 Enter 键。如需验证数据代理是否返回了您预期的数据，请检查代理的回答。如果回答与预期不符，请在 Editor 部分中更改设置，以优化数据代理配置，直到获得令人满意的回答。您可以继续测试和修改代理，以优化代理的回答。
点击保存。
如需将数据代理设为草稿模式，以便稍后重新修改，请点击返回，返回到代理目录页面。由于您的智能体现在处于草稿模式，因此它会显示在智能体目录标签页的我的草稿智能体部分中。

如需发布代理，请停留在代理创建页面上，然后继续执行下一步。
点击发布以发布数据代理，使其可在项目中供您使用。您可以使用 BigQuery Studio 或数据洞察与数据代理进行对话。您还可以使用 Conversational Analytics API 构建自己的界面，以便与数据代理对话。如需了解如何发布到数据洞察，请参阅在数据洞察中发布数据代理。如需了解如何发布到 Gemini Enterprise，请参阅在 Gemini Enterprise 中发布数据智能体。
可选：在您的代理已发布对话框中，点击分享，与其他用户分享数据代理。
1. 在共享权限窗格中，点击添加主账号。
2. 在新的主账号字段中，输入一个或多个主账号。
3. 点击选择角色列表。
4. 在角色列表中，选择以下角色之一：
  - Gemini Data Analytics Data Agent User (roles/geminidataanalytics.dataAgentUser)：授予与数据代理对话的权限。
  - Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor)：授予修改数据代理的权限。
  - Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer)：授予查看数据代理的权限。
点击保存。
如需返回“新建代理”页面，请点击关闭。保存或发布智能体后，您会立即在智能体目录中看到它。

管理数据代理

您可以在代理目录标签页中找到现有代理，该标签页包含三个部分：

我的代理：您创建并发布的所有代理的列表。您可以修改已发布的代理并与他人分享。
我的草稿智能体：您尚未发布的智能体。您无法共享草稿代理。
您组织中的其他人分享的代理：其他人创建并与您分享的代理。如果其他人向您授予权限，您就可以修改这些共享代理。

修改数据代理

如需修改数据代理，请按以下步骤操作：

前往 BigQuery 代理页面。

前往“代理”
选择智能体目录标签页。
找到要修改的数据代理的代理卡片。
如需在代理编辑器中打开数据代理，请依次点击 打开操作 > 代理卡片上的修改。
根据需要修改数据代理的配置。
如需保存更改但不发布，请点击保存。
如需发布更改，请点击发布。在共享对话框中，您可以与他人共享代理，也可以点击取消。
如需返回代理窗格，请点击返回。

按照以下步骤操作，即可分享已发布的数据智能体。您无法共享草稿代理。

前往 BigQuery 代理页面。

前往“代理”
选择智能体目录标签页。
找到要修改的数据代理的代理卡片。
如需在代理编辑器中打开数据代理，请依次点击 打开操作 > 代理卡片上的修改。
如需与其他用户共享数据代理，请点击共享。
在共享权限窗格中，点击添加主账号。
在新的主账号字段中，输入一个或多个主账号。
点击选择角色列表。
在角色列表中，选择以下角色之一：
- Gemini Data Analytics Data Agent User（roles/geminidataanalytics.dataAgentUser）：授予与数据代理对话的权限。
- Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor)：授予修改数据代理的权限。
- Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer)：授予查看数据代理的权限。
点击保存。
如需返回代理编辑页面，请点击关闭。
如需返回代理窗格，请点击返回。

删除数据智能体

前往 BigQuery 代理页面。

前往“代理”
选择智能体目录标签页。
在代理目录标签页的我的代理或我的草稿代理部分中，找到要删除的数据代理的代理卡片。
依次点击 打开操作 > 删除。
在删除代理？对话框中，点击删除。

当您发布智能体并与数据洞察用户共享该智能体后，该智能体会自动显示在数据洞察的与数据对话页面上，供这些用户与之对话。

创建智能体并将其发布到数据洞察

作为数据分析师，您可以完成以下步骤，在数据洞察中创建、修改和发布代理：

在 BigQuery 中创建或修改数据智能体。
发布代理。发布智能体时，请选择 数据洞察 作为发布选项。
按照说明共享代理，并向数据洞察用户授予适当的 Identity and Access Management 角色。

您可以直接与数据洞察用户分享智能体，方法是复制一个链接，该链接可在数据洞察中打开与智能体的对话，也可以发送电子邮件通知用户他们有权访问某个智能体。

如需分享指向智能体的直接链接，您可以通过以下方式复制智能体的专用网址：

在代理目录中：依次选择 打开操作 > 选择复制链接 > 选择 数据洞察。
在代理详情视图中：依次选择 复制代理链接 > 选择 数据洞察。
在分享溢出菜单中：选择复制数据洞察中代理的链接。
在共享权限面板中点击保存后：选择复制链接。

如需发送电子邮件通知，告知收件人他们对代理的访问权限，请从共享权限面板中选择发送电子邮件。电子邮件通知仅会发送给您在相应编辑会话中刚刚与之共享代理的用户或群组。即使某个用户已拥有相应代理的代理级权限，群组的所有成员也会收到电子邮件通知。该电子邮件包含分享代理的用户的名称、代理的名称，以及用于在数据洞察中打开代理的链接。

在 Gemini Enterprise 中发布数据智能体

以下部分介绍了如何在 Gemini Enterprise 中发布数据代理。此过程通常需要数据分析师、Gemini Enterprise 管理员和业务用户共同协作。如需详细了解这些用户所需的角色，请参阅必需的角色。

如需在 Gemini Enterprise 中发布数据智能体，请完成以下步骤：

创建并发布数据智能体。
配置授权详细信息。
预配代理。
发现并使用智能体。

创建并发布代理

作为数据分析师，您可以通过完成以下步骤来创建、修改智能体并将其发布到 Gemini Enterprise：

在 BigQuery 中创建或修改数据智能体。
发布代理。发布智能体时，请选择 Gemini Enterprise 作为发布选项。
复制 A2A 端点 JSON。
与 Gemini Enterprise 管理员分享 A2A 端点 JSON 和用户列表。
与需要访问权限的用户和群组共享代理。

配置授权详细信息

在 Gemini Enterprise 管理员预配代理之前，您或管理员必须配置授权详细信息，以生成 Google Cloud OAuth 客户端凭据。

如需创建 OAuth 客户端 ID 和客户端密钥，请按照配置授权详细信息中的步骤操作。

预配代理

作为 Gemini Enterprise 管理员，您可以让已发布的代理在 Google Cloud 控制台中供用户使用。

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

Gemini Enterprise
点击要向其注册代理的应用的名称。
依次点击代理 > 添加代理。
在选择代理类型部分，对于通过 A2A 构建的自定义代理，点击添加。
在代理卡片 JSON 字段中，以 JSON 格式输入您之前从数据分析师那里收到的代理卡片详细信息。如需查看可用字段的完整列表，请参阅 Agent2Agent (A2A) Protocol 规范。此示例仅使用必填字段。
依次点击预览代理详情 > 下一步。
如需允许代理代表您访问 Google Cloud 资源，请完成以下步骤：
1. 输入您在配置授权详细信息部分中生成的客户端 ID 和客户端密钥。
2. 在授权 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%2Fcloud-platform&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
```
  将 client_id 替换为您在配置授权详细信息部分中生成的客户端 ID。
3. 在 Token URI 字段中，输入以下内容：
```
https://oauth2.googleapis.com/token
```
4. 在范围字段中，输入以下内容：
```
https://www.googleapis.com/auth/cloud-platform
```
点击完成。
与数据分析师提供的用户或群组共享代理。

如需详细了解如何在 Gemini Enterprise 中使用 A2A 代理，请参阅注册和管理 A2A 代理。

发现和使用代理

您可以使用以下任一方法在 Gemini Enterprise 中发现和使用数据代理：

手动发现：在代理库中找到数据代理，然后使用以下任一方法来使用它：
- 浏览图库：选择代理，然后开始专门的对话。
- 直接链接：使用代理的专用网址直接在会话中打开 Gemini Enterprise，并使用该特定 BigQuery 数据代理。
- 定向意图：在 Gemini Enterprise 核心聊天中，通过 @mention（例如 @sales_pipeline_agent）调用智能体。
- 无缝编排：提出一个宽泛的分析问题（例如“过去 3 个月内的销售管道趋势如何？”），Gemini Enterprise 会自动将查询路由到相关的数据代理。

发现代理后，您可以按照以下步骤与其互动：

进行身份验证：完成一次性 OAuth 登录，以安全地向 BigQuery 进行身份验证。
聊天：向智能体提出自然语言问题。请求由代理处理，响应以文本、Markdown、图表或表格的形式流式传输回 Gemini Enterprise。
查看对话历史记录：对话会自动保存在历史记录窗格中。

监控智能体和对话

您可以在 BigQuery 中使用 Google Cloud Observability 监控数据代理及其对话的性能、采用率、延迟时间和费用。启用代理可观测性后，您可以查看以下指标：

对话中使用的代理数量
提出过问题的用户数量
创建的对话数量
回答问题最多的代理
最常用的知识来源
用户互动度
预计 token 用量
每小时回答延迟时间

准备工作

启用 Cloud Trace、Cloud Monitoring、Cloud Logging API。

启用 API 所需的角色

如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

启用 API

所需的角色和权限

如需启用代理可观测性，您必须拥有项目的以下权限：

cloudaicompanion.gibqObservabilitySettings.create
cloudaicompanion.gibqObservabilitySettings.list
cloudaicompanion.gibqObservabilitySettings.update
geminidataanalytics.dataAgents.create
geminidataanalytics.operations.get
observability.traceScopes.create
resourcemanager.projects.update
serviceusage.services.enable
serviceusage.values.test

如需获得使用指标、跟踪记录和日志监控代理所需的权限，请让管理员为您授予项目的以下 IAM 角色：

查看监控数据和配置：Monitoring Viewer (roles/monitoring.viewer)
查看轨迹： Cloud Trace User (roles/cloudtrace.user)
查看日志：Logs Viewer (roles/logging.viewer)
查看数据集及其内容：BigQuery Data Viewer (roles/bigquery.dataViewer)
查看管理员设置：Gemini for Google Cloud User (roles/cloudaicompanion.user)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

启用可观测性

代理可观测性默认处于停用状态。管理员可以为您的项目或组织启用此功能。如需为代理启用可观测性，请选择以下选项之一：

控制台

在 Google Cloud 控制台中，前往 BigQuery 代理页面。

前往“代理”
选择监控标签页。
如果可观测性处于停用状态，请按照提示启用它。

Google Cloud CLI

创建可观测性设置：

gcloud gemini gibq-observability-settings create SETTING_NAME \
  --conversational-analytics-setting-metrics-enabled \
  --conversational-analytics-setting-traces-enabled \
  --project=PROJECT_ID \
  --location=global

替换以下内容：

SETTING_NAME：可观测性设置的名称。
PROJECT_ID：您的项目 ID。

将可观测性设置绑定到您的项目：

gcloud gemini gibq-observability-settings setting-bindings create BINDING_NAME \
  --gibq-observability-setting=SETTING_NAME \
  --target=projects/PROJECT_ID \
  --location=global \
  --project=PROJECT_ID

将 BINDING_NAME 替换为设置绑定的名称。建议您使用 binding-PROJECT_ID 作为绑定名称。

API

创建可观测性设置：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d '{
          "conversational_analytics_setting": {
            "metrics_enabled": true
          }
        }' \
    "https://cloudaicompanion.googleapis.com/v1/projects/PROJECT_ID/locations/global/gibqObservabilitySettings?gibq_observability_setting_id=SETTING_NAME"

替换以下内容：

SETTING_NAME：可观测性设置的名称。
PROJECT_ID：您的项目 ID。

将可观测性设置绑定到您的项目：

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d '{
          "target": "projects/PROJECT_ID",
          "product": "GEMINI_IN_BIGQUERY"
        }' \
    "https://cloudaicompanion.googleapis.com/v1/projects/PROJECT_ID/locations/global/gibqObservabilitySettings/SETTING_NAME/settingBindings?setting_binding_id=BINDING_NAME"

将 BINDING_NAME 替换为设置绑定的名称。建议您使用 binding-PROJECT_ID 作为绑定名称。

查看指标

启用可观测性后，系统会收集指标。数据不会回填。如需查看客服人员指标，请选择以下选项之一：

BigQuery

在 Google Cloud 控制台中，前往 BigQuery 代理页面。

前往“代理”
选择监控标签页。

Cloud Monitoring

在 Google Cloud 控制台中，前往 Cloud Monitoring 信息中心页面。

转到“信息中心”
在我的信息中心窗格中，搜索名为 BigQuery Conversational Analytics 的信息中心。
如需打开信息中心，请点击其名称。
可选：创建自定义信息中心。
可选：如需单独查看指标，请前往 Metrics Explorer 页面。

转到 Metrics Explorer

智能体指标包括智能体使用情况、模型调用、工具使用情况、健康状况、延迟时间和 token 使用情况。

调试模型调用

您可以直观呈现对话轮次中的操作序列（例如模型调用和工具调用），以便排查错误和延迟问题。

在 Google Cloud 控制台中，前往 Cloud Monitoring Trace 探索器页面。

前往 Trace 探索器
点击某个 span 即可进行检查。
查看详细信息窗格中的信息。
可选：创建自定义轨迹信息中心。

保留轨迹

您的 Cloud Trace 数据会存储在可观测性数据集中，保留期限为 30 天。如需将轨迹数据存储更长时间，请将轨迹数据迁移到 BigQuery 数据集。

所需的角色

如需获得通过创建关联数据集将实时轨迹公开给 BigQuery 所需的权限，请让管理员向您授予项目的以下 IAM 角色：

Cloud Trace Admin (roles/cloudtrace.admin)
Observability Editor (roles/observability.editor)
BigQuery User (roles/bigquery.user)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

将轨迹数据迁移到 BigQuery

如需保留跟踪记录数据，请执行以下操作：

打开 Cloud Shell。
查找 _Trace 存储桶的位置：
```
gcloud beta observability buckets list --location=-
```
记下 _Trace 存储桶的位置，以便用于下一步。

在您的 BigQuery 项目中创建一个指向 _Trace 存储桶的关联数据集：

gcloud beta observability buckets datasets links create \
    projects/PROJECT_ID/locations/LOCATION/buckets/_Trace/datasets/Spans/links/LINK_NAME \
    --dataset=Spans \
    --bucket=_Trace \
    --location=LOCATION \
    --project=PROJECT_ID

替换以下内容：

PROJECT_ID：您的项目 ID
LOCATION：上一步中 _Trace 存储桶的位置
LINK_NAME：关联数据集的名称

创建一个标准数据集，用于存储历史轨迹。以下命令将默认分区到期时间设置为 90 天（7,776,000 秒）：

bq --location=LOCATION mk \
    --dataset \
    --default_partition_expiration=7776000 \
    --description="Archive storage for historical traces" \
    PROJECT_ID:STORAGE_DATASET

将 STORAGE_DATASET 替换为数据集的名称。

在存储数据集中创建一个空的分区表，该表具有与关联数据集相同的架构。按日期进行分区有助于您管理数据保留和查询费用。如需创建该表，请在 SQL 编辑器中运行以下查询：
```
CREATE TABLE `PROJECT_ID.STORAGE_DATASET.TABLE_NAME`
PARTITION BY DATE(start_time)
AS
SELECT *
FROM `PROJECT_ID.LINK_NAME._AllSpans`
WHERE FALSE;
```
将 TABLE_NAME 替换为表的名称。

创建预定查询，以将关联数据集中的每日轨迹数据复制到归档表中。以下查询会复制前一天的数据：

INSERT INTO `PROJECT_ID.STORAGE_DATASET.TABLE_NAME`
SELECT *
FROM `PROJECT_ID.LINK_NAME._AllSpans`
WHERE start_time >=
  TIMESTAMP_SUB(TIMESTAMP_TRUNC(CURRENT_TIMESTAMP(), DAY), INTERVAL 1 DAY)
  AND start_time < TIMESTAMP_TRUNC(CURRENT_TIMESTAMP(), DAY);

如需了解详情，请参阅如何查找和探索轨迹。

关闭可观测性

如需为数据代理关闭可观测性，请更新可观测性设置：

gcloud gemini gibq-observability-settings update SETTING_NAME \
    --no-conversational-analytics-setting-metrics-enabled \
    --no-conversational-analytics-setting-traces-enabled \
    --project=PROJECT_ID \
    --location=global

替换以下内容：

SETTING_NAME：您创建的用于启用可观测性的可观测性设置的名称。如果您使用 Google Cloud 控制台启用了可观测性，则设置名称为default。
PROJECT_ID：您的项目 ID。

后续步骤

详细了解 BigQuery 中的对话式分析。
详细了解 Conversational Analytics API。
通过对话分析数据。
详细了解 Gemini Data Analytics Data Agent Viewer (roles/geminidataanalytics.dataAgentViewer) 角色如何授予查看数据代理的权限。

创建数据代理

准备工作

所需的角色

最佳做法

生成数据分析

使用示例数据代理

创建数据代理

初始步骤

自定义表格和字段说明

创建智能体指令

创建经过验证的查询

创建参数化验证查询

工作原理

有关如何创建有效的参数化查询的提示

创建参数化验证查询

选择现有的 Gemini 建议的已验证查询

创建代理，然后创建经过验证的查询

为已验证的查询配置参数

测试参数化验证查询

创建或查看术语表中的术语

配置设置

预览并发布代理

管理数据代理

修改数据代理

共享数据代理

删除数据智能体

在数据洞察中发布数据代理

创建智能体并将其发布到数据洞察

与数据洞察用户共享您的代理

在 Gemini Enterprise 中发布数据智能体

创建并发布代理

配置授权详细信息

预配代理

发现和使用代理

监控智能体和对话

准备工作

所需的角色和权限

启用可观测性

控制台

Google Cloud CLI

API

查看指标

BigQuery

Cloud Monitoring

调试模型调用

保留轨迹

所需的角色

将轨迹数据迁移到 BigQuery

关闭可观测性

后续步骤