エージェント スキルを使用してデータ プロダクトを構築する
概要
このガイドでは、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 コード アーティファクトを自動的に生成します。
- データ品質ゲート: ローカルビルドの実行、SQL コードのコンパイル、単体テストと統合テストの実行、命名規則への準拠の検証により、データ プロダクトを検証します。
- ドキュメントの作成: データ プロダクト モジュールのエンティティ関係(ER)図や主キーの可視化など、ドキュメント アセットを自動的に作成します。
これらのエージェント スキルを使用してデータ プロダクトを開発することは、反復的なプロセスです。最初の目標から始めて、ER 図やスキーマを含むエージェントの提案された実装計画を確認し、AI アシスタントに会話形式でロジックを改良するよう依頼できます。 エージェントは開発を加速しますが、生成されたすべてのコードをレビューして承認し、リポジトリに commit するのは、すべてユーザーの管理下で行われます。さらに、これらのエージェント スクリプトは認証済みの認証情報を使用してローカルで実行されるため、既存の Google Cloud と BigQuery のアクセス制限が自動的に適用されます。
前提条件
エージェント スキルを使用する前に、開発環境が次の要件を満たしていることを確認してください。これにより、ライブスキーマ クエリ、データ コンパイル、自動検証が可能になります。
Google Cloud SDK(
gcloud): ユーザー アカウントを使用して(gcloud)CLI をインストールして認証します。詳細については、デプロイのドキュメントをご覧ください。アプリケーションのデフォルト認証情報(ADC): ローカルのコンパイル ツールと pytest スイートが BigQuery と通信できるように、ローカルの ADC とプロジェクト ターゲットを構成します。詳細については、デフォルトの Google Cloud プロジェクトを準備するをご覧ください。
複製された SAP データ ディクショナリ(DDIC)テーブル: エージェントが大文字と小文字を区別しないスキーマ チェックを実行し、フィールド長を正確に検証できるようにするには、次の SAP メタデータ テーブルを未加工のターゲット BigQuery データセットに複製します。
DD03L(テーブル フィールド)DD04T(データ要素テキスト)DD08L(テーブルの関係)DD01L(ドメイン)DD07L(ドメイン値 - 省略可)DD07T(ドメイン値のテキスト - 省略可)
ローカル Python 環境: ローカル依存関係をインストールし、
uvを使用して同期ツールを実行して、検証ライブラリと単体テストが適切に機能することを確認します。詳細については、ドキュメントをご覧ください。
セットアップと IDE の構成
始める前に、お好みの AI コーディング アシスタント(Antigravity など)のドキュメントを参照して、インストールと設定の手順を確認してください。
必要なインストール アーティファクトを収集し、リポジトリのクローンを作成します。詳細については、インストール アーティファクトをご覧ください。
指定した AI コーディング アシスタント内で、クローン作成した Google Cloud Cortex Framework のソースコード フットプリントを開きます。
Google Cloud Cortex Framework は、リポジトリの .agents/skills/ ディレクトリにある一連の特殊なスキルを通じて、エージェント機能を公開します。これらのスキルは、複数の開発環境で使用できます。
Antigravity フレームワーク: Antigravity は、起動時にすべてのワークスペース スキルを自動的に検出、インデックス登録、有効化します。追加の設定作業は必要ありません。確認するには、アシスタントに次のように話しかけます。
どのようなスキルが利用可能ですか?
Gemini Code Assist を使用した VSCode:
- VS Code Marketplace から Gemini Code Assist 拡張機能をインストールします。
cortex-framework-coreフォルダをワークスペースとして開きます。アシスタントは、.agents/skills/ディレクトリからスキルを自動的にスキャンして読み込みます。
その他の AI CLI ツール: 指示プロンプトでスキル ディレクトリをネイティブに参照します。次に例を示します。
.agents/skills/ ディレクトリ内の create-data-product スキルを読み取り、スキャフォールディングします...
カスタム データ プロダクトを作成する
次の手順は、エージェント スキルを使用してカスタム データ プロダクトを作成するための、構造化されたデベロッパー ワークフローの概要を示しています。
ステップ 1: 要件とコンテキストを提供する
AI コーディング アシスタントのチャット インターフェースを使用して、特定のデータ要件を記述するプロンプトを入力します。次に例を示します。
SAP S/4HANA と ECC を対象とした Accounts Payable Insights の 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: 品質ゲートを実行してデータを検証する
付与された権限に応じて、エージェントは次の必須の検証ゲートを自動的に実行するか、実行を求めるプロンプトを表示します。このプロセス全体を通じて、エージェントは詳細なステータス レポートを生成するため、結果を確認できます。
- ビルド検証:
uv run cortex-build --config config/config.yamlを実行して、生成されたすべての SQL モデルが正常にコンパイルされることを確認し、ビルドの概要を生成します。 - Pytest の実行: Python 単体テストの完全なスイートを実行し、コア ビジネス ロジックとアサーションを検証するテスト実行レポートを出力します。
- linter と監査:
validate-data-productスキルを活用して、厳格なフィールド パリティ チェックを実行し、命名規則の遵守を検証します。最後に、詳細な準備状況レポートを作成します。
ステップ 5: デプロイと実行
検証レポートを確認し、生成されたコードを承認したら、データ プロダクト アセットをデプロイする準備が整います。
- アセットをデプロイする: デプロイ スクリプトをローカルで実行して(例: uv run cortex-deploy --config config/config.yaml)、コンパイルされたデータ プロダクト定義を構成済みの Dataform ワークスペースに push します。
- データをマテリアライズする: デプロイ後の最終ワークフローを完了して、生成された Dataform パイプラインを実行し、新しいテーブルとビューを BigQuery 内で直接マテリアライズします。
- 分析情報を提供する: 実体化されたカスタム データ プロダクトは、Gemini Enterprise などのダウンストリーム分析アプリに接続して、元のビジネス上の質問に対してインテリジェントで実用的な回答を提供できるようになります。
既存のデータ プロダクトを更新する
カスタム データ プロダクトを構築した後は、変更を加えるために最初からやり直す必要はありません。update-data-product スキルを活用して、新しいフィールドの追加、ビジネス ロジックの調整、まったく新しいソーステーブルの統合を繰り返し行うことができます。次に例を示します。
custom_finance AP データ プロダクトを更新します。LFA1 ソーステーブルからお支払い期限フィールド(ZTERM)を追加し、最終出力ビューに適切にマッピングされていることを確認します。完了したら、ビルド検証を実行します。
エージェントは構成を特定し、BigQuery DDIC にクエリを実行して正確なフィールド要件を取得し、Dataform コードを更新して、必要なビルドチェックを実行して変更を検証します。
ベスト プラクティスと制限事項
- スキーマクエリの失敗: エージェントが SAP メタデータ スキーマを取得できない場合は、ローカルのアプリケーションのデフォルト認証情報(ADC)が有効で、ターゲットの未加工データセットに対する BigQuery データ閲覧者の IAM ロールを保持していることを確認します。
- コンテキストの上限: 数十のテーブルを含む非常に大規模なデータ プロダクトを構築している場合、エージェントがコンテキストを失う可能性があります。より小さく、アトミックな指示を提供することで、成功率を高めます(たとえば、エージェントにヘッダーレベルのディメンションを最初に構築させ、その後、別のフォローアップ プロンプトでアイテムレベルのファクトを追加するよう指示します)。