社内知識をAIに渡す基盤、読める範囲はプロジェクト単位で決まる

CyberAgent Developers Blogに載った、インターン生の広瀬エイトルさんの体験記です。AIエージェントに社内の知識を渡す基盤づくりを扱っています。

この話は、AIエージェントに社内の知識を渡す仕組みを作るエンジニアや、業務データをAIで扱うチームに関係します。 一般の利用者が使うサービスの変更ではありません。

記事でいう「知識」は、「特定の状況で使うべき解釈や判断を、再利用できる形で言語化したもの」です。 たとえば「セール期間の売上の伸びは、前年の同じ時期の伸びを差し引いて評価する」といった書き方になります。 事実とは分けて扱います。

これまでは、担当者がSlackなどで共有した知見を、エンジニアがプロンプト（AIへの指示文）に手で反映していました。 業務用語や指標の定義を反映し続けることと、更新のたびにエンジニアが作業する負担を減らすことが課題でした。

そこで、基盤の要件を4つに置きました。

• エンジニアでなくても知識を書けること
• 書き方がそろっていること
• 顧客企業ごとに知識を分けられること
• エージェントが検索して引けること

知識の形式には、Googleが公開しているOpen Knowledge Format（OKF）を選びました。 YAML（設定ファイルに使う書き方）の情報を先頭に付けたMarkdownファイル1つが、知識1件になります。 2026年7月公開のv0.2では、次の項目が加わりました。

• 出典
• 誰がいつ確認したか
• 有効期限
• 下書きか確定か

選んだ理由は2つです。 1つ目は、Googleが開発している形式で、保存先のKnowledge Catalogも同じGoogle Cloudの製品だからです。 2つ目は、知識どうしの関係を表せることです。知識1件ごとに指標や用語といった種類を持たせ、本文からほかの知識へリンクを張れます。

Knowledge Catalogは、2026年4月にDataplex Universal Catalogから改名されたサービスです。 BigQueryのテーブル情報と同じ場所に置けるため、エージェントは「どのテーブルを使うか」と「そのテーブルをどう解釈するか」を同じAPIで引けます。 サイソクも11月2日に、Knowledge Catalogの自己学習機能がプレビュー版として登場したことを報じています（Knowledge Catalogの自己学習機能の記事）。

一方で、Knowledge Catalogのコンソール（管理画面）ではカスタムエントリを作れません。 作成はAPIかCLI（コマンドで操作する方法）で行う必要があります。 入れ子の項目も画面から編集できません。 そこで、ブラウザからOKFを編集できる個人開発のOSS「ochakai」を、編集の入口として一時的に使いました。 MITライセンスで、変更履歴が残り、知識全体をOKFのファイルとして書き出せます。 検索やMCP（AIと外部ツールをつなぐ仕組み）には頼らない形にしたそうです。

読める相手は「entry group」ではなくプロジェクトで決まる

一番時間をかけたのが権限の設計でした。 知識1件は1つのentryになり、entryは「entry group」というまとまりに入ります。 entry groupごとに権限を分ければ、知識も分けられそうに見えます。

しかし、カスタムエントリが検索で見えるかどうかは、プロジェクトに付与するroles/dataplex.catalogViewerで決まります。 このロールを持つ相手には、同じプロジェクトにあるすべてのentry groupの知識が見えてしまいます。

根拠は3つあります。

• 1つ目は、entry単位ではIAMを設定できないことです。entryは所属するentry groupの権限を引き継ぎます。
• 2つ目は、カスタムエントリの検索結果がプロジェクトのロールで絞られることです。BigQueryのテーブルが元のテーブルの権限で絞られるのとは異なります。
• 3つ目は、検索範囲を省くと、呼び出したプロジェクトが属する組織全体が対象になることです。

そのため、読める相手を分けたい知識は別のGCPプロジェクトに置きます。 検索範囲は、ワーカー（処理を担当する仕組み）側で固定します。

複数の相手で共有したい知識は、読ませたい相手がcatalogViewerを持つプロジェクトに置きます。 その場合、そのプロジェクトを読める相手全員から読まれる前提になります。

エージェントのサービスアカウント（プログラムが使うアカウント）には、次の2つの権限が必要です。

• 知識を置いた各プロジェクトのcatalogViewer
• 検索対象のデータセットのroles/bigquery.metadataViewer

後者は見落としやすいとされています。足りなくてもエラーは出ず、検索結果が0件になるだけだからです。

検索クエリの条件も境界にはなりません。 インターン生が、クエリにORを足すと条件の外まで結果が広がることを実際に確認しました。 境界はIAMと検索範囲の固定で作る必要があります。

エージェントに渡す検索ツールは、knowledge_retrieval（知識検索用）の1本だけにしました。 モデルが指定できるのは検索語と件数だけで、どこを検索するかは固定しています。 scopeを省くと組織全体が対象になるので、ここを任せると分離が崩れるからです。

日本語の社内用語では検索が0件になることがあった

作ってみて一番困ったのが、Knowledge Catalogの検索性能でした。 検索には、意味を解釈するsemantic検索と、キーワード検索の2つがあります。

キーワード検索は、知識を書いた人と同じ語を使えば当たります。 しかし、表記の揺れや動詞の活用が違うだけで0件になりました。 自然な言い回しで質問しても同じでした。

semantic検索は、表記の揺れや活用の違いに強くなりました。 その代わり、該当する知識がない質問でも何かを返し、関係のないものが上位に来ることがありました。

今回の環境で自動生成されたテーブルの説明は英語でした。 そのため、英語では見つかるテーブルが、同じ意味の日本語では見つかりませんでした。 ドキュメントにも、英語以外の言語での挙動の記載は見当たらなかったとされています。

検索は該当するものをすべて返すとは保証されず、同じクエリでも結果が変わりうると明記されています。 記事は、保存先としてのKnowledge Catalogには満足しているとしつつ、今の検索性能では、エージェントが必要な知識を安定して引くのは難しいと書いています。 そのため、知識検索用のサービスを自前で用意する必要があるという見方です。

日本でのKnowledge CatalogやOKFの採用事例も、調べた範囲では公にはあまり見つからなかったそうです。

学びは3つです。

• 保存先より前に形式を決めたことで、ツールを後から替えやすくできたこと
• 読める相手はプロジェクトの境界で分け、検索範囲も固定すること
• 知識の保存先と検索は分けて考え、検索には専用の仕組みが要ること