🗂️ 技術調査 - Agents Schema
目次

⚠️ 非公開(zenn 未公開)

🗂️ 技術調査 - Agents Schema

調査対象: Agents Schema (Fivetran / Open Data Infrastructure) — GitHub fivetran/agents_schema
ライセンス: MIT / 調査時点の最新リリース: v0.0.6(2026-04 リポジトリ公開、Development Status: Alpha)/ 対応 destination: Snowflake のみ
調査日: 2026-06-04

概要

Agents Schema は、AI エージェントがウェアハウスデータを正確にクエリするために必要なコンテキストを、ウェアハウス内の標準スキーマ AGENTS として提供する OSS 標準です。Fivetran, Inc. が開発・維持し、Open Data Infrastructure (ODI) イニシアティブのもとで公開されています。

位置づけは「コードリポジトリにおける AGENTS.md のデータ版」です。コードリポジトリに AGENTS.md を置いてエージェントにプロジェクト理解を与えるように、データウェアハウスに AGENTS スキーマを置いてエージェントにデータ理解を与えます。

主な対象は、dbt や Snowflake を運用しつつ、AI エージェントに社内データを触らせ始めたチームです。メトリクス定義やフィルタ条件をエージェントが推測してしまう問題に、ウェアハウス内のメタデータで答えを与えます。

解決する課題

エージェントはテーブルスキーマだけでは不十分なコンテキスト、すなわち「テーブルの用途・管理者・変換元・クエリコスト・他テーブルとの関係」を必要とします。この情報は従来、wiki・Slack スレッド・ダッシュボード・暗黙知として分散していました。エージェントはそれらを収集する手段を持たないため、metric 定義・フィルタ・スキーマを推測して誤クエリを生みます。

Agents Schema はこれらのコンテキストをウェアハウス内に集約し、エージェントがクエリインターフェースから離れずに参照できる単一の標準場所を提供します。

用途

次の用途に特化した consumer-facing な discovery layer です。

  • どのキュレーションテーブル・セマンティックオブジェクトが存在するか
  • どのシステムがメタデータを提供しているか
  • dbt モデル・LookML オブジェクト・OSI セマンティックモデルがどのデータセットを裏づけているか
  • ソースが陳腐化していないか、データプロダクトのオーナーは誰か

Agents Schema は専門システム・ソースネイティブ API・開発時ツールの代替ではありません。dbt MCP server のように dbt リポジトリを編集するエージェントは引き続きソースファイル・アーティファクトを直接使います。Agents Schema はウェアハウスを起点として既存データのコンテキストを得る consumer 用途に限定されます。

特徴

  • オープン形式・オープンソース・オープンコネクタ: 仕様 (SPEC.md)・CLI・GitHub Actions ワークフローを MIT ライセンスで公開します。
  • メタデータのみ、データ移動なし: ビジネスデータはウェアハウスに留まり、メタデータ(モデル定義・カラム説明・依存関係・セマンティック定義)だけを AGENTS スキーマに書き込みます。
  • SQL で直接クエリ可能: SELECT 文でアクセスできるため、Cursor・Claude Code・ノートブック・内製エージェントなど、ウェアハウスに接続できるあらゆるツールが追加設定なしで読めます。
  • 自己文書化する AGENTS.ROOT: provider registry として機能し、どの provider が何のテーブルを提供しているかを consumer が最初に参照できます。
  • ソース別テーブルファミリー: dbt・LookML・OSI を独立したテーブル群として提供し、各 source の ingestion が自分のファミリーだけを管理します。
  • CREATE OR REPLACE による冪等な再生成: 各インジェスト実行はテーブルファミリーを丸ごと置き換えるため、再実行で状態が一意に確定します。consumer はこれらを手編集不可の生成メタデータとして扱います。
  • クロスソースクエリ: LOOKML_VIEW と DBT_MODEL を結合するなど、複数 provider のテーブルを JOIN して横断的な文脈を得られます。
  • GitHub Actions ネイティブ: 既存リポジトリに reusable workflow を数行追加するだけで CI/CD パイプラインとして動作し、プロジェクト変更のたびに AGENTS を自動更新できます。

隣接技術との比較

比較軸 Agents Schema information_schema MCP サーバー セマンティックレイヤー本体 dbt MCP server / ソースネイティブ API
配置場所 warehouse 内 (AGENTS スキーマ) warehouse 内 (標準スキーマ) warehouse 外 (エージェント実行環境) warehouse 外 (専用サービス / ファイル) warehouse 外 (開発環境 / CI/CD)
アクセス方法 SQL (SELECT) SQL (SELECT) 専用 API / ツール呼び出し GraphQL / JDBC / SDK 専用 CLI / REST API
provider 横断性 複数 provider を統合 単一 warehouse の物理メタデータのみ provider 依存 単一ツールのエコシステム内 ツール固有
主な用途 consumer discovery DDL 構造確認・内部処理 tools / actions の公開 BI 向けメトリクス一元管理 開発時の編集・テスト・リネージ
データ移動 なし (メタデータのみ) なし なし (ツール経由) クエリ委譲 なし
再生成方式 CREATE OR REPLACE (冪等) warehouse が自動管理 — ソース変更で反映 ソース変更で反映

公式 README は次のように位置づけます。

"It is closest in spirit to information_schema, but extensible across many providers. Compared with MCP servers, Agents Schema is narrower: it publishes context inside the warehouse, while MCP servers can expose tools, actions, and source-specific workflows."

ユースケース別の参照テーブル

ユースケース 参照テーブル
利用可能なメタデータ provider の一覧確認 AGENTS.ROOT
MRR・ARR などのメトリクス定義取得 AGENTS.OSI_METRIC / AGENTS.LOOKML_MEASURE
dbt モデルの用途・スキーマ・タグ確認 AGENTS.DBT_MODEL
カラムの意味・型の確認 AGENTS.DBT_COLUMN
dbt DAG の依存を再帰トレース AGENTS.DBT_DEPENDENCY
BI 向けの explore・view の把握 AGENTS.LOOKML_EXPLORE / AGENTS.LOOKML_VIEW
セマンティックモデルの dataset・関係確認 AGENTS.OSI_DATASET / AGENTS.OSI_RELATIONSHIP
LookML view と dbt model の対応付け AGENTS.LOOKML_VIEW JOIN AGENTS.DBT_MODEL

エージェント向けの差別化要素は ai_context 列です。LookML / OSI 由来のオブジェクトは description(人間向け説明)に加えて ai_context(エージェント向けの明示的な指示)を保持できます。たとえば「このメトリクスは必ず currency_code でフィルタする」「historical データのため当年ではなく最新年で集計する」といった制約を ai_context に書くと、エージェントは推測せずその指示に従えます。既存のセマンティックレイヤーが無い段階で OSI ファミリーから着手し、既に dbt / LookML を運用していればその provider をそのまま取り込む、という使い分けが自然です。

構造

C4 model の 3 段階で内部アーキテクチャを図解します。次は公式が示す全体フローです。

Agents Schema 公式概要図。ソースリポジトリ → GitHub Actions → CLI → Snowflake AGENTS スキーマ → AI エージェントの流れを示す

出典: fivetran/agents_schema リポジトリ README(assets/agents-schema-overview.png)

システムコンテキスト図

ワークフロー設定認証情報登録 メタデータ取得トリガー ソースファイル提供 正規化メタデータ書き込み AGENTS テーブルを SQL で参照 データエンジニア/ アナリティクスエンジニア AI エージェントクライアント Agents Schemaシステム メタデータソースdbt / LookML / OSI CI/CD 基盤GitHub Actions データウェアハウスSnowflake

要素説明

要素名 説明
データエンジニア / アナリティクスエンジニア ワークフローを設定し WAREHOUSE_CREDENTIALS シークレットを登録する人間アクター。
AI エージェント クライアント AGENTS.* テーブルを SQL で読み取りデータの文脈を得る consumer。Cursor / Claude Code / Codex / ノートブック等が該当する。
Agents Schema システム メタデータを取り込み・正規化・書き込む本システム。本図ではブラックボックス扱い。
メタデータソース dbt project の manifest.json、LookML の *.lkml、OSI の *.osi.yaml を提供する外部リポジトリ。
CI/CD 基盤 GitHub Actions。ユーザーリポジトリのワークフローから reusable workflow を呼び出すオーケストレーター。
データウェアハウス Snowflake。AGENTS スキーマを保持する書き込み先かつクエリ先。

コンテナ図

ユーザーリポジトリ Agents Schema システム Snowflake ウェアハウス uses: pinned tag で呼び出し ファイル読み込み MERGE upsert CREATE OR REPLACE / INSERT CREATE OR REPLACE / INSERT CREATE OR REPLACE / INSERT checkout + 実行 CLI 起動 正規化データ渡し メタデータソースmanifest.json / lkml / osi.yaml 呼び出し元ワークフローagents-schema-dbt.yml 等 再利用可能ワークフローagents-schema-dbt/looker/osi.yml Composite Action.github/actions 配下 agents-schema CLIPython パッケージ Destination 層SnowflakeDestination AGENTS.ROOTプロバイダーレジストリ dbt テーブルファミリーDBT_MODEL / COLUMN / DEPENDENCY LookML テーブルファミリーLOOKML_VIEW / DIMENSION 等 OSI テーブルファミリーOSI_DATASET / FIELD 等

UserRepo サブグラフ

要素名 説明
呼び出し元ワークフロー ユーザーリポジトリが配置する .github/workflows/*.yml。uses: 行に pinned tag を指定して reusable workflow を呼び出し、WAREHOUSE_CREDENTIALS シークレットを渡す。

AgentsSchemaSystem サブグラフ

要素名 説明
再利用可能ワークフロー fivetran/agents_schema が提供する agents-schema-dbt.yml / agents-schema-looker.yml / agents-schema-osi.yml。workflow_call で公開される。
Composite Action .github/actions/agents-schema-dbt 等。リポジトリ checkout 後に呼ばれ、必要なら managed dbt parse で manifest を生成してから CLI を起動する。
agents-schema CLI agents-schema Python パッケージ。argparse サブコマンドでソースを選択し、メタデータを正規化する中心エンジン。
Destination 層 SnowflakeDestination クラス。SQL 生成と snowflake.connector 経由の書き込みを担う。

Warehouse サブグラフ

要素名 説明
AGENTS.ROOT プロバイダーレジストリ。各 source の ingestion が自身の行を MERGE で upsert し、他 provider の行は保持する。
dbt テーブルファミリー AGENTS.DBT_MODEL / AGENTS.DBT_COLUMN / AGENTS.DBT_DEPENDENCY。実行ごとに CREATE OR REPLACE TABLE + INSERT で全置換される。
LookML テーブルファミリー AGENTS.LOOKML_VIEW / AGENTS.LOOKML_DIMENSION / AGENTS.LOOKML_MEASURE / AGENTS.LOOKML_EXPLORE。
OSI テーブルファミリー AGENTS.OSI_DATASET / AGENTS.OSI_FIELD / AGENTS.OSI_METRIC / AGENTS.OSI_RELATIONSHIP。

コンポーネント図

agents-schema CLI destinations.py 内部 warehouse_type_from_env open_destination open_destination open_destination upsert_rows ROOT 内部に実装 型検証 dbt サブコマンド looker サブコマンド osi サブコマンド upsert_provider_root upsert_provider_root upsert_provider_root adapter-package サブコマンド カラムリスト保持 TableSchema を受け取る JSON/YAML パース cli.pyargparse エントリポイント dbt.pymanifest.json パーサー lookml.pylkml パーサー osi.pyosi.yaml パーサー root.pyROOT レジストリ destinations.py書き込みエンジン config.py設定バリデーター dbt_profiles.pyprofiles パーサー TableSchemaテーブル定義 dataclass Columnカラム定義 dataclass SnowflakeDestination書き込みクラス warehouse_credentials_from_env認証情報パーサー

CLI サブグラフ

要素名 説明
cli.py argparse でサブコマンド dbt / looker / osi を定義し、対応モジュールの run() を呼び出す。
dbt.py target/manifest.json を読み込み、resource_type=model のノードを走査して DBT_MODEL / DBT_COLUMN / DBT_DEPENDENCY の行を生成する。
lookml.py *.lkml を再帰スキャンし、view / explore ブロックと内部の dimension / dimension_group / measure を解析して LookML 4 テーブルの行を生成する。
osi.py *.osi.yaml を読み込み、semantic_model オブジェクトから OSI 4 テーブルの行を生成する。
root.py ROOT_ENTRIES 辞書で provider 別の説明行を保持し、upsert_provider_root() が AGENTS.ROOT へ MERGE する。
destinations.py TableSchema / Column dataclass によるテーブル定義、SnowflakeDestination による SQL 生成・実行、認証情報読み込みを担う。
config.py ConfigError 例外と SUPPORTED_WAREHOUSE_TYPES 定数を提供する。
dbt_profiles.py profiles.yml から dbt アダプターパッケージ名を解決する補助モジュール。agents-schema-dbt-adapter-package サブコマンドが使用する。

destinations.py 内部

要素名 説明
TableSchema テーブル名・カラムリスト・主キーを保持する frozen dataclass。array_indexes プロパティで VARIANT カラムの位置を返す。
Column カラム名・型種別 (varchar / text / boolean / array)・nullable フラグを保持する frozen dataclass。
SnowflakeDestination replace_table()(CREATE OR REPLACE TABLE)、upsert_rows()(MERGE INTO、1000 行バッチ)、insert_rows()(INSERT INTO、1000 行バッチ)を実装する。VARIANT カラムには PARSE_JSON(%s) プレースホルダを使用する。
warehouse_credentials_from_env 環境変数 WAREHOUSE_CREDENTIALS を JSON または YAML でパースする。type: snowflake 必須、key-pair 認証またはパスワード認証を受け付ける。

データ

概念モデル

AGENTS スキーマ全体の所有関係と参照関係を示します。

AGENTS スキーマ dbt table family LookML table family OSI table family dbt provider を登録 lookml provider を登録 osi provider を登録 model_id 参照 DAG edge upstream / downstream view_name 参照 view_name 参照 from_view 参照 dataset_name 参照 from / to 参照 ROOTprovider registry DBT_MODEL DBT_COLUMN DBT_DEPENDENCY LOOKML_VIEW LOOKML_DIMENSION LOOKML_MEASURE LOOKML_EXPLORE OSI_DATASET OSI_FIELD OSI_METRIC OSI_RELATIONSHIP

概念モデル説明

エンティティ 分類 役割
ROOT core provider registry。全 provider が (provider, key) の組で行を upsert する。
DBT_MODEL dbt table family dbt manifest.json の model ノード 1 件を 1 行で表す。
DBT_COLUMN dbt table family DBT_MODEL に属する documented column を正規化して格納する。
DBT_DEPENDENCY dbt table family dbt DAG の直接依存エッジ。upstream / downstream の id ペアを保持する。
LOOKML_VIEW LookML table family LookML の view ブロック 1 件を 1 行で表す。
LOOKML_DIMENSION LookML table family LOOKML_VIEW に属する dimension / dimension_group ブロックを格納する。
LOOKML_MEASURE LookML table family LOOKML_VIEW に属する measure ブロックを格納する。
LOOKML_EXPLORE LookML table family LookML の explore ブロック 1 件を 1 行で表す。from_view で LOOKML_VIEW を参照する。
OSI_DATASET OSI table family semantic_model.datasets の dataset 1 件を 1 行で表す。
OSI_FIELD OSI table family OSI_DATASET に属するフィールドを格納する。
OSI_METRIC OSI table family semantic_model.metrics の metric 1 件を 1 行で表す。
OSI_RELATIONSHIP OSI table family dataset 間の結合関係を 1 行で表す。

情報モデル

ROOT と 12 の source テーブル、計 13 テーブルの主要属性を示します。

ROOT + provider: varchar + key: varchar + content: text DBT_MODEL + unique_id: varchar + name: varchar + schema_name: varchar + materialization: varchar + description: text + file_path: varchar + tags: array DBT_COLUMN + model_id: varchar + column_name: varchar + data_type: varchar + description: text DBT_DEPENDENCY + upstream_id: varchar + downstream_id: varchar + upstream_type: varchar + downstream_type: varchar LOOKML_VIEW + name: varchar + sql_table_name: varchar + label: varchar + description: text + ai_context: text + file_path: varchar LOOKML_DIMENSION + view_name: varchar + field_name: varchar + field_kind: varchar + type: varchar + sql: text + description: text + ai_context: text + primary_key: boolean LOOKML_MEASURE + view_name: varchar + measure_name: varchar + type: varchar + sql: text + description: text + ai_context: text + filters: text LOOKML_EXPLORE + name: varchar + from_view: varchar + label: varchar + description: text + ai_context: text + file_path: varchar OSI_DATASET + name: varchar + source_table: varchar + primary_key: array + description: text + ai_context: text OSI_FIELD + dataset_name: varchar + field_name: varchar + label: varchar + description: text + ai_context: text + is_time_dimension: boolean + expression: text OSI_METRIC + name: varchar + description: text + ai_context: text + expression: text OSI_RELATIONSHIP + name: varchar + from_dataset: varchar + to_dataset: varchar + from_columns: array + to_columns: array model_id 1 many upstream / downstream many many view_name 1 many view_name 1 many from_view many 1 dataset_name 1 many from / to 1 many

OSI_METRIC は他エンティティと関係線を持ちません。これは OSI 仕様上 semantic_model.metrics が semantic_model.datasets と並列のトップレベル要素であり、metric が特定 dataset への外部キーを持たない設計を反映したものです。

AGENTS.ROOT(PK: provider + key)

カラム 型 意味(ソースフィールド対応)
provider varchar metadata contributor の短い識別子。dbt / lookml / osi など lowercase で記録する。
key varchar provider 内でユニークな識別子。テーブル文書化行では unprefixed table 名を使う慣習(例: model → AGENTS.DBT_MODEL)。
content text provider が公開したい任意のテキスト。Markdown が自然だが plain text でも可。

AGENTS.DBT_MODEL(PK: unique_id)

カラム 型 意味(ソースフィールド対応)
unique_id varchar manifest の node key。例: model.package.model_name。
name varchar node.name。
schema_name varchar node.schema。
materialization varchar node.config.materialized。
description text node.description。欠損時は空文字列。
file_path varchar node.original_file_path。
tags array (VARIANT) node.tags を PARSE_JSON でシリアライズした JSON 配列。

AGENTS.DBT_COLUMN(PK: model_id + column_name)

カラム 型 意味(ソースフィールド対応)
model_id varchar 親モデルの unique_id。
column_name varchar node.columns のキー。
data_type varchar column.data_type。欠損時は空文字列。
description text column.description。欠損時は空文字列。

AGENTS.DBT_DEPENDENCY(PK: upstream_id + downstream_id)

カラム 型 意味(ソースフィールド対応)
upstream_id varchar node.depends_on.nodes のエントリ(依存先の unique_id)。
downstream_id varchar 現在のモデルの unique_id。
upstream_type varchar upstream_id の最初の . より前のプレフィックス。. が無い場合は unknown。
downstream_type varchar 現行の dbt ingestion では常に model。

AGENTS.LOOKML_VIEW(PK: name)

カラム 型 意味(ソースフィールド対応)
name varchar view ブロック名。
sql_table_name varchar view の sql_table_name。
label varchar view の label。
description text view の description。
ai_context text view の ai_context。
file_path varchar LookML ディレクトリからの .lkml 相対パス。

AGENTS.LOOKML_DIMENSION(PK: view_name + field_name)

カラム 型 意味(ソースフィールド対応)
view_name varchar 親 view 名。
field_name varchar dimension または dimension_group のブロック名。
field_kind varchar dimension または dimension_group の区別。
type varchar フィールドの type。
sql text フィールドの sql。LookML ;; ターミネータを除去して格納する。
description text フィールドの description。
ai_context text フィールドの ai_context。
primary_key boolean フィールドの primary_key を boolean として解析した値。

AGENTS.LOOKML_MEASURE(PK: view_name + measure_name)

カラム 型 意味(ソースフィールド対応)
view_name varchar 親 view 名。
measure_name varchar measure ブロック名。
type varchar measure の type。
sql text measure の sql。;; ターミネータを除去して格納する。
description text measure の description。
ai_context text measure の ai_context。
filters text measure の filters プロパティ。現行パーサは JSON 化せず、捕捉した生の LookML テキスト値をそのまま TEXT に格納する。consumer 側で解釈する。

AGENTS.LOOKML_EXPLORE(PK: name)

カラム 型 意味(ソースフィールド対応)
name varchar explore ブロック名。
from_view varchar explore の from。欠損時は explore 名と同値。
label varchar explore の label。
description text explore の description。
ai_context text explore の ai_context。
file_path varchar LookML ディレクトリからの .lkml 相対パス。

AGENTS.OSI_DATASET(PK: name)

カラム 型 意味(ソースフィールド対応)
name varchar dataset の name。
source_table varchar NOT NULL dataset の source。欠損時は NULL ではなく空文字列を挿入する。
primary_key array (VARIANT) dataset の primary_key を PARSE_JSON でシリアライズした JSON 配列。
description text dataset の description。欠損時は空文字列。
ai_context text dataset の ai_context。欠損時は空文字列。

AGENTS.OSI_FIELD(PK: dataset_name + field_name)

カラム 型 意味(ソースフィールド対応)
dataset_name varchar 親 dataset の name。
field_name varchar フィールドの name。
label varchar フィールドの label。
description text フィールドの description。欠損時は空文字列。
ai_context text フィールドの ai_context。欠損時は空文字列。
is_time_dimension boolean field.dimension.is_time が truthy のとき true、それ以外は false。
expression text field.expression.dialects[].expression の先頭エントリ。

AGENTS.OSI_METRIC(PK: name)

カラム 型 意味(ソースフィールド対応)
name varchar metric の name。
description text metric の description。欠損時は空文字列。
ai_context text metric の ai_context。欠損時は空文字列。
expression text metric.expression.dialects[].expression の先頭エントリ。

AGENTS.OSI_RELATIONSHIP(PK: name)

カラム 型 意味(ソースフィールド対応)
name varchar relationship の name。
from_dataset varchar relationship の from(起点 dataset 名)。
to_dataset varchar relationship の to(終点 dataset 名)。
from_columns array (VARIANT) NOT NULL relationship の from_columns を PARSE_JSON した JSON 配列。
to_columns array (VARIANT) NOT NULL relationship の to_columns を PARSE_JSON した JSON 配列。

型システムと識別子の重要事実

内部 kind Snowflake 格納型 挿入方法
varchar VARCHAR そのまま文字列として渡す。
text TEXT そのまま文字列として渡す。
boolean BOOLEAN Python の bool 値として渡す。
array VARIANT json.dumps でシリアライズし PARSE_JSON(%s) プレースホルダ経由で挿入する。

Python パッケージ内部はテーブル名・カラム名を lowercase で定義します。Snowflake へはクォートなしの unquoted identifier として送出するため、Snowflake は格納時に自動的に UPPERCASE へ変換します。実際のウェアハウスオブジェクトは AGENTS.DBT_MODEL・AGENTS.LOOKML_VIEW・AGENTS.OSI_DATASET のような大文字名として存在します。

NOT NULL 制約は、各テーブルの PK 構成カラムすべてと、DBT_MODEL.name・OSI_DATASET.source_table・OSI_RELATIONSHIP.from_columns/to_columns に付きます。PK カラムは定義上 NOT NULL です。ただし「欠損時は空文字列を挿入する」カラムは、制約上 NOT NULL でも意味的には空になりうる点に注意します。

OSI_FIELD.expression と OSI_METRIC.expression には、OSI YAML の expression.dialects[] のうち先頭エントリの式だけを格納します。複数 dialect が定義されていても残りは取り込まれません。consumer は格納された式が必ずしも Snowflake 方言である保証がない点に注意し、AI_CONTEXT の指示を優先します。

構築方法

前提条件

対応 destination は Snowflake のみです("more coming soon")。各メタデータソースに必要なファイルは次のとおりです。

ソース 必須ファイル 備考
dbt <dbt-project-dir>/target/manifest.json 無ければ commit するか、managed dbt parse で生成する。
LookML <lookml-dir>/*.lkml Looker プロジェクトのディレクトリを指定する。
OSI <osi-dir>/*.osi.yaml Open Semantic Interchange YAML を配置する。

CLI を直接使う場合は Python 3.11 以上が必要です(依存: cryptography / pyyaml / snowflake-connector-python)。

必須パラメータ一覧

CLI サブコマンドの必須引数

サブコマンド 必須引数 説明
dbt --project-dir target/manifest.json を含む dbt プロジェクトのパス。
looker --lookml-dir *.lkml ファイルが存在するディレクトリのパス。
osi --osi-dir *.osi.yaml ファイルが存在するディレクトリのパス。

WAREHOUSE_CREDENTIALS secret の必須キー

キー 必須/任意 説明
type 必須 snowflake 固定。
account 必須 Snowflake アカウント識別子。
user 必須 接続ユーザー名。
warehouse 必須 使用するウェアハウス名。
database 必須 書き込み先データベース名。
role 任意 実行ロール名。
private_key_pem / private_key_path / password いずれか 1 つ必須 認証手段。key-pair(private_key_pem または private_key_path)を推奨する。
private_key_passphrase 任意 private_key_pem が暗号化されている場合のみ必要。

Secret 設定

GitHub リポジトリの Actions secret に WAREHOUSE_CREDENTIALS を 1 つ作成します。形式は YAML または JSON を受け付けます。

type: snowflake
account: abc123
user: AGENTS_SCHEMA_BOT
warehouse: COMPUTE_WH
database: ANALYTICS
role: TRANSFORMER
private_key_pem: |
  -----BEGIN ENCRYPTED PRIVATE KEY-----
  MIIEvQIBADANBgkqh...
  -----END ENCRYPTED PRIVATE KEY-----
private_key_passphrase: your-passphrase
  • role は省略可能です。
  • 非暗号化キーは -----BEGIN PRIVATE KEY----- / -----END PRIVATE KEY----- マーカーを使い、private_key_passphrase を省略します。暗号化キーは -----BEGIN ENCRYPTED PRIVATE KEY----- マーカーで判別できます。
  • account は Snowflake の新方式 orgname-accountname か、旧方式の account locator(locator.region.cloud)のいずれかを使います。接続できない場合はこの形式の取り違えを疑います。

Workflow 配線 — dbt

dbt プロジェクトのリポジトリに次の workflow ファイルを配置します。

name: Agents Schema dbt

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  agents-schema-dbt:
    uses: fivetran/agents_schema/.github/workflows/agents-schema-dbt.yml@v0.0.6
    with:
      dbt-project-dir: dbt_project
    secrets: inherit

workflow は <dbt-project-dir>/target/manifest.json を読み込み、AGENTS.DBT_MODEL / AGENTS.DBT_COLUMN / AGENTS.DBT_DEPENDENCY に書き込みます。

manifest.json が存在しない場合、Composite Action は次の 3 択で対応します。いずれも満たさないとエラーになります。

  1. target/manifest.json を事前に commit しておく。
  2. managed dbt parse: dbt-profile-name(input)と DBT_PROFILES_YML(secret)の両方を渡す。Action がこの 2 つを揃って検知したときだけ dbt parse を実行する。
  3. カスタムコマンド: dbt-parse-command(input)で manifest 生成コマンドを直接指定する。

オプション入力と secret は次のとおりです。

入力 / secret 種別 説明
dbt-profile-name input managed dbt parse に必要なプロファイル名。DBT_PROFILES_YML と必ずペアで指定する。
dbt-target input (任意) profiles.yml が複数ターゲットを持つ場合に指定する。
dbt-parse-command input (任意) manifest 生成に使うカスタムコマンド(選択肢 3)。
DBT_PROFILES_YML secret managed dbt parse 用の profiles.yml 内容。dbt-profile-name と必ずペアで指定する。

managed dbt parse の内部では、補助コマンド agents-schema-dbt-adapter-package が profiles.yml の選択ターゲットから adapter type を読み取り、対応する dbt アダプターパッケージ名を出力します。現行マッピングは snowflake → dbt-snowflake のみです。Composite Action は uvx でこのアダプターを取り込んでから dbt parse --no-partial-parse を実行し、target/manifest.json を生成します。profiles.yml が複数ターゲットを持つ場合は dbt-target の指定が必要です。

Workflow 配線 — Looker

name: Agents Schema Looker

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  agents-schema-looker:
    uses: fivetran/agents_schema/.github/workflows/agents-schema-looker.yml@v0.0.6
    with:
      lookml-dir: lookml
    secrets: inherit

Workflow 配線 — OSI

name: Agents Schema OSI

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  agents-schema-osi:
    uses: fivetran/agents_schema/.github/workflows/agents-schema-osi.yml@v0.0.6
    with:
      osi-dir: osi
    secrets: inherit

workflow は AGENTS.OSI_DATASET / AGENTS.OSI_FIELD / AGENTS.OSI_METRIC / AGENTS.OSI_RELATIONSHIP を書き込みます。

Workflow 配線 — 複数ソース同時

1 つのリポジトリで dbt + LookML + OSI を同期する場合は、各 job を同一 workflow に並べます。job 間の依存関係は不要です。公式サンプルとして examples/workflows/dbt-looker.yml と examples/workflows/dbt-looker-osi.yml が用意されています。

jobs:
  agents-schema-dbt:
    uses: fivetran/agents_schema/.github/workflows/agents-schema-dbt.yml@v0.0.6
    with:
      dbt-project-dir: dbt_project
    secrets: inherit

  agents-schema-looker:
    uses: fivetran/agents_schema/.github/workflows/agents-schema-looker.yml@v0.0.6
    with:
      lookml-dir: lookml
    secrets: inherit

  agents-schema-osi:
    uses: fivetran/agents_schema/.github/workflows/agents-schema-osi.yml@v0.0.6
    with:
      osi-dir: osi
    secrets: inherit

バージョン pin

リポジトリ全体(reusable workflows・actions・CLI・examples・README・spec)が 1 つの release tag で versioning されます。現行タグは v0.0.6 です。アップグレードは uses: 行のタグを変更するだけです。

CLI 直接呼び出し

GitHub Actions を使わずローカルや任意の CI で直接実行する場合は agents-schema CLI を使います。PyPI に agents-schema として公開されています。

pip install agents-schema
# または
uv pip install agents-schema

インストール後のエントリポイントは agents-schema(agents_schema.cli:main)です。補助コマンド agents-schema-dbt-adapter-package(agents_schema.cli:dbt_adapter_package_main)も提供されます。

export WAREHOUSE_CREDENTIALS="$(cat credentials.yaml)"

agents-schema dbt --project-dir dbt_project
agents-schema looker --lookml-dir lookml
agents-schema osi --osi-dir osi

CLI は環境変数 WAREHOUSE_CREDENTIALS を読み込みます。

利用方法

エージェントは AGENTS.* テーブルを SQL で読んで、ビジネスデータをクエリする前に文脈を得ます。

AGENTS.ROOT 起点の discovery

まずどの provider がメタデータを書き込んでいるかを確認します。存在する provider のテーブルのみを参照します。

SELECT provider, key, content
FROM AGENTS.ROOT
ORDER BY provider, key;

metric 探索

OSI の metric は AGENTS.OSI_METRIC、LookML の measure は AGENTS.LOOKML_MEASURE を検索し、DESCRIPTION / AI_CONTEXT と計算式(OSI は EXPRESSION、LookML は SQL)を読み取ります。

SELECT name, description, ai_context, expression
FROM AGENTS.OSI_METRIC
WHERE LOWER(NAME||' '||COALESCE(DESCRIPTION,'')||' '||COALESCE(AI_CONTEXT,''))
      LIKE '%mrr%';
SELECT view_name, measure_name, type, sql, description, ai_context
FROM AGENTS.LOOKML_MEASURE
WHERE LOWER(MEASURE_NAME||' '||COALESCE(DESCRIPTION,'')||' '||COALESCE(AI_CONTEXT,''))
      LIKE '%revenue%';

physical table 解決

metric の formula を確認したら、参照する物理テーブルとクエリルールを取得します。AI_CONTEXT の指示に厳密に従います。

SELECT name, source_table, primary_key, description, ai_context
FROM AGENTS.OSI_DATASET
WHERE name = '<dataset_name>';
SELECT name, sql_table_name, description, ai_context
FROM AGENTS.LOOKML_VIEW
WHERE name = '<view_name>';

再帰 lineage(dbt dependency)

あるソースに直接・間接的に依存する全モデルは AGENTS.DBT_DEPENDENCY を WITH RECURSIVE で辿って取得します。次は SPEC.md の正準例です。

WITH RECURSIVE lineage AS (
  SELECT downstream_id AS node_id
  FROM AGENTS.DBT_DEPENDENCY
  WHERE upstream_id = 'source.my_project.raw.account'

  UNION ALL

  SELECT d.downstream_id
  FROM AGENTS.DBT_DEPENDENCY d
  JOIN lineage l ON d.upstream_id = l.node_id
)
SELECT DISTINCT m.name, m.schema_name, m.description
FROM lineage
JOIN AGENTS.DBT_MODEL m ON m.unique_id = lineage.node_id;

cross-source join(LookML ↔ dbt)

LookML view の sql_table_name と dbt model の schema_name / name を heuristic で突き合わせ、BI 向けオブジェクトをモデル化された warehouse テーブルへ対応づけます。sql_table_name は自由記述のため、orientation 用途の発見的クエリです。

SELECT
  v.name AS lookml_view,
  v.sql_table_name,
  m.unique_id AS dbt_model_id,
  m.name AS dbt_model,
  m.schema_name,
  m.description AS dbt_description
FROM AGENTS.LOOKML_VIEW v
LEFT JOIN AGENTS.DBT_MODEL m
  ON LOWER(v.sql_table_name) LIKE '%' || LOWER(m.schema_name) || '.' || LOWER(m.name) || '%';

sql_table_name が derived table(インライン SQL)や ${TABLE} テンプレート、database.schema.table の三段修飾を含む場合は、この LIKE 一致が外れます。一致しない view は LOOKML_VIEW.description / ai_context のテキスト検索で補うか、AGENTS.ROOT のカスタム行に view ↔ model の対応関係を明示して解決します。

analyst skill の導入

agents-schema-analyst skill を使うと、AI エージェントが AGENTS.* を自律的に参照してビジネス質問に答えます。事前に snow connection add で Snowflake 接続を設定します。

# Claude Code
curl -fsSL --create-dirs \
  -o ~/.claude/skills/agents-schema-analyst/SKILL.md \
  https://raw.githubusercontent.com/fivetran/agents_schema/v0.0.6/examples/skills/agents-schema-analyst/SKILL.md
# Codex
curl -fsSL --create-dirs \
  -o ~/.codex/skills/agents-schema-analyst/SKILL.md \
  https://raw.githubusercontent.com/fivetran/agents_schema/v0.0.6/examples/skills/agents-schema-analyst/SKILL.md

呼び出しは Claude Code が /agents-schema-analyst "What is our total MRR this month?"、Codex が $agents-schema-analyst "What is our total MRR this month?" です。

working directory に agents.yml を置くと接続名とスキーマ名をカスタマイズできます。

snow_cli_connection: my_connection
agents_schema_name: AGENTS

snow_cli_connection を省略すると snow connection list のデフォルト接続を、agents_schema_name を省略すると AGENTS を使います。skill は snow sql を通じて read-only(SELECT / SHOW のみ)で動作します。

運用

メタデータのリフレッシュ

ワークフローは push (branches:[main]) と workflow_dispatch の 2 トリガーで動きます。dbt manifest や LookML / OSI ファイルを main に push するたびに自動起動します。secret 更新後やリポジトリ変更を伴わないリフレッシュは、Actions タブの "Run workflow"(workflow_dispatch)で手動実行します。

冪等な再生成

各 source ingestion は自分の table family を CREATE OR REPLACE TABLE で丸ごと置換します。AGENTS.ROOT への書き込みは MERGE(upsert)で行い、自分の provider 行だけを更新して他 provider の行には触れません。

実行ごとの動作:
  source table(DBT_MODEL 等): CREATE OR REPLACE TABLE → 全件置換
  AGENTS.ROOT:                 MERGE ON (provider, key) → 自 provider 行のみ upsert

consumer 側は手編集不可の「generated metadata」として扱う設計です。

状態確認

publish 済み provider は AGENTS.ROOT で確認します。各テーブルの最終更新時刻は Snowflake の INFORMATION_SCHEMA で補完できます。

SELECT provider, key, content FROM AGENTS.ROOT ORDER BY provider, key;
SELECT table_name, last_altered
FROM information_schema.tables
WHERE table_schema = 'AGENTS'
ORDER BY table_name;

バージョン更新

uses: 行のタグを上げるだけでリポジトリ全体(workflows / actions / CLI / examples / spec)が一括更新されます。本記事の調査時点(2026-06-04)の最新タグは v0.0.6 です。

ベストプラクティス

権限分離

SPEC.md「Permissions」に基づく推奨設計です。

  • read: AGENTS.ROOT と全 source table は、分析クエリまたはエージェントクエリを実行するすべての Snowflake principal に SELECT を付与します。
  • write: AGENTS.* への書き込みは、publish するワークフロー / サービスプリンシパルに限定します。専用ユーザー(例: AGENTS_SCHEMA_BOT)と TRANSFORMER ロールを用意し、key-pair 認証を推奨します。

取り込み経路の選択

SPEC.md「Populating the Tables」が示す 4 経路から、自分のインフラに合うものを選びます。GitHub Actions は 1 実装手段にすぎません。

経路 説明
Vendor-run pipeline プロバイダーが自動で warehouse に sync する。
CI/CD job ソースアーティファクト変更時に AGENTS.* をロードする。
Scheduled workflow 定期的にソースからメタデータをリフレッシュする。
Platform engineering job 内部メタデータ・スキル・クエリレシピ・運用コンテキストを管理する。

カスタム provider 拡張

AGENTS.ROOT に独自 provider 行を追加すると、warehouse に任意のコンテキストを置けます。特定テーブルを説明する行は unprefixed table 名に key を合わせます(例: (dbt, model) → AGENTS.DBT_MODEL)。content は LLM consumer 向けに Markdown が自然です。

INSERT INTO AGENTS.ROOT (provider, key, content) VALUES
  ('acme_corp', 'skills/refund_workflow', '# Refund Workflow\nWhen a user asks about refunds, use this procedure...'),
  ('acme_corp', 'costs', '# Query Costs\nUse this before running expensive joins.');

カスタムテーブルを作る場合は (provider, table_name) の命名慣習(例: AGENTS.ACME_ORDERS)に従うと、LLM エージェントが混乱しにくくなります。テーブルのカラム構成に強制はなく、consumer が読める列名と型(自由記述は TEXT、ID やラベルは VARCHAR、JSON は VARIANT)を持てば十分です。最小構成の DDL 例は次のとおりです。

CREATE TABLE IF NOT EXISTS AGENTS.ACME_ORDERS (
  table_name  VARCHAR,
  description TEXT,
  ai_context  TEXT
);

ROOT.key にテーブル名以外の自由キー(例: skills/refund_workflow、costs)を使う場合、それは特定テーブルの文書ではなく自由コンテキストです。consumer は AGENTS.ROOT を全件 SELECT し、provider で絞り込んだうえで content(多くは Markdown)を読んで利用します。テーブル文書化行とは異なり、対応テーブルの存在を前提にしません。

destination の拡張余地

現状の対応 destination は Snowflake のみです("more coming soon")。destinations.py は Destination Protocol(replace_table / upsert_rows / insert_rows / close)を定義し、SnowflakeDestination がその実装です。他ウェアハウスへ拡張する際は、この Protocol を満たすクラスを追加し、open_destination() のディスパッチと SUPPORTED_WAREHOUSE_TYPES を拡張する形になります。TableSchema / Column による論理スキーマ定義は destination 非依存のため再利用できます。

適用境界

  • dbt リポジトリを編集する dbt MCP server は source files / artifacts を直接使うべきです。Agents Schema はその代替ではありません。
  • Semantic Layer の置換でもありません。計算・集計ロジックのランタイム実行は専用システムが担います。
  • information_schema のように warehouse 内で自己完結するメタデータ発見レイヤーとして位置づけます。

consumer 側 skill のガードレール

examples/skills/agents-schema-analyst/SKILL.md に示されるガードレールです。

  • snow sql の SELECT / SHOW のみ を許可します。INSERT・UPDATE・DROP・CREATE は実行しません。
  • SHOW TABLES / GET_DDL による広域スキーマクロールは避け、AGENTS.ROOT を起点に focused SELECT で対象を絞ります。
  • ROOT に出ていない provider のテーブルを推測クエリしません。
  • AI_CONTEXT / DESCRIPTION の指示を厳守し、定義が無ければ推測せず「定義が見つからない」と返します。

トラブルシューティング

src/destinations.py / src/config.py の ConfigError メッセージを根拠とした主要エラーです。

症状 原因 対処
missing required WAREHOUSE_CREDENTIALS secret WAREHOUSE_CREDENTIALS 未設定 リポジトリの Settings → Secrets → Actions に登録する。
WAREHOUSE_CREDENTIALS is not valid JSON or YAML secret 本文が JSON / YAML として不正 改行・インデント・クォートを確認して正しい形式で書き直す。
WAREHOUSE_CREDENTIALS.type must be snowflake type が欠落または別値 type: snowflake を明示する(現状唯一の対応 destination)。
unsupported WAREHOUSE_CREDENTIALS.type '...' type に snowflake 以外を指定 type: snowflake に修正する。
WAREHOUSE_CREDENTIALS missing keys: ... account / user / warehouse / database または認証手段の欠落 不足キーを追加する。
dbt manifest not found <dbt-project-dir>/target/manifest.json が無い manifest を生成して commit するか、managed dbt parse(dbt-profile-name + DBT_PROFILES_YML を両方設定)か dbt-parse-command を使う。
expected a simple Snowflake identifier: ... 識別子に [A-Za-z_][A-Za-z0-9_$]* 以外の文字が混入 命名規則に従ったテーブル名に変更する。
key-pair 認証失敗 private_key_pem の改行崩れ、または passphrase 指定誤り 暗号化キーは passphrase を指定、非暗号化キーは passphrase 行を省く。PEM の改行保持を確認する。

WAREHOUSE_CREDENTIALS の解析順

destinations.py の _parse_warehouse_credentials は JSON → YAML の順で parse を試み、どちらも失敗すると ConfigError を送出します。認証手段は password / private_key_pem / private_key_path のいずれか 1 つが必須で、private_key_passphrase は暗号化キー使用時のみ指定します。

dbt manifest 不在

dbt compile --project-dir dbt_project
# または dbt run / dbt parse で target/manifest.json を生成
git add dbt_project/target/manifest.json
git commit -m "add dbt manifest"
git push origin main

ROOT が空のまま / provider が追加されない

ワークフローが正常終了しても ROOT が空の場合は、write 権限(TRANSFORMER role 等)が AGENTS スキーマに付与されているかを確認します。

SELECT provider, key FROM AGENTS.ROOT ORDER BY provider, key;

SELECT table_name FROM information_schema.tables
WHERE table_schema = 'AGENTS' ORDER BY table_name;

まとめ

Agents Schema は、AI エージェントがウェアハウスデータを正確にクエリするためのメタデータを、ウェアハウス内の標準 AGENTS スキーマに置く OSS 標準です。dbt / LookML / OSI のメタデータを GitHub Actions + CLI で AGENTS.* テーブルへ正規化し、SQL を実行できるあらゆるエージェントが「推測ではなく定義」に基づいてクエリできるようにします。information_schema に近く provider 横断で拡張でき、ai_context 列でエージェント向けの明示的な制約を与えられる点が特徴です。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります!

参考リンク