Conversational Analytics API 版本说明

这些版本说明适用于 Conversational Analytics API 的更新。

2026 年 6 月 23 日

Conversational Analytics API 更新：

通知

Conversational Analytics API 现已正式发布 (GA)，适用于 BigQuery 和 Looker。

如需了解价格，请参阅 Data Cloud Agent 价格和免费试用。

功能

Conversational Analytics API 支持 v1 REST 端点。

功能

Conversational Analytics API 现已支持数据驻留。您可以使用单区域和多区域端点来控制 DataAgent 和 Conversation 资源的实际位置。这些端点可针对静态数据提供承诺，并根据您的数据源，针对使用中的数据提供管辖区机器学习 (ML) 处理。如需了解详情，请参阅数据驻留和位置。

功能

Conversational Analytics API 支持以下企业安全和合规性功能：

• 客户管理的加密密钥 (CMEK)，用于保护数据代理和对话
• VPC Service Controls，以保护服务边界内的资源
• Cloud Audit Logs，用于记录管理员活动和数据访问权限
• 数据保留和删除，以支持企业数据擦除和保留政策

功能

Conversational Analytics API 现在支持 预览版中的 agent-to-agent (A2A) 协议。您可以使用新的 API 方法（例如 SendMessage、SendStreamingMessage 和 GetAgentCard）来编排多个代理。如需查看如何使用这些方法的示例，请参阅 A2A SDK 示例笔记本。

功能

Conversational Analytics API 现在支持对列表方法进行过滤和排序。使用 filter 字段可缩小数据智能体、对话和消息的搜索结果范围。使用 orderBy 字段按名称或创建时间对数据代理进行排序。

• 对于数据代理，您可以按名称、创建时间和标签进行过滤。
• 对于对话，您可以按关联的客服人员和标签进行过滤。
• 对于消息，您可以按创建时间进行过滤。
• 对于包含 has (:) 运算符和尾随星号 (*) 的字符串过滤器，系统支持使用通配符。示例：filter=display_name:"*" 或 filter=display_name:"foo*"。
• 系统会按近期活动时间顺序返回对话和消息；这些资源不支持自定义排序。

功能

此版本包含以下针对 BigQuery 数据源的功能和改进：

• 您现在可以在代理的配置中使用 big_query_max_billed_bytes 字段来限制代理启动的 BigQuery 作业的结算字节数。
• 数据智能体现在可以引用用于生成回答的来源，例如术语表条目或示例查询。
• 您现在可以提供自定义 BigQuery 用户定义函数 (UDF)，供代理用于回答问题。
• 如果用户的问题与定义的示例查询充分匹配，智能体可能会直接执行该查询，而不是生成新的查询。发生这种情况时，API 响应会包含一个 matchedQuery 对象，以表明使用了经过验证的查询。

功能

Conversational Analytics API 现在支持与 BigQuery Graph 对话。此功能处于预览版阶段。

已更改

v1 API 存在以下变更和弃用：

• v1 版本不支持图表的 SVG 和 PNG 格式。ChartOptions 中的 options.chart 字段仅限用于 v1alpha 和 v1beta 版本。
• context 字段（例如 dataAgentContext.credentials）下的 credentials 字段已弃用。对于身份验证，请直接在 ChatRequest 对象中提供凭据。
• 系统生成的澄清消息 (systemMessage.clarification) 已弃用。请改用 TextMessage 和 FINAL_RESPONSE 文本类型。

2026 年 4 月 16 日

Conversational Analytics API 更新：

功能

Conversational Analytics API 现在支持查询连接到 Apache Iceberg REST 目录或联合到外部目录的 Lakehouse 表。如果您使用的是 Lakehouse 表，请使用四部分 project.catalog.namespace.table (P.C.N.T) 语法。 如需了解详情，请参阅进行身份验证并连接到数据源。

2026 年 3 月 30 日

Conversational Analytics API 更新：

功能

对话式分析 API 现在支持将 AlloyDB for PostgreSQL、Cloud SQL for MySQL、Cloud SQL for PostgreSQL 和 Spanner 用作数据源。借助此功能，用户可以使用自然语言查询其运营数据，并将复杂的人类对话转换为精确的数据库查询，从而提供可据以采取行动的分析洞见。此功能处于预览版阶段。 详情请参阅以下内容：

• AlloyDB 对话式分析概览
• Cloud SQL for MySQL 对话式分析概览
• Cloud SQL for PostgreSQL 对话式分析概览
• Spanner 对话式分析概览

功能

针对 BigQuery 数据源的 Conversational Analytics API 更新包括以下功能和改进：

• Conversational Analytics API 现在通过 ObjectRef 函数与 Cloud Storage 集成。这样一来，API 就可以通过引用任何表中的 ObjectRef 列来回答有关 Cloud Storage 存储分区中非结构化数据（例如图片和 PDF）的问题。
• 该 API 现在支持一组 BigQuery ML 函数，包括 AI.FORECAST、AI.DETECT_ANOMALIES 和 AI.GENERATE。该 API 可以使用这些函数来回答更广泛的问题，例如用于预测、异常检测和生成式 AI 任务。
• Conversational Analytics API 现在可以使用 BigQuery 表分区。该 API 可以在按日期分区的表上使用分区列（例如日期范围）来优化 SQL 查询，从而提高查询性能并降低费用。

• 由对话式分析 API 启动的 BigQuery 作业现在包含标签，可让您在 Google Cloud 控制台的 BigQuery 作业历史记录中识别这些作业。这些标签有助于监控费用、审核代理活动和分析查询性能。由于这些标签不会直接显示在 BigQuery Studio 作业历史记录表中，因此您可以通过查询 INFORMATION_SCHEMA.JOBS 查找与 {'ca-bq-job': 'true'} 类似的标签来识别它们：

  SELECT
    COUNT(*) AS job_count
  FROM
    `PROJECT_ID`.`region-LOCATION`.INFORMATION_SCHEMA.JOBS
  WHERE
    EXISTS (
      SELECT 1
      FROM UNNEST(labels) AS label
      WHERE label.key = 'ca-bq-job' AND label.value = 'true'
    );

  在示例查询中，您需要按如下所示替换示例值：

  • PROJECT_ID：您的 Google Cloud 项目 ID。
  • LOCATION：BigQuery 作业的位置。

功能

对于使用 Looker 或 BigQuery 数据源的数据代理，您现在可以在聊天请求中指定 thinkingMode 值为 FAST，以启用“快速”思考模式。快速思考有助于缩短总体思考时间，从而缩短延迟时间。不过，在此模式下，由于响应流中不会发出 TextType 值为 THOUGHT 的消息，因此答案的透明度会降低。此外，使用此模式可能会影响回答的准确性。

功能

对于使用 Looker 数据源的数据代理，代理现在可以提出后续问题，以消除查询中的歧义，例如当存在多个名称相似的字段时。这些问题会以 TextMessage 响应的形式返回，并带有 Clarification needed: 前缀。如需了解详情，请参阅提出有效的问题。

功能

对于使用 BigQuery 数据源的数据代理，该代理现在可以提出后续问题，以澄清查询中的歧义，例如当有多个名称相似的字段时。这些问题以 TextMessage 响应的形式返回。

已更改

对于使用 Looker 数据源的数据代理，我们进行了一些改进来缩短延迟时间，包括并行工具调用和更好地利用 Looker 缓存。

2026 年 3 月 26 日

Conversational Analytics API 更新：

功能

对于使用 Looker 数据源的 Conversational Analytics API，您可以使用客户管理的加密密钥 (CMEK) 来帮助保护静态 DataAgent 和 Conversation 资源。Conversational Analytics API 中的 CMEK 处于预览版状态。如需了解详情，请参阅客户管理的加密密钥 (CMEK)。

2026 年 2 月 11 日

Conversational Analytics API 更新：

功能

现在，包含 BigQuery 数据源的 Chat 请求可以更深入地了解代理的推理过程。虽然 API 架构保持不变，但您会在响应流中看到以下新行为：

• API 响应流现在包含额外的 systemMessage.text 消息，其中包含 textType = THOUGHT。这些消息可让您逐步了解代理的推理和决策流程。
• 在 THOUGHT 消息之后，API 会以一系列消息（例如查询、作业、文本、数据结果和图表消息）的形式返回答案。如需详细了解消息类型，请参阅 SystemMessage。
• BigQuery 数据源的响应流中不再包含架构消息。

功能

提供同步代理管理方法。这些方法可让您同步创建、更新和删除数据代理，作为现有异步方法的替代方案：

• CreateDataAgentSync
• UpdateDataAgentSync
• DeleteDataAgentSync

已更改

BigQuery 数据源不再支持 Python 分析选项 (options.analysis.python.enabled)。

2026 年 2 月 6 日

Conversational Analytics API 更新：

功能

对于使用 Looker 数据源的数据代理，您现在可以将 Looker 黄金查询定义为结构化上下文。

2026 年 1 月 26 日

Conversational Analytics API 更新：

功能

改进了推理透明度，可提供有关智能体推理和决策过程的逐步洞见（通过 textType = THOUGHT 消息实现），不再需要许可名单，并且适用于所有用户（对于 Looker 数据源）。

功能

针对 Looker 数据源的精细数据检索功能（通过 textType = PROGRESS 消息提供有关数据值搜索的更新）不再需要许可名单，所有用户都可以使用。

2025 年 12 月 15 日

Conversational Analytics API 更新：

功能

Looker 数据源的 API 响应流包含其他带有 textType = THOUGHT 的 systemMessage.text 消息。这些消息可让您逐步了解代理在回答查询时所用的推理和决策流程。如需运行演示此推理过程的对话示例，请参阅 HTTP 和 Python SDK Colaboratory 笔记本。如需有关使用 Looker 数据源呈现 THOUGHT 消息的指南，请参阅呈现 Looker 数据源的智能体回答。这是一项实验性功能的早期公告，该功能可应要求提供。如需请求访问此功能，请发送邮件至 [e-mail]。

注意：自 2026 年 1 月 26 日起，此功能不再需要列入许可名单，并且适用于所有用户，可用于 Looker 数据源；请参阅 2026 年 1 月 26 日的条目。

功能

对于 Looker 数据源，代理会使用更精细的方法来检索探索架构和数据值。当代理搜索特定数据值时，API 流还会包含带有 textType = PROGRESS 的 systemMessage.text 消息，用于提供有关搜索状态和结果的更新。如需有关呈现 PROGRESS 消息的指南，请参阅呈现 Looker 数据源的智能体回答。这是一项实验性功能的早期公告，该功能可应要求提供。如需请求访问此功能，请发送邮件至 [e-mail]。

注意：自 2026 年 1 月 26 日起，此功能不再需要列入许可名单，并且适用于所有用户，可用于 Looker 数据源；请参阅 2026 年 1 月 26 日的条目。

功能

对话分析 API 与 VPC Service Controls 的集成处于预览状态。此项产品集成已为更广泛的测试和使用做好准备，但尚未完全支持生产环境。如需了解详情，请参阅支持的产品列表。

已修复

修复了 big_query_max_billed_bytes 未正确应用的问题。

已修复

修复了 API 处理 Looker 数据源时存在的问题，包括：

• 改进了文本回答中的值格式
• 更精准地过滤完全匹配项
• 改进了同比 (PoP) 指标支持
• 完善了 always_filter 支持

客户端库更新：

功能

添加了以下客户端库：

• Node.js (v1beta)
• Java (v1beta)
• Go (v1beta)
• Ruby (v1beta)

2025 年 10 月 21 日

Conversational Analytics API 更新：

功能

向 REST API 和 SDK 添加了对 deleteConversation API 方法的支持。

2025 年 9 月 25 日

Conversational Analytics API 更新：

功能

现在提供了一个新的 API ListAccessibleDataAgents，用于列出用户在项目中可访问的数据代理。如果调用 API 的用户对数据代理具有 get 权限，则认为该数据代理可供访问。您可以使用 creator_filter 字段来管理此方法返回哪些代理：

• NONE（默认）：返回用户可访问的所有数据代理，无论创建者是谁。
• CREATOR_ONLY：仅返回用户创建的数据代理。
• NOT_CREATOR_ONLY：仅返回由其他用户创建的数据代理。

功能

现在，systemMessage.text.textType 枚举提供 FINAL_RESPONSE 和 THOUGHT 值，可帮助客户端区分不同类型的消息。Conversational Analytics API 现在使用包含 textType = THOUGHT 的 systemMessage.text 消息来生成思考步骤。

功能

该 API 现在支持最多五个 Looker Explore 数据源。Chat 请求会在最相关的探索中生成查询。如需了解详情，请参阅有关通过 HTTP 和通过 Python SDK 连接到 Looker 数据的文档。

已更改

systemMessage.data.generatedLookerQuery 字段现在为 systemMessage.data.query.looker。

2025 年 8 月 25 日

通知

Conversational Analytics API 现已推出公开预览版。

客户端库更新：

功能

以下客户端库现已支持多种语言：

• PHP (v1beta)
• DotNet (v1beta)
• Python (v1beta)

Conversational Analytics API 更新：

功能

现在支持适用于 HTTP REST 的 v1beta 端点。

功能

向 REST API 和 SDK 添加了对 GetLocation 和 ListLocations API 方法的支持。

功能

您现在可以使用 GetIamPolicy 和 SetIamPolicy API 方法共享数据代理。

功能

您现在可以通过基于使用专用 IP 网络的 Looker (Google Cloud Core) 实例的 Looker 数据源构建数据代理。（Conversational Analytics API 不支持基于位于虚拟私有云边界内的 Looker [Google Cloud Core] 实例的数据源。）

功能

BigQuery 数据源的结构化上下文现已推出。这包括能够使用 API 在表和字段级别添加示例问题/查询对、表说明、同义词和标记。

已更改

现在支持位置和操作 API。DataAgentCreator 和 DataAgentEditor Identity and Access Management 角色现在拥有适用于操作 API 的权限。

已更改

我们对以下功能进行了增强：每当数据代理的已发布上下文更新时，在服务器层自动存储 Last Published Context。

已更改

Identity and Access Management 角色的显示名称已更新为“Gemini Data Analytics Stateless Chat User”和“Gemini Data Analytics Data Agent Creator”。如需详细了解与该 API 搭配使用的 Identity and Access Management 角色，请参阅授予 Conversational Analytics API Identity and Access Management 角色和权限文档页面。

已更改

Colaboratory 版本 1.1 现已推出。

已修复

更新了错误处理功能，以便为有状态聊天处理对话相关 500 内部错误。

已修复

针对 400 客户端错误实现了更完善的异常处理消息。

文档更新：

功能

您现在可以使用 GitHub 上的 Streamlit 快速入门应用在几分钟内设置 Conversational Analytics API 的演示。

功能

Conversational Analytics API 黄金版演示现已在 GitHub 上推出。借助 Conversational Analytics API 黄金版演示，您可以查看将 Conversational Analytics API 集成到 Web 应用中的示例，以及使用 TypeScript 编写的完整生产演示。此项目仅用于演示目的。它不适用于生产环境。

功能

我们为 REST API 和 SDK 添加了请求载荷代码示例。

功能

Conversational Analytics API 架构、工作流和角色：详细了解使用 Conversational Analytics API 的关键概念，包括数据代理的工作方式、典型的数据代理工作流、对话模式、Identity and Access Management 角色，以及如何设计使用多个数据代理的系统。

功能

Conversational Analytics API 已知限制：详细了解数据源数量、可视化图表样式和数据集大小方面的限制。

功能

排查 Conversational Analytics API 错误：详细了解 Conversational Analytics API 的潜在问题或错误，以及建议的解决方案。

功能

监控和管理 Conversational Analytics API 代理的 BigQuery 费用：详细了解如何为 Conversational Analytics API 代理实现费用控制。

功能

Conversational Analytics API 概览文档页面上提供了 SetIAMPolicy 和 GetIAMPolicy 方法，用于共享数据代理。

功能

我们现已推出一个新文档页面，其中包含 Conversational Analytics API 的常见问题解答。

功能

为 BigQuery 数据源定义数据代理上下文：详细了解如何为 BigQuery 数据源编写系统指令。

功能

为 Looker 数据源定义数据代理上下文：详细了解如何为 Looker 数据源编写系统指令。

2025 年 7 月 15 日

功能

您现在可以通过分配预定义 IAM 角色，邀请用户协作处理特定数据代理。如需了解详情，请参阅 Conversational Analytics API IAM 角色和权限。

功能

新的最佳实践指南可帮助您为代理提供有效的业务和数据上下文。如需了解详情，请参阅使用编写的上下文来引导代理行为。

SDK 更新：

功能

您现在可以从 Python 软件包索引 (PyPI) 安装 Python SDK。

2025 年 6 月 25 日

API 更新：

功能

新的预定义 IAM 角色可控制用于创建、管理数据代理以及与数据代理互动的访问权限：

• geminidataanalytics.dataAgentCreator
• geminidataanalytics.dataAgentOwner
• geminidataanalytics.dataAgentEditor
• geminidataanalytics.dataAgentUser
• geminidataanalytics.dataAgentViewer
• geminidataanalytics.dataAgentStatelessUser

如需查看角色及其权限的完整列表，请参阅授予 Conversational Analytics API IAM 角色和权限。

2025 年 6 月 5 日

通知

Conversational Analytics API 的初始非公开预览版引入了用于创建数据代理并与之互动的各项功能。

功能

以下交互式 Colaboratory 笔记本可帮助您开始使用 REST 和 Python SDK：

• HTTP Colab 笔记本
• Python SDK Colab 笔记本

API 更新：

功能

借助 Data Agent Service，您可以使用 Looker、数据洞察 和 BigQuery 以程序化方式创建、配置和管理持久的情境感知 AI 智能体。

功能

借助 Data Chat Service，您可以使用多种聊天模式与代理进行对话。这些模式包括有状态模式（Google 管理对话历史记录）、有状态选项（您的应用管理对话）以及无状态模式（您的应用在每次请求中提供完整上下文）。

功能

该 API 支持使用 Python 进行高级分析，并会自动重试失败的查询。

已更改

Conversational Analytics API (geminidataanalytics.googleapis.com) 取代了已弃用的 Data QnA API (dataqna.googleapis.com)。这包括从 DataQuestionService 迁移到新的 DataChatService。有关如何更新请求的详细说明，请参阅迁移指南。