利用智能体技能构建数据产品

概览

本指南介绍了如何将 Cortex Framework 在 GitHub 代码库中直接提供的专用 Cortex Framework 代理技能与 AI 编码助理（例如 Gemini 与 Antigravity 代理开发框架搭配使用）结合使用，以构建遵循 Cortex Framework 最佳实践的自定义数据产品。

Cortex Framework 提供专门的智能体技能来扩展其功能，使您的 AI 助理能够指导您按照 Cortex Framework 最佳实践构建数据产品。借助这些功能，您可以使用自然语言根据特定业务需求请求新的数据产品。例如，您可以请求应付账款消费数据产品，以深入了解应付总额、逾期金额和周转率。最终，您将获得一个完全集成的 Cortex Framework 数据产品，该产品基于您的客户特定要求和数据构建，可随时执行。

代理技能

智能体技能是一种轻量级开放格式，可利用专业知识和工作流来扩展 AI 智能体功能。技能的核心是一个文件夹，其中包含一个 SKILL.md 文件（包含元数据和指令），以及可选的脚本、参考资料和资产，用于指示智能体如何执行特定任务。技能将程序性知识和上下文打包到可移植文件夹中，智能体可按需加载这些文件夹，从而提供领域专业知识和可重复的工作流。Cortex Framework 技能存储在 .agent 目录中。

Cortex Framework 智能体技能

代理式数据产品构建器可自动执行 Cortex Framework 中数据产品的端到端开发生命周期。通过指示 AI 助理执行结构化开发工作流，您无需再手动搭建文件结构、浏览复杂的 SAP 架构、配置基础层、管理自定义命名空间以及编写样板 Dataform SQLX 代码。

AI 助理负责管理以下核心任务：

  • 规划和需求映射：将具体的业务需求转化为可执行的数据建模和开发计划。
  • 实时架构查找：执行查询复制的 SAP 数据字典 (DDIC) 表的脚本，以提供客户特定的上下文信息，例如自定义 Z 字段。
  • 样板脚手架：自动生成所有必需的配置文件、元数据以及 SQLX 或 JavaScript 代码工件。
  • 数据质量门：通过运行本地 build、编译 SQL 代码、执行单元测试和集成测试以及验证是否符合命名标准来验证数据产品。
  • 文档创建：自动创建文档资源，包括直观呈现数据产品模块的实体关系 (ER) 图和主键。

利用这些智能体技能开发数据产品是一个迭代过程。您可以从初始目标开始，查看智能体提出的实施方案（包括 ER 图和架构），并让 AI 助理在您操作时通过对话方式优化逻辑。 虽然智能体可以加快开发速度，但您仍拥有完全控制权，可以在提交到代码库之前查看并批准所有生成的代码。此外，由于这些智能体脚本使用您经过身份验证的凭据在本地执行，因此它们会自然遵循您现有的 Google Cloud 和 BigQuery 访问权限限制。

前提条件

在使用智能体技能之前，请验证您的开发环境是否满足以下要求，以便启用实时架构查询、数据编译和自动验证：

  1. Google Cloud SDK (gcloud)：使用您的用户账号安装 (gcloud) CLI 并进行身份验证。如需了解详情，请参阅部署文档

  2. 应用默认凭证 (ADC)：配置本地 ADC 和项目目标，以便本地编译工具和 pytest 套件可以与 BigQuery 通信。如需了解详情，请参阅准备默认 Google Cloud 项目

  3. 复制的 SAP 数据字典 (DDIC) 表：为了让代理能够执行不区分大小写的架构检查并准确验证字段长度，请在原始目标 BigQuery 数据集中复制以下 SAP 元数据表：

    • DD03L（表字段）
    • DD04T（数据元素文本）
    • DD08L（表关系）
    • DD01L（网域）
    • DD07L（网域值 - 可选）
    • DD07T（网域值文本 - 可选）

  4. 本地 Python 环境：安装本地依赖项，并使用 uv 运行同步工具，以确保验证库和单元测试正常运行。如需了解详情，请参阅相关文档。

设置和 IDE 配置

在开始之前，请参阅您首选 AI 编码助理（例如 Antigravity）的文档，了解安装和设置说明。

  1. 收集所需的安装工件并克隆代码库。如需了解详情，请参阅安装工件。

  2. 在指定的 AI 编码助理中打开克隆的 Google Cloud Cortex Framework 源代码。

Google Cloud Cortex Framework 通过一组位于代码库 .agents/skills/ 目录中的专用技能来提供智能体功能。您可以在多个开发环境中使用这些技能：

  • Antigravity 框架：Antigravity 会在启动时自动发现、索引和激活所有工作区技能。您无需进行其他配置。如需验证，请向 Google 助理询问：

    您有哪些技能？

  • VSCode with Gemini Code Assist：

    1. 从 VS Code Marketplace 安装 Gemini Code Assist 扩展程序。
    2. 以工作区形式打开 cortex-framework-core 文件夹。助理会自动扫描并加载 .agents/skills/ 目录中的技能。

  • 其他 AI CLI 工具：在指令提示中原生引用技能目录。例如：

    Read the create-data-product skill inside the .agents/skills/ directory and scaffold…

创建自定义数据产品

以下步骤概述了使用智能体技能创建自定义数据产品的结构化开发者工作流。

第 1 步：提供要求和背景信息

使用 AI 编码助理的对话界面，提供描述具体数据要求的提示。例如：

为 Accounts Payable Insights 创建一个 Cortex Framework 数据产品，目标是 SAP S/4HANA 和 ECC。使用命名空间：custom_finance。主要业务要求是跟踪所有供应商的应付总额和逾期金额，并按公司代码计算应付账款周转率。

请注意，您也可以直接在提示中引用现有的需求或规范文档。这些文档（可以是 Markdown 或其他结构化格式）可为智能体提供重要的上下文信息，例如：

  • 业务背景和领域：详细目标、用户故事和目标消费者。
  • 输入数据规范：源表列表（例如 LFA1、BSIK、BSEG、Z...）、版本控制详细信息（ECC 与 S/4HANA）、排除规则、自定义字段等。
  • 转换逻辑和业务规则：核心映射限制、客户过滤 (mandt)、软删除 (loekz)、处理付款冻结指示器 (zlspr) 映射以及对账规则（例如，排除公司间供应商交易，以避免营业额率失真）。
  • 数据完整性和测试断言：验证场景（例如，验证粒度唯一性，并确保最终输出中的待付账单金额总和与原始源表完全一致）。

第 2 步：查看实施计划

在您概述要求后，代理会使用多种技能（例如 query-sap-ddic 技能）来查询原始 BigQuery DDIC 元数据表。这样，代理便可识别并验证您所需的源表，确保字段类型和关系准确无误。该智能体还可能会调用其他技能，以确保您的要求与 Cortex Framework 最佳实践完全一致。

在开始实施之前，智能体会提供一份简要的实施方案供您审核。此计划包括已确定的源表、映射和数据产品的建议架构结构。请先查看此方案，并提出任何必要的调整要求，然后再确认。

第 3 步：生成数据产品

在您确认实施计划后，智能体会利用 create-data-product 技能来搭建目录结构。这样，您在指定自定义命名空间下的新自定义开发内容便可与核心平台更新隔离开来：

src/data_modules/<custom_namespace>/products/<dataproductname>/
├── manifest.yaml
├── table_settings.default.yaml
├── README.md
├── definitions/
│   └── [ecc|s4]/
│       └── <product_name>.js
└── annotations/
    └── [ecc|s4]/
        └── <product_name>.yaml

如需详细了解文件夹结构和各个文件，请参阅可扩展性指南文档。

在此阶段，您还可以让智能体使用 generate-er-diagram 技能自动直观呈现关系，或使用 create-python-tests 技能搭建断言。

第 4 步：运行质量门并验证数据

根据所授予的权限，智能体将自动执行以下强制性验证关卡，或提示您运行这些关卡。在此过程中，智能体会生成精细的状态报告，以便您查看结果：

  1. 构建验证：执行 uv run cortex-build --config config/config.yaml，确保所有生成的 SQL 模型均成功编译，并生成构建摘要。
  2. Pytest 执行：运行完整的 Python 单元测试套件，输出测试执行报告，以验证核心业务逻辑和断言。
  3. Linter 和审核：利用 validate-data-product 技能执行严格的字段一致性检查，并验证是否符合命名规范，最后生成详细的就绪情况报告。

第 5 步：部署和执行

查看验证报告并批准生成的代码后，您就可以部署数据产品资产了。

  • 部署资产：通过在本地执行部署脚本（例如 uv run cortex-deploy --config config/config.yaml），将编译后的数据产品定义推送到配置的 Dataform 工作区。
  • 具体化数据：完成最终的部署后工作流，以执行生成的 Dataform 流水线，从而直接在 BigQuery 中具体化新表和视图。
  • 提供数据洞见：自定义数据产品物化后，即可连接到下游分析应用（例如 Gemini Enterprise），针对您最初的业务问题提供智能、可操作的答案。

更新现有数据产品

自定义数据产品构建完成后，您无需从头开始进行修改。您可以利用 update-data-product 技能，以迭代方式添加新字段、调整业务逻辑或集成全新的源表。例如：

更新我的 custom_finance AP 数据产品。从 LFA1 源表中添加支付条件字段 (ZTERM)，并确保其正确映射到最终输出视图。完成后，运行 build 验证。

智能体将找到配置，查询 BigQuery DDIC 以获取确切的字段要求，更新 Dataform 代码，并执行必要的构建检查来验证更改。

最佳做法和限制

  • 架构查询失败：如果智能体无法提取 SAP 元数据架构，请验证您的本地应用默认凭据 (ADC) 是否有效，并拥有目标原始数据集的 BigQuery Data Viewer IAM 角色。
  • 上下文限制：如果您要构建涉及数十个表的超大型数据产品，代理可能会丢失上下文。提供更小、更原子化的指令（例如，指示智能体先构建标题级维度，然后在单独的后续提示中添加项级事实），以提高成功率。