创建数据代理

借助对话式数据代理，您可以使用自然语言界面与数据库数据进行互动。通过构建这些代理，您可以帮助用户“与数据对话”，从而从运营数据库中发掘洞见，而无需用户编写复杂的 SQL 查询。

从宏观层面来看，数据代理是角色、一组数据源的组合，可访问一组对其用途至关重要的业务知识。

对于应用开发者，这些代理可带来以下好处：

  • 高精确度：通过使用撰写的内容，您可以针对特定的业务问题获得高精确度的回答。编写的上下文是代理创建者可用于提高准确性的主要关键因素。它包括架构说明、系统指令和结构化上下文，可提供有关预期数据库查询的其他信息。
  • 降低复杂性：智能体将自然语言转换为 SQL 查询、执行，甚至数据总结或可视化图表。
  • 灵活性：您可以起草代理以供个人测试，也可以发布代理，以便项目中的其他用户或通过 API 以编程方式使用代理。

准备工作

  1. 验证是否已为您的 Google Cloud 项目启用结算功能。

  2. 启用 Cloud SQL、Data Analytics API with Gemini 和 Gemini for Google Cloud API。

    启用 API 所需的角色

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

    启用 API

所需的角色

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

使用场景 所需的角色
创建、修改、发布、共享和删除代理
  • 在项目中创建数据代理：项目中的 Gemini Data Analytics Data Agent Creator (roles/geminidataanalytics.dataAgentCreator)。此角色会自动授予您所创建数据代理的 Gemini Data Analytics Data Agent Owner 角色。
  • 如需修改、共享或删除数据代理，您需要拥有该代理或项目的 Gemini Data Analytics Data Agent Owner (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)。

在管理对 Cloud SQL for PostgreSQL 数据库资源的访问权限时，请考虑以下权限层级：

  • Google Cloud IAM：控制对数据库实例（作为云资源）的访问权限。这包括连接、管理实例和执行 SQL 查询的权限，例如使用 executeSql 权限。
  • 数据库权限：控制对数据库中对象（例如表、视图和架构）的访问权限。这些权限通过 GRANT 等 SQL 命令以及特定于数据库的用户和角色系统进行管理。

对于 Cloud SQL for PostgreSQL，您需要具有适当的 Cloud SQL IAM 角色才能连接到实例并获得发送查询的授权。如需与表和视图等对象进行交互，连接的数据库用户必须拥有使用 Cloud SQL for PostgreSQL GRANT 系统授予的必要权限。如需了解详情，请参阅 PostgreSQL 用户和角色简介。 如果代理使用服务账号，您可以获取分配的数据库角色。例如，请参阅使用 IAM 数据库身份验证管理用户。

创建数据代理

以下部分介绍了如何创建数据代理。 创建代理后，您可以修改其设置。

配置基本信息

  1. 在 Google Cloud 控制台中，前往 Cloud SQL for PostgreSQL 页面。

    前往 Cloud SQL

  2. 从列表中选择一个实例。

  3. 在导航菜单中，点击代理。

  4. 点击代理标签页。

  5. 选择数据库，然后使用您的 IAM 账号登录。

  6. 点击新建代理 (New agent)。 系统会打开新建代理页面。

  7. 在编辑器部分的代理名称字段中，输入数据代理的描述性名称，例如 Q4 sales data 或 User activity logs。

  8. 在代理说明字段中，输入数据代理的说明。好的说明会解释智能体的用途、所使用的数据，并帮助您确定这是否是适合在对话中使用的正确数据智能体 - 例如，What are the top 10 selling products in Q2?

  9. 在知识来源部分，点击添加来源。系统会打开添加数据页面。

  10. 选择代理在回答问题时将重点关注的表。如需查看其他知识来源，请选择 显示更多。

  11. 点击添加。系统会重新打开新的代理页面。

自定义表格和字段说明

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

  • 架构说明：为表和列添加说明，帮助代理了解您的数据。如果您不添加说明，代理将使用数据定义中的架构说明。

添加表和字段说明时，请遵循以下最佳实践：

  • 向数据定义添加说明，而不仅仅是向数据代理定义添加说明。这样可确保其他客服人员也能受益于这些说明。
  • 如需设计合适的说明来帮助数据智能体了解您的数据，请为您的特定智能体添加说明。验证说明是否具有预期效果后，您可以决定是否在数据定义中添加该说明。

如需配置表和字段说明，请按以下步骤操作：

  1. 在智能体目录标签页中，打开要自定义的智能体。
  2. 点击修改代理。
  3. 在知识来源中，找到要自定义的表格，然后点击自定义。
  4. 输入表格说明。
  5. 如需修改任何字段说明，请点击相应字段旁边的 修改。系统会打开修改字段窗格。
    1. 在 ID 字段中，输入字段说明。
    2. 如需保存字段说明，请点击更新。
  6. 如需保存说明和字段更新，请点击更新。系统会重新打开新的代理页面。
  7. 针对要自定义的每个表格重复上述步骤。

为数据代理添加标签

在代理设置部分，您可以创建标签来整理 Google Cloud 资源。标签是键值对，可用于将相关对象组合在一起或者与其他 Google Cloud资源组合在一起。

  1. 在代理目录标签页中，打开要添加标签的代理。
  2. 点击修改代理。
  3. 在代理设置部分，点击添加标签。系统随即会打开管理标签窗格。
  4. 点击添加标签。
  5. 在键和值字段中，输入标签的键值对。
  6. 如果您想添加更多标签，请再次点击添加标签。
  7. 如需删除标签，请点击删除。
  8. 完成后，点击添加。系统会重新打开新的代理页面。

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

预览并发布智能体

  1. 在预览部分中，在提出问题字段中输入示例问题，然后按 Enter 键。

    如需验证数据代理是否返回了您预期的数据，请检查代理的回答。如果回答与预期不符，请在 Editor 部分中更改设置，以优化数据代理配置，直到获得令人满意的回答。您可以继续测试和修改代理，以优化代理的输出结果。

  2. 点击保存。

  3. 如需将数据代理置于草稿模式（以便稍后重新修改），请点击 返回，返回到代理目录页面。由于您的智能体现在处于草稿模式，因此它会显示在智能体目录标签页上的我的草稿智能体部分中。

    如需发布代理，请停留在代理创建页面上，然后继续执行下一步。

  4. 如需发布数据代理并使其可在项目中供使用，请点击发布。发布代理后，有权访问同一数据库表的其他用户便可以查看您的代理并与之对话，从而受益于您创建的指令和上下文。

    您可以使用 Google Cloud 控制台中的智能体页面与数据智能体创建对话。您还可以使用 Conversational Analytics API 构建自己的界面，以便与数据代理对话。

  5. 可选：在您的代理已发布对话框中，点击分享，与其他用户分享数据代理。

    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)：授予查看数据代理的权限。
    5. 点击保存。

  6. 可选：您可以将数据代理发布到 Gemini Enterprise。如需了解详情，请参阅在 Gemini Enterprise 中发布数据代理。

  7. 如需返回“新建代理”页面，请点击关闭。保存或发布智能体后，您可以在智能体目录中看到它。

管理数据代理

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

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

修改数据代理

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

  1. 在 Google Cloud 控制台中，前往 Cloud SQL for PostgreSQL 页面。

    前往 Cloud SQL

  2. 从列表中选择一个实例。

  3. 在导航菜单中，点击代理。

  4. 使用 Identity and Access Management (IAM) 身份验证登录智能体。

  5. 点击智能体目录标签页。

  6. 找到要修改的数据代理的代理卡片。

  7. 如需在智能体编辑器中打开数据智能体，请点击 打开操作，然后点击智能体卡片上的修改。

  8. 根据需要修改数据代理的配置。

  9. 如需保存更改但不发布，请点击保存。

  10. 如需发布更改，请点击发布。在分享对话框中，您可以选择与他人分享代理，也可以点击取消。

  11. 如需返回代理窗格，请点击 返回。

共享数据代理

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

  1. 在 Google Cloud 控制台中，前往 Cloud SQL for PostgreSQL 页面。

    前往 Cloud SQL

  2. 从列表中选择一个实例。

  3. 在导航菜单中，点击代理。

  4. 使用 Identity and Access Management (IAM) 身份验证登录智能体。

  5. 点击智能体目录标签页。

  6. 找到要修改的数据代理的代理卡片。

  7. 如需在智能体编辑器中打开数据智能体，请依次点击 打开操作 > 智能体卡片上的修改。

  8. 如需与其他用户共享数据代理，请点击共享。

  9. 在共享权限窗格中，点击添加主账号。

  10. 在添加主账号字段中，输入一个或多个主账号。

  11. 点击选择角色。

  12. 在角色列表中，选择以下角色之一：

    • 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)：授予查看数据代理的权限。

  13. 点击保存。

  14. 如需返回代理编辑页面，请点击关闭。

  15. 如需返回代理窗格，请点击 返回。

删除数据智能体

  1. 在 Google Cloud 控制台中，前往 Cloud SQL for PostgreSQL 页面。

    前往 Cloud SQL

  2. 从列表中选择一个实例。

  3. 在导航菜单中，点击代理。

  4. 使用 Identity and Access Management (IAM) 身份验证登录智能体。

  5. 选择智能体目录标签页。

  6. 在代理目录标签页的代理部分中，找到要删除的数据代理的代理卡片。

  7. 依次点击 打开操作 > 删除。

  8. 在删除代理？对话框中，点击删除。删除代理后，系统会从项目中永久移除该代理。

    删除智能体后，现有对话将以“只能查看”模式显示。 您无法再向已删除的代理提出新问题。

在 Gemini Enterprise 中发布数据智能体

发布数据代理需要数据分析师、Gemini Enterprise 管理员和业务用户之间的协作。如需了解这些用户所需的角色，请参阅必需的角色。

创建并发布代理

如需创建、修改和发布代理，请按以下步骤操作：

  1. 在 Cloud SQL for PostgreSQL 中创建或修改数据代理。
  2. 发布代理。发布智能体时，请选择 Gemini Enterprise 作为发布选项。
  3. 如需复制 A2A 端点 JSON，请点击 Copy JSON。
  4. 与 Gemini Enterprise 管理员分享 A2A 端点 JSON 和用户列表，以便他们可以在 Google Cloud 控制台中注册自定义代理并配置访问权限。 如需了解详情，请参阅预配代理。
  5. 与需要访问权限的用户和群组共享代理。

预配代理

如需在 Google Cloud 控制台中向用户提供已发布的代理，请按以下步骤操作：

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

    Gemini Enterprise

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

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

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

  5. 在代理卡片 JSON 字段中，以 JSON 格式输入您之前从数据分析师那里收到的代理卡片详细信息。

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

  7. 如需允许代理代表您访问 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

  8. 点击完成。

  9. 与用户或群组共享代理。

如需了解详情，请参阅注册和管理 A2A 代理。

查找和使用代理

您可以使用以下任一方法在 Gemini Enterprise 中查找和使用数据智能体：

  • 在 Agent Gallery 中找到该代理，然后开始专用对话。
  • 使用代理的专用网址直接在会话中打开 Gemini Enterprise，并与该特定的 Cloud SQL for PostgreSQL 数据代理进行交互。
  • 在 Gemini Enterprise 核心对话中输入 @mention（例如 @sales_pipeline_agent），以调用智能体。
  • 提出一般性分析问题，例如“过去 3 个月的销售渠道趋势如何？”，让 Gemini Enterprise 自动将查询路由到相关的数据代理。

找到代理后，您可以使用以下任一方法与其互动：

  • 完成一次性 OAuth 登录，以安全地向 Cloud SQL for PostgreSQL 进行身份验证。
  • 提出自然语言问题。对话式分析智能体会处理您的请求，并将回答以文本、Markdown、图表或表格的形式流式传输回 Gemini Enterprise。
  • 在历史记录窗格中查看对话记录，系统会自动保存对话。

位置

对话式分析在全球范围内运行，因此您无法选择要使用的区域。

后续步骤