创建数据代理

预览

此功能受服务专用条款的“通用服务条款”部分中的“非正式版产品条款”的约束。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

借助对话式数据智能体，您可以使用自然语言界面与数据库数据进行交互。通过构建这些代理，您可以帮助用户“与数据对话”，从运营数据库中解锁数据洞见，而无需编写复杂的 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 数据分析数据代理所有者角色。 如需修改、共享或删除数据代理，请执行以下操作：针对代理或项目的 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) 角色。 此外，您还必须拥有以下角色才能创建或修改数据代理： 添加到实例的 IAM 用户或服务账号。如需了解详情，请参阅使用 Cloud SQL 的 IAM 数据库身份验证管理用户。 在项目级向 IAM 用户授予的 cloudsql.studioUser 和 cloudsql.instanceUser 角色。如需了解详情，请参阅为项目添加 IAM 政策绑定。 可选：如果您将上下文集（预览版）与数据库数据代理搭配使用，则需要：在项目级层向 IAM 用户授予 Dataplex Catalog Editor (roles/dataplex.catalogEditor) 或 Dataplex Catalog Admin (roles/dataplex.catalogAdmin) 角色，以便创建、上传和管理上下文集。如需了解详情，请参阅上下文集权限。 以 postgres 用户身份登录，向 IAM 用户或服务账号授予数据库权限。 GRANT ALL ON SCHEMA public TO public; 如需了解详情，请参阅向单个 IAM 用户或服务账号授予数据库权限。
在 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. 在表说明中添加说明，或接受 Gemini 给出的建议。
5. 在字段中，查看 Gemini 为表中各列建议的说明。
6. 管理建议的字段说明：
   • 如需接受建议，请选择所需的说明，然后点击接受建议。
   • 如需拒绝建议，请选择所需的说明，然后点击拒绝建议。
7. 如需修改字段说明，请点击字段旁边的 修改。
   1. 在说明中，输入字段的说明。
   2. 点击更新以保存修改。
8. 点击更新，保存对表格的自定义设置。
9. 针对您要自定义的每个表格重复上述步骤。

创建经过验证的查询

注意： 只能为“引导式”模式添加经过验证的查询

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

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

1. 在代理目录标签页中，打开要自定义的代理。
2. 点击修改代理。

3. 在已验证的查询中，点击查看 Gemini 生成的建议。

   1. 在查看建议的经过验证的查询中，查看建议的经过验证的查询。
   2. 选择适用于您的用例的查询。
   3. 点击添加，将查询添加到上下文。
   注意： 如需修改建议的查询，请展开建议的查询，然后点击修改。

4. 可选。如需创建您自己的经过验证的查询，请在经过验证的查询中点击添加查询。

   1. 在问题中，输入可通过已验证的查询回答的问题。
   2. 点击生成 SQL，让 Gemini 生成与您添加的问题相对应的已验证查询。
   3. 点击运行，并验证查询是否返回了您预期的结果。
   4. 查看回答，并根据需要修改经过验证的查询。
   5. 点击 Add（添加）。

5. 重复上述步骤，创建更多经过验证的查询。

为数据代理添加标签

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

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

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

预览并发布代理

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

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

2. 点击保存。

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

   如需发布智能体，请留在智能体创建页面，然后继续执行下一步。

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

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

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

   1. 在共享权限窗格中，点击添加主账号。
   2. 在新的主账号字段中，输入一个或多个主账号。
   3. 点击选择角色列表。
   4. 在角色列表中，选择以下角色之一：
      • Gemini 数据分析 Data Agent User (roles/geminidataanalytics.dataAgentUser)：授予与数据代理对话的权限。
      • Gemini 数据分析 Data Agent Editor (roles/geminidataanalytics.dataAgentEditor)：授予修改数据代理的权限。
      • Gemini 数据分析 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 数据分析数据代理用户 (roles/geminidataanalytics.dataAgentUser)：授予与数据代理对话的权限。
    • Gemini Data Analytics Data Agent Editor (roles/geminidataanalytics.dataAgentEditor)：授予修改数据代理的权限。
    • Gemini 数据分析 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，请点击复制 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. 在令牌 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。
• 在历史记录窗格中查看对话记录，对话会自动保存在该窗格中。

位置

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

后续步骤

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