📊 技術調査 - GitHub 社内データ分析エージェント Qubot

本記事は GitHub Blog "How we built an internal data analytics agent" を起点に、GitHub が社内向けに構築したデータ分析エージェント Qubot の構造・データモデル・構築・利用・運用を技術調査としてまとめたものです。Qubot は GitHub 社内システムであり一般公開されていないため、構築・利用の一部は公式記述に基づく「再現案」として明示します。

概要

Qubot は GitHub が社内向けに構築した Copilot 駆動のデータ分析エージェントです。GitHub 従業員（Hubbers）がデータウェアハウス内の任意のデータモデルに自然言語で質問し、秒単位で回答を得られます。実行環境は GitHub Copilot Cloud Agent（github.com 上）です。

背景課題

大規模データ・アナリティクス組織では、データアクセスの完全なセルフサービス化が長年の課題です。GitHub スケールでは、複数のプロダクトチームに専任アナリストを割り当てることが難しく、各チームがデータ問題を個別に解決する状況が生じていました。

Qubot はこの課題を解決するために設計されました。SQL の知識を持たない従業員でも「どのユーザーコホートが最も高い継続率を示すか」のような探索的質問を自然言語で投げ、即座に回答を得られます。ユーザー側のメンテナンスコストはゼロです。

位置づけ

Qubot はレポートツールでも BI ダッシュボードの代替でもありません。定型レポートの自動生成ではなく、探索的質問への動的な対話を主目的とします。

関連技術・類似アプローチとの比較

ユースケース別推奨

特徴

• コンテキスト層を first-class に: Bronze / Silver / Gold の 3 段階キュレーションで、スキーマ情報・クエリ例・ビジネスルール・メトリック定義を構造化して保持します。ETL パイプラインが追加シグナルと派生メタデータを自動付加します。公式ブログは構造化コンテキストにより Qubot が約 3 倍高速に正解へ到達したと報告しています。
• 分散所有モデル（hub-and-spoke）: テレメトリコンテキストはプロダクトチーム、適合ファクト／ディメンションはデータ・アナリティクスチーム、ビジネスルールはデータセット所有チームがそれぞれ保守します。各チームは自分の知識領域だけを担い、単一ツールに集約します。
• 複数インターフェース: Slack（設定不要・推奨）、VS Code（1 コマンドインストール）、Copilot CLI の 3 経路を提供します。技術習熟度を問わず採用を促進します。
• デフォルト Kusto → 自動 Trino 切替: 最近のイベントデータの探索的質問には Kusto を使い、複雑な結合や履歴分析が必要な場合は自動的に Trino へ切り替えます。ユーザーがエンジンの使い分けを意識する必要はありません。
• eval を PR で回す: テストケース（プロンプト + ground-truth SQL + メタデータ）と自動オーケストレーション（gh agent-task create）で、コンテキスト変更や機能追加を本番反映前に統計的に評価します。回帰を PR 段階で検出します。
• MCP によるランタイムコンテキスト取得: GitHub MCP Server、Trino 用カスタム MCP Server、Kusto 向け Fabric RTI MCP Server をそれぞれ用途別に組み合わせます。

構造

C4 model の 3 段階（システムコンテキスト → コンテナ → コンポーネント）で Qubot の内部アーキテクチャを図解します。

システムコンテキスト図

コンテナ図

コンポーネント図

UI 層

コンテキスト層

クエリエンジン

データ

概念モデル

Qubot のデータを構成するエンティティと、その所有・利用関係を示します。

所有関係の補足を示します。

情報モデル（再現用の推定モデル）

主要エンティティの属性と多重度を示します。公式ブログにここまで詳細なデータモデルの記載はありません。以下は記事記述から再現用に推定したモデルであり、属性だけでなく関連・多重度も推測を含みます。記事に明示されていない属性は「※推測」と注記します。

属性の根拠と注記を示します。

構築方法

Qubot は GitHub 社内システムであり、一般公開されていません。本セクションは公式ブログ記事に基づく「同等の社内データ分析エージェントを再現するための構成手順」です。Qubot 固有で公開されていない実装部分は「記事記述に基づく再現案」と明示します。

コンテキスト層（Bronze / Silver / Gold）の整備

公式ブログは、データウェアハウス内のデータを raw events / conformed facts and dimensions / curated datasets という成熟度に分け、それぞれに対応した context knowledge（federated context layer）を持つと説明しています。本記事ではこの 3 区分を medallion アーキテクチャの Bronze / Silver / Gold に対応づけて整理します。なお、以下の「ETL による昇格パイプライン」としての記述は、公式記述を実装に落とすための再現案です。

整備の考え方を示します（記事記述に基づく再現案）。

1. 各プロダクトチームが Bronze 層にテーブルスキーマとメタデータを登録します。
2. ETL パイプラインが Bronze を読み込み、クエリ例・使用ガイダンス・必須フィルタを付加して Silver 層を生成します。
3. データセット所有チームが Silver をもとにビジネスルールとメトリック定義を記述し、Gold 層として確定します。
4. コンテキストエージェントが各チームからの投入物を取り込み、エージェントが利用しやすい統一フォーマットに正規化します。

[Bronze: raw schema + telemetry metadata]
        ↓ ETL (query examples, usage guidance, required filters)
[Silver: structured facts/dimensions]
        ↓ team-curated business rules + metric definitions
[Gold: canonical context for agent]
        ↓ context agent normalizes & indexes
[MCP Server context retrieval at runtime]

公式ブログは「構造化・キュレーションされたコンテキストが精度を向上させるだけでなく、応答速度を約 3 倍改善した」と述べています。コンテキスト整備がエージェント品質の核心です。

GitHub MCP Server のセットアップ

Qubot のコンテキスト層は GitHub 上のリポジトリに Markdown 等で永続化されます。GitHub MCP Server は、その context リポジトリ（およびリポジトリ・Issue・PR）を読む汎用 MCP として機能します。Qubot 専用のメタデータ API ではなく、「GitHub 上の context リポジトリを読む経路」と捉えてください。リモートモードとローカルモードの 2 種類があります。

前提条件を示します。

• GitHub アカウント（Copilot サブスクリプション付き）
• VS Code 1.101 以上（リモートモード使用時）

リモートモード（推奨）

追加インストール不要です。VS Code の settings.json に以下を追記します。

{
  "mcp": {
    "servers": {
      "github": {
        "type": "http",
        "url": "https://api.githubcopilot.com/mcp/"
      }
    }
  }
}

PAT 認証を使う場合は Authorization ヘッダを追加します。

{
  "mcp": {
    "servers": {
      "github": {
        "type": "http",
        "url": "https://api.githubcopilot.com/mcp/",
        "headers": {
          "Authorization": "Bearer ${input:github_mcp_pat}"
        }
      }
    }
  }
}

ローカルモード（Docker）

リモート MCP が利用できない環境向けです。

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
  ghcr.io/github/github-mcp-server

VS Code の settings.json に以下を追記します。

{
  "mcp": {
    "servers": {
      "github": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
          "ghcr.io/github/github-mcp-server"
        ],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
        }
      }
    }
  }
}

主要な環境変数を示します。

PAT に付与するスコープは用途に応じた最小権限にします。

Trino 用 MCP Server の接続

Qubot は複雑な結合・履歴分析に Trino を使用し、カスタム MCP Server を自前実装しています。再現案として OSS 実装を活用する構成を示します。

前提条件を示します。

• Python 3.10 以上
• uv パッケージマネージャ
• 稼働中の Trino クラスタ

.env ファイルを作成します。

TRINO_HOST=your-trino-host
TRINO_PORT=8080
TRINO_USER=trino
TRINO_CATALOG=your_catalog
TRINO_SCHEMA=your_schema
TRINO_HTTP_SCHEME=http
# TRINO_PASSWORD=  # 認証が必要な場合のみ

VS Code の settings.json に以下を追記します。

{
  "mcp": {
    "servers": {
      "trino": {
        "command": "uv",
        "args": [
          "run", "--with", "mcp[cli]",
          "--with", "trino",
          "--with", "loguru",
          "mcp", "run", "/path/to/src/server.py"
        ],
        "envFile": "/path/to/.env"
      }
    }
  }
}

提供されるツール名は採用する OSS 実装によって異なります（例: カタログ一覧、スキーマ一覧、テーブル定義取得、SQL 実行など）。Qubot 本体の Trino MCP Server は GitHub 社内のカスタム実装であり非公開のため、ツール名は不明です。再現する場合は採用する OSS 実装（txn2/mcp-trino 等）の README で正確なツール名・設定例を確認し、それに合わせてください。

Fabric RTI MCP Server（Kusto 向け）の接続

Qubot は最近のイベントデータの探索に Kusto（Azure Data Explorer / Microsoft Fabric Eventhouse）を使用し、Fabric RTI MCP Server のローカル版をデプロイしています。

前提条件を示します。

• Python 3.10 以上
• uv パッケージマネージャ
• Azure CLI でログイン済み（az login）
• Microsoft Fabric または Azure Data Explorer クラスタへのアクセス権

インストール手順を示します。

pip install microsoft-fabric-rti-mcp
# または uv を使う場合
uvx microsoft-fabric-rti-mcp

VS Code の settings.json に以下を追記します。

{
  "mcp": {
    "servers": {
      "fabric-rti-mcp": {
        "command": "uvx",
        "args": ["microsoft-fabric-rti-mcp"],
        "env": {
          "KUSTO_SERVICE_URI": "https://your-cluster.region.kusto.windows.net",
          "KUSTO_SERVICE_DEFAULT_DB": "YourDatabase"
        }
      }
    }
  }
}

主要な環境変数を示します。

認証には DefaultAzureCredential を使用します。環境変数・Azure CLI・開発ツールの資格情報の順で自動的に試行されるため、az login 済みであれば追加設定は不要です。

利用可能な主要ツール（microsoft/fabric-rti-mcp README に基づく）を示します。

Fabric RTI MCP のツール名・引数は更新が続いています。実際の名称は導入時点の公式リポジトリ（microsoft/fabric-rti-mcp）の README で確認してください。

VS Code プラグイン / Slack / Copilot CLI の導入

VS Code — Copilot 拡張のインストール

1. VS Code の拡張機能パネルを開きます。
2. 「GitHub Copilot」と「GitHub Copilot Chat」を検索してインストールします。
3. GitHub アカウントでサインインします（Copilot サブスクリプションが必要）。
4. Agent モードを有効にすると、上記で設定した MCP サーバーが自動的に読み込まれます。

Slack — GitHub App の導入

公式ブログでは Qubot は専用の「Qubot Slack channel」として提供され、設定不要で使える推奨経路です。以下は同等の体験を再現する案として、GitHub Copilot 公式の Slack 連携（cloud agent の Slack 統合）を使う手順です。

1. Slack ワークスペースに「GitHub App for Slack」をインストールします。
2. Slack で GitHub App との DM を開くか、任意チャンネルで @GitHub Copilot をメンションします。
3. 初回アクセス時に GitHub アカウントの連携と、PR 作成先のデフォルトリポジトリを設定します。
4. 以降は DM またはチャンネルスレッドで自然言語の質問を送ると、Copilot エージェントが応答します。

対象リポジトリへの write アクセスが必要です。Enterprise では管理者による GitHub App の設定が必要です。

Copilot CLI のインストール

# npm（公式パッケージ）
npm install -g @github/copilot

認証手順を示します。

copilot
# 起動後に /login を入力して GitHub 認証

利用方法

必須パラメータを示します。

Slack スレッドでの自然言語質問

Slack は設定不要で使い始められる推奨インターフェースです。

どのユーザーコホートが最も高い継続率を示していますか？

先月の機能 X の利用数を四半期前と比較してください。

エージェントの回答に対してスレッド内で追加質問を送ると、前の文脈を引き継いで回答します。

[スレッド内]
> 上記のクエリを地域別に分解してください。

回答は Slack スレッドに直接表示されます。詳細なレポートは Markdown 形式の PR として保存されるため、後から参照・共有できます。

VS Code でのコマンド実行

Copilot Chat の Agent モードで MCP サーバー経由のクエリを実行します。

1. コマンドパレット（Ctrl+Shift+P / Cmd+Shift+P）を開きます。
2. 「Copilot Chat」を起動し、Agent モードに切り替えます。
3. チャットパネルに質問を入力します。

過去 7 日間のアクティブユーザー数をコホート別に集計してください

Copilot CLI 経由での実行

# CLI を起動
copilot

# ログイン（未認証の場合）
/login

# データ分析タスクを実行
先週の主要メトリクスを取得してください

gh agent-task create でのオフライン eval 実行

Qubot の評価フレームワークでは、gh agent-task create コマンドを使って PR マージ前にエージェントの品質を測定します。

gh agent-task は 2025-09 に GitHub CLI から Copilot coding agent セッションを起動・追跡する機能として追加されました。利用には Copilot coding agent が有効な GitHub Copilot プランが必要です。対応プラン・GA 状況は公式 Changelog および GitHub Docs で確認してください。view はタスク ID（PR 番号またはタスク UUID）を受け付けます。

基本コマンドを示します。

# 新しいエージェントタスクを作成（eval スクリプトを指示として渡す）
gh agent-task create "run evaluation suite against PR #123 using test cases in ./eval/cases.json"

# タスク一覧を表示
gh agent-task list

# タスクの詳細・ログを確認（PR 番号またはタスク UUID を指定）
gh agent-task view 1234

テストケースのスキーマ例を示します（再現案）。

{
  "test_case_id": "cohort_retention_001",
  "prompt": "どのユーザーコホートが最も高い継続率を示しますか？",
  "ground_truth_sql": "SELECT cohort, retention_rate FROM gold.user_retention WHERE deleted = 0",
  "domain": "growth",
  "difficulty": "medium"
}

eval ワークフローを示します（記事記述に基づく再現案）。

# 1. テストケース（プロンプト + ground-truth SQL）を用意
ls ./eval/cases/
# → domain_cohort_analysis.json
# → difficulty_hard_join.json

# 2. eval スクリプトを agent-task 経由で並列実行
for case in ./eval/cases/*.json; do
  gh agent-task create "evaluate qubot with test case: $(cat $case)"
done

# 3. 全タスクの完了を確認
gh agent-task list

# 4. 各エージェントが保存した結果 JSON を収集してメトリクスを集計
#    （結果はエージェントがリポジトリ/PR に JSON として書き出す前提。
#     ターミナルから取得する場合は `gh agent-task view <id> --json` 等で形式を確認する）
jq -s '{completion_rate: ([.[] | select(.status=="completed")] | length) / (length)}' results/*.json

eval のフロー概要を示します。

[PR 作成]
    ↓
[gh agent-task create でテストケースを N 並列実行]
    ↓
[完了をポーリング]
    ↓
[JSON 結果を収集 → 統計集計スクリプトで completion rate / accuracy / duration を算出]
    ↓
[メトリクスを PR に反映 → レビュー・マージ判断]

新しいコンテキストはコンテキスト層への PR として追加し、この eval フローで品質を確認してからマージします。eval 結果は JSON で保存し、設定間の比較に使います。

運用

コンテキスト層の保守責任

Qubot のコンテキスト層は 3 層に分かれ、各層の保守責任者が明確に分離されています。

この分散型オーナーシップにより、データ・アナリティクスチームへの問い合わせ集中を防ぎます。各チームが自身の知識ドメインを直接管理し、コンテキストエージェントが標準テンプレートまたはリポジトリ参照経由で取り込みを自動化します。

ETL によるコンテキスト強化

ETL パイプラインが継続的にコンテキスト層を強化します。

• 追加シグナルの付加: クエリログ・アクセスパターンなどの利用実績から派生メタデータを生成します。
• 正規化: コンテキストエージェントが各チームの投稿内容を統一フォーマットに変換します。
• スケジュール更新: スキーマ変更や新規データモデル追加のたびに Bronze 層を更新し、下流の Silver・Gold に変更を伝播します。

eval を PR ゲートとして回す CI 運用

コンテキスト層の変更はすべて PR 経由で eval を通過してからマージします。

[PR 作成]
  ↓
[gh agent-task create でジョブ起動]
  ↓
[並列トライアル実行]
  ↓
[完了ポーリング]
  ↓
[JSON 結果ファイル保存]
  ↓
[統計集約・メトリクス算出]
  ↓
[PR レビュー・マージ判定]

eval の構成要素を示します。

コンテキスト層の変更が既存クエリの精度を下げていないかをシップ前に検出します。

メトリクス監視

completion rate が基準値（例: 0.90）未満、または前回 PR より精度が低下した場合にマージをブロックする運用が考えられます。閾値はドメイン・難度別に分けて設定すると安定します（PR ゲートの合否例・再現案）。

ベストプラクティス

1. コンテキストを first-class 成果物として扱う

コンテキスト資産（Silver 層のクエリ例・使用ガイダンス・必須フィルタ）を、データモデリングの副産物ではなく主要な配信物として設計します。公式ブログは、これまで事後的だったアナリティクスエンジニアリングのコンテキスト成果物を first-class citizen（第一級の成果物）としてデータモデリングに組み込むべきだと述べています。データモデル変更時は必ずコンテキストも同時に更新するプロセスを組み込みます。

2. 必須フィルタと使用ガイダンスを Silver に集約する

Bronze のスキーマだけでは LLM が適切なフィルタ条件を推論できません。Silver 層に以下を明示的に記載します。

• WHERE deleted = 0 等の必須フィルタ条件
• ファクトテーブルとディメンションテーブルの推奨結合パターン
• メトリックの計算方法（例: active_users の定義）

3. デフォルトエンジン選択をユーザーから隠蔽する

クエリエンジンの使い分けをユーザーに強制しません。Qubot の設計では Kusto をデフォルトとし、複雑な結合や履歴分析が必要と判断した場合に自動で Trino へ切り替えます。ユーザーはエンジンを意識せず質問できます。

4. ゼロ設定インターフェースを採用の入口にする

Slack インターフェースは設定不要で使い始められます。技術知識が高いユーザーでも、最初の採用障壁を下げるためにゼロ設定オプションを提供します。VS Code プラグインや Copilot CLI は、より高度な利用者向けの追加選択肢として位置づけます。

5. 分散知識を hub-and-spoke で集約する

各チームが持つ独自の定義・ルールを個別ツールに閉じ込めず、Qubot という単一ハブに集約します。各チームは自身のドメイン知識を Silver・Gold 層へ投稿し、全社がそれを参照します。これによりデータ・アナリティクスチームへの問い合わせ集中が解消されます。

6. 回答を PR として保存し監査性と再現性を確保する

Slack で得た回答を markdown レポートとして PR に自動保存します。これにより以下を実現します。

• 過去の分析結果を再参照・再利用できます。
• 誤った回答を発見した場合に ground-truth として eval セットへ登録できます。
• 保存時にコンテキスト・モデルのバージョンを併記すれば、どの条件で生成した回答かを追跡できます（再現案）。

トラブルシューティング

text-to-SQL / データ分析エージェントで頻出する失敗を症状・原因・対処の順に示します。

コンテキスト陳腐化による誤答は、SQL 文法エラーとは異なり「技術的に正しいが意味的に間違い」な結果を返します。通常のデータ品質監視では検出できないため、eval による定期的な精度計測が有効な検出手段です（一般的なベストプラクティス）。

まとめ

GitHub の社内データ分析エージェント Qubot は、エージェントの精度をモデルやプロンプトではなく、Bronze / Silver / Gold の 3 段階で各チームが分散保守する「コンテキスト層」と、gh agent-task による PR ゲート型のオフライン eval に置いています。コンテキストを first-class 成果物として設計し、MCP でランタイム取得・Kusto/Trino を自動使い分けする構造は、社内 RAG・データ分析エージェントを本番運用する組織にとって再利用価値の高い設計パターンです。

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

参考リンク

• 公式ドキュメント
  • How we built an internal data analytics agent - GitHub Blog
  • About GitHub Copilot cloud agent - GitHub Docs
  • Integrate cloud agent with Slack - GitHub Docs
  • Install Copilot CLI - GitHub Docs
  • Copilot CLI overview - GitHub Docs
  • Fabric RTI MCP overview - Microsoft Learn
  • Integrate MCP servers with Azure Data Explorer - Microsoft Learn
  • Conformed Dimension - Kimball Group
• GitHub
  • github/github-mcp-server
  • microsoft/fabric-rti-mcp
  • What is MCP - GitHub Resources
  • microsoft-fabric-rti-mcp - PyPI
• 記事
  • Kick off and track Copilot coding agent sessions from the GitHub CLI - GitHub Changelog
  • Model Context Protocol Specification
  • Trino MCP server (imti.co)
  • Medallion Architecture: Bronze, Silver and Gold Layers - dataforest.ai
  • Why text-to-SQL fails - omni.co
  • The six failures of text-to-SQL and how to fix them with agents - Google Cloud
  • Context drift detection - atlan.com
  • Text-to-SQL evaluation techniques - Ragas docs