Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

エージェントスキルを使用してデータプロダクトを構築する

概要

このガイドでは、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:
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 を使用します。主なビジネス要件は、ベンダー全体の未払い額と延滞額を追跡し、会社コード別に買掛金回転率を計算することです。

なお、プロンプトで既存の要件や仕様書を直接参照することもできます。これらのドキュメント（マークダウンなどの構造化された形式で記述できます）は、エージェントに次のような重要なコンテキストを提供します。

ビジネスコンテキストとドメイン: 詳細な目標、ユーザーストーリー、ターゲットユーザー。
入力データ仕様: ソーステーブル（LFA1、BSIK、BSEG、Z... など）、バージョン管理の詳細（ECC と S/4HANA）、除外ルール、カスタムフィールドなどのリスト。
変換ロジックとビジネスルール: コアマッピングの制約、クライアントフィルタリング（mandt）、削除（復元可能）（loekz）、支払いブロックインジケーター（zlspr）マッピングの処理、調整ルール（たとえば、売上高の偏りを避けるために企業間ベンダー取引を除外するなど）。
データの整合性とテストアサーション: 検証シナリオ（粒度のユニークネスの検証、最終出力の未払いの請求書金額の合計が元のソーステーブルと完全に一致することの確認など）。

ステップ 2: 実装計画を確認する

要件を概説すると、エージェントは query-sap-ddic スキルなどの複数のスキルを使用して、未加工の BigQuery DDIC メタデータテーブルをクエリします。これにより、エージェントは必要なソーステーブルを特定して検証し、フィールドの型とリレーションシップが正確であることを確認できます。また、エージェントは他のスキルを呼び出して、要件が Cortex Framework のベストプラクティスに完全に沿っていることを確認することもあります。

実装を開始する前に、エージェントは簡単な実装計画を提示します。このプランには、特定されたソーステーブル、マッピング、データプロダクトの提案されたアーキテクチャ構造が含まれます。このプランを確認し、調整が必要な場合は、確定する前にリクエストしてください。

ステップ 3: データプロダクトを生成する

実装計画を確認したら、エージェントは create-data-product スキルを使用してディレクトリ構造をスキャフォールディングします。これにより、指定したカスタム Namespace で、新しいカスタム開発がコアプラットフォームの更新から分離されます。

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 ロールが保持されていることを確認します。
コンテキストの上限: 数十個のテーブルを含む非常に大規模なデータプロダクトを構築している場合、エージェントがコンテキストを失う可能性があります。より小さなアトミックな指示（たとえば、まずヘッダーレベルのディメンションを作成し、次に別のフォローアッププロンプトでアイテムレベルのファクトを追加するようエージェントに指示するなど）を提供することで、成功率を高めます。

エージェント スキルを使用してデータ プロダクトを構築する

概要