LangBot/plugins/misc/AgenticRAG/readme/README_ja_JP.md

AgenticRAG

AgenticRAG は、現在の pipeline に設定された知識ベースを Agent から呼び出せるツールとして公開し、利用可能な KB の確認と必要な情報の検索を可能にします。

役割

• query_knowledge という 1 つのツールを提供します
• 2 つのアクションをサポートします
  • list: 現在の pipeline で利用可能な知識ベースを一覧表示
  • query: 1 つまたは複数の知識ベースから関連ドキュメントを検索
• 結果を JSON で返すため、Agent がそのまま後続の推論に利用できます

全体設計

AgenticRAG は新しい RAG エンジンではなく、「いつ検索するか」を制御するためのプラグインです。

変えているのは検索アルゴリズムそのものではなく、検索のタイミングを誰が決めるか です。

• runner が毎回自動で検索するのではなく
• モデルが今このターンで検索が必要かを判断し
• 利用可能な KB を確認し
• 1 つまたは複数の KB を明示的に選んで検索する

この設計は、naive RAG の「毎回先に検索する」方式が持つノイズ、文脈浪費、不必要な断片注入を避けるためのものです。

実装の仕組み

このプラグインは新しい RAG バックエンドを実装するものではありません。LangBot にある、query_id 単位でスコープされた知識検索 API をツールとして薄くラップしています。

• list_pipeline_knowledge_bases()：現在の query がアクセス可能な知識ベースを列挙
• retrieve_knowledge()：1 つまたは複数の KB から検索し、統合された top-k 件の結果を取得

ツール実行時には runtime が現在の query_id を自動で注入します。QueryBasedAPIProxy がこの文脈を保持するため、ツール側で明示的に渡す必要があるのは次の項目です。

• kb_id または kb_ids
• query_text
• top_k

基盤の runtime 自体は metadata filter を扱えますが、このプラグインでは現時点で Agent フローのツール呼び出しに raw な metadata filter を公開していません。知識エンジンやベクターバックエンドごとに metadata の項目名、型、値の形式、filter の意味が揃っておらず、Agent 側にその schema を安定して渡す仕組みがまだないためです。

今後、知識ベースごとに利用可能な filter 項目や演算子を統一的に記述できる仕組みが整えば、metadata filter を Agent に開放することは可能です。

どのように動くか

AgenticRAG の 1 回の処理は、おおむね 4 段階です。

1. naive RAG を無効化する

PromptPreProcessing の段階で、plugin は現在の LLM が tool call を使えるかを先に確認します。

• tool call を使える場合は runner の _knowledge_base_uuids をクリアし、既定の naive RAG 前処理を止めます
• tool call を使えない場合は naive RAG を残し、KB 検索自体が失われないようにします

2. 検索方針を system prompt に注入する

同時に、追加の system prompt を注入して、モデルに次の点を明示します。

• 設定済み KB がその領域の主要な情報源であること
• 自動検索のフォールバックは存在しないこと
• 事実、規則、手順、製品仕様、設定などの質問では query_knowledge を優先すべきこと

これは、tool description だけでは検索行動を十分に安定化できないことが多いためです。

3. モデルに KB 一覧確認と検索をさせる

その後、モデルは次の 2 段階で動けます。

• action="list" で利用可能な KB を確認する
• action="query" で 1 つまたは複数の KB を検索する

単一 KB の場合は kb_id、複数 KB を並列検索する場合のみ kb_ids を使います。

4. 結果を構造化 JSON で返す

ツールは結果をマージし、knowledge_base_id などを補った JSON を返します。これによりモデルはそのまま推論を継続できます。

セキュリティ

このツールは、現在の pipeline に設定された知識ベースだけを対象にします。

• LangBot runtime 側でも、kb_id が現在の pipeline に属しているか再検証します

そのため、prompt injection だけで pipeline 外の任意の KB を検索することは想定されていません。

使い方

1. このプラグインをインストールして有効化します。
2. 現在の pipeline の local agent 設定で、1 つ以上の知識ベースを関連付けます。
3. Agent に query_knowledge を呼ばせます。
   • まず action="list" で利用可能な KB を確認します
   • 次に action="query" で、単一 KB なら kb_id、複数 KB を並列検索するなら kb_ids を渡します
   • あわせて query_text と、必要に応じて統合結果数を表す top_k を渡します

なぜこの設計なのか

このプラグインの目的は明確です。

• LangBot の既存 KB / 検索基盤をそのまま活かす
• 不要な常時検索をやめる
• 検索判断を agent loop に戻す
• それでもアクセス範囲は現在の pipeline に厳密に限定する

naive RAG と比べると、この設計には次の利点があります。

• KB が不要なターンでは文脈がよりクリーンになる
• モデルがどの KB を使うかを明示的に選べる
• 「まず list、次に query、必要なら再 query」という段階的検索ができる

一方で、モデルがまったくツールを呼ばなければ KB 内容は一切入ってきません。

そのため AgenticRAG は「モデルが自然に検索してくれるはず」とは考えず、system prompt と tool prompt の両方で検索優先の方針を明示しています。

そのため現在の実装では、tool call 非対応モデルに対して naive RAG を無効化しない保護も入れています。これがないと、AgenticRAG を有効にしただけで KB 検索が完全に失われるためです。

パラメータ

action="query" のときに使えるパラメータは以下です。

• kb_id：単一 KB 検索時の対象知識ベース UUID
• kb_ids：複数 KB を並列検索するための UUID 配列。複数 KB を同時に検索するときだけ使います
• query_text：検索クエリ
• top_k：任意。返す件数。正の整数である必要があり、既定値は 5。統合後の結果数に適用されます

複数 KB の並列検索で一部だけ失敗した場合、ツールは results と failed_kbs を持つ JSON オブジェクトを返し、Agent が部分的な成功結果を継続利用できるようにします。

典型的な流れ

1. Agent が利用可能な知識ベースを一覧表示します。
2. 名前と説明を見て、適切な 1 つまたは少数の KB を選びます。
3. 明確な検索クエリで検索します。
4. 返却された断片を使って回答または次の推論を行います。

Prompt 設計の意図

現在の prompt 設計がモデルに伝えたいのは主に 2 点です。

• 知識ベースはその対話領域における権威ある情報源であること
• AgenticRAG 有効時には自動検索のフォールバックがないこと

この 2 点を明示しないと、LLM は自分の事前学習知識を過信して検索頻度を下げがちです。

そのため現在の実装では、検索方針を tool prompt だけでなく、system prompt にも重ねて入れています。