利用代理技能构建数据产品

概览

本指南介绍了如何将 GitHub 代码库中由 Cortex Framework 直接提供的专业 Cortex Framework 代理技能与 AI 编码助理（例如与 Antigravity 代理开发框架搭配使用的 Gemini）搭配使用，以构建遵循 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) 图和主键。

利用这些智能体技能开发数据产品是一个迭代过程。您可以从最初的目标着手，查看智能体提出的实施方案（包括实体关系图和架构），并要求 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 会在启动时自动发现、编入索引并激活所有工作区技能。无需进行其他配置。如需验证，请向助理提出以下问题：

    您有哪些技能？

  • 使用 Gemini Code Assist 的 VSCode：

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

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

    读取 .agents/skills/ 目录中的 create-data-product 技能并搭建脚手架…

创建自定义数据产品

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

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

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

创建面向 SAP S/4HANA 和 ECC 的“应付账款数据洞见”Cortex Framework 数据产品。使用命名空间：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 代码，并执行必要的 build 检查来验证更改。

最佳做法和限制

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