# 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 にも重ねて入れています。