ツールシステムと RAG ナレッジベース

本ドキュメントでは、AgentCraftLab のツールシステム、RAG（Retrieval-Augmented Generation）ナレッジベース機能、およびスキルシステムについて説明します。

Part 1: ツールシステム

1.1 エージェントの4層ツールソース

各エージェントノードは4つのソースからのツールを同時に使用でき、実行時に AgentContextBuilder.ResolveToolsAsync() によって統合されます：

レイヤー	ソース	説明
1	Tool Catalog（ビルトインツール）	プラットフォームがデフォルトで提供する検索、ファイル、メールなどのツール
2	MCP Servers	Model Context Protocol を通じて外部ツールサーバーに接続
3	A2A Agents	Agent-to-Agent プロトコルを通じてリモートエージェントを呼び出し
4	HTTP APIs	カスタム HTTP エンドポイントを決定論的なツール呼び出しとして使用

さらに、OCR と JS サンドボックススクリプトエンジンは拡張モジュールとして接続され、有効化するとツールリストに統合されます。

Workflow Studio では、エージェントノードの設定パネルでビルトインツールの選択、MCP Server URL、A2A Agent URL、HTTP API エンドポイントの入力が可能です。

1.2 ビルトインツール（Tool Catalog）

ビルトインツールはカテゴリ別に以下のとおりです：

検索系（Search）

ツール ID	名前	説明	必要な認証情報
`azure_web_search`	Azure Web Search	Azure OpenAI Responses API を通じてリアルタイムの Web 情報を検索	azure-openai
`tavily_search`	Tavily Search	AI 専用検索エンジン（無料 1000回/月）	tavily
`tavily_extract`	Tavily Extract	URL からクリーンな Web コンテンツを抽出し、広告を自動除去	tavily
`brave_search`	Brave Search	プライバシー重視の検索エンジン（無料 2000回/月）	brave
`serper_search`	Serper (Google)	Google Search API。search/news/images/places に対応	serper
`web_search`	Web Search (Free)	DuckDuckGo + Wikipedia。無料、API Key 不要	--
`wikipedia`	Wikipedia	Wikipedia 百科事典検索（中国語/英語を自動検出）	--

ユーティリティ系（Utility）

ツール ID	名前	説明
`get_datetime`	Date & Time	現在の日付、時刻、タイムゾーンを取得
`calculator`	Calculator	数式を計算
`uuid_generator`	UUID Generator	ユニークな UUID / GUID を生成
`send_email`	Send Email	SMTP を通じてメールを送信（smtp 認証情報が必要）

Web 系（Web）

ツール ID	名前	説明
`url_fetch`	URL Fetch	指定された Web ページのテキストコンテンツサマリーを取得

データ系（Data）

ツール ID	名前	説明
`json_parser`	JSON Parser	JSON 文字列を解析し、指定フィールドを抽出
`csv_log_analyzer`	CSV Log Analyzer	ディレクトリ内の CSV ファイルを読み取り、AI 分析用に統合
`zip_extractor`	ZIP Extractor	ZIP ファイルを一時ディレクトリに解凍
`write_file`	Write File	テキストをファイルに書き込み（csv/json/txt/md/xml/yaml/html など）
`write_csv`	Write CSV	JSON 配列データを CSV ファイルに書き込み
`list_directory`	List Directory	ディレクトリ構造を一覧表示（tree 形式）
`read_file`	Read File	ファイルの指定行範囲を読み取り（行番号付き）
`search_code`	Search Code	コードベース内で正規表現パターンに一致するコードを検索

認証情報が必要なツールは、/settings ページの Credentials セクションで対応する API Key を事前に設定してください。認証情報が未設定の場合、ツールはリストに表示されますが、実行時にエラーメッセージが返されます。

1.3 MCP Server 統合

MCP（Model Context Protocol）により、エージェントは標準プロトコルを通じて外部ツールサーバーに接続できます。

設定方法：

Workflow Studio でエージェントノードを選択します
ノード設定パネルで「MCP Servers」セクションを見つけます
MCP Server の URL を入力します（例：http://localhost:3001/mcp）
複数の MCP Server URL を追加できます

接続フロー：

実行時、システムは各 MCP Server URL に discovery リクエストを送信し、そのサーバーが提供するツールリストを取得して、エージェントの利用可能なツールに自動的に統合します。接続に失敗した場合、システムは警告を記録しますが実行は中断しません。

テスト用 MCP Server：

bash

npx -y @modelcontextprotocol/server-everything streamableHttp
# 起動後、http://localhost:3001/mcp で接続できます

1.4 A2A Agent 統合

A2A（Agent-to-Agent）プロトコルにより、ローカルエージェントがリモートエージェントをツールとして呼び出せます。

設定方法：

エージェントノードの設定パネルで「A2A Agents」セクションを見つけます
リモートエージェントの URL を入力します
形式を選択します：auto（自動検出）、google（Google A2A 形式）、microsoft（Microsoft 形式）

接続フロー：

システムはまず URL に discovery リクエストを送信して Agent Card（名前、説明、機能などの情報を含む）を取得し、そのリモートエージェントを AITool としてラップして、ローカルエージェントから呼び出せるようにします。

また、独立した a2a-agent ノードタイプを使用して、ワークフロー内でリモートエージェントノードとして直接参加させることもできます。

1.5 HTTP API ツール

HTTP API ツールにより、エージェントはカスタム HTTP エンドポイントを呼び出せます。内部システムやサードパーティの REST API への接続に適しています。

設定方法：

エージェントノードの設定で HTTP API エンドポイント情報を追加すると、システムがエージェントから呼び出し可能なツールとしてラップします。

また、独立した http-request ノードタイプがあり、ワークフロー内で LLM の判断を経ない決定論的な HTTP 呼び出しステップとして使用できます。

1.6 OCR ツール

AgentCraftLab は Tesseract OCR エンジンを統合しており、拡張モジュール（AgentCraftLab.Ocr）として提供しています。

有効化条件： システムが tessdata ディレクトリの存在を検出すると自動的に有効化されます。

対応言語： 繁体字中国語、簡体字中国語、英語、日本語、韓国語。

有効化後、OCR ツールはエージェントのツールリストに自動的に統合され、エージェントが画像内のテキストを認識するために使用できます。

1.7 JS サンドボックススクリプト

Code ノードは script モードをサポートしており、Jint エンジンを使用して JS サンドボックス内で JavaScript スクリプトを実行します。

用途： 決定論的なデータ変換。LLM トークンを消費しません。例：JSON フィールドの再構成、フォーマット、フィルタリングなど。

主な機能：

サンドボックスで隔離され、メインシステムに影響を与えません
ISandboxApi でサンドボックス内で利用可能な API を拡張できます
AI スクリプト生成をサポート：POST /api/script-generator エンドポイントを通じて、LLM が記述に基づいてサンドボックス互換の JS スクリプトを自動生成します
Test Run をサポート：デプロイ前にスクリプトの出力をテストできます

エンジンインターフェースは IScriptEngine で、DI を通じて Roslyn または Python エンジンに置き換え可能です。

Part 2: RAG とナレッジベース

2.1 RAG の概念説明

RAG（Retrieval-Augmented Generation）は「検索」と「生成」を組み合わせた技術パターンです。実行フローは以下のとおりです：

Ingest（取り込み）： ドキュメントからテキストを抽出 → チャンキング（chunking） → ベクトル化（embedding） → 検索インデックスに書き込み
Search（検索）： ユーザー入力 → ベクトル化 → インデックス内で関連する断片を検索 → Rerank で再順位付け
Augment（拡張）： 検索結果（ソース metadata 付き）を LLM の system message に注入し、コンテキストを提供
Generate（生成）： LLM がコンテキストと質問に基づいて回答を生成

AgentCraftLab の RAG パイプラインでは、RagService が Ingest を担当し、RagChatClient（DelegatingChatClient）が検索と注入を担当します。検索エンジンは独立した AgentCraftLab.Search クラスライブラリによって提供されます。

2.2 ナレッジベース管理

ナレッジベースは RAG の中核であり、永続的に保存して複数回使用するドキュメントコレクションに適しています。/knowledge-bases ページで管理します。

ナレッジベースの作成：

ナレッジベース管理ページに移動します
「ナレッジベースを作成」をクリックします
名前と説明を入力します
インデックスパラメータを設定します（作成後は変更不可）：
- Embedding Model： ベクトル化モデル（text-embedding-3-small / large / ada-002）
- Chunk Strategy： チャンキング戦略
  - 固定サイズ（Fixed Size）： 文字数で分割しオーバーラップを追加。すべてのドキュメントに適用可能
  - 構造認識（Structural）： Markdown/HTML の見出しや段落境界で分割。構造化されたドキュメントに最適
- Chunk Size： チャンクサイズ（文字数、デフォルト 512）
- Chunk Overlap： チャンクのオーバーラップ領域（文字数、デフォルト 50）
作成後、対応する検索インデックスが構築されます（命名規則：{userId}_kb_{id}）

注意： Embedding モデル、チャンキング戦略、Chunk Size、Overlap は作成後に変更できません。変更が必要な場合は、ナレッジベースを削除して再作成してください。

スマートデフォルト：

Chunk Strategy を切り替えると、システムが対応する Chunk Size と Overlap の値を自動的に推薦します：

固定サイズ（Fixed Size） → 512 / 50
構造認識（Structural） → 1024 / 100

ファイルのアップロード：

作成済みのナレッジベースを選択します
ファイルをアップロードします（PDF / DOCX / PPTX / HTML / TXT / MD / CSV / JSON などの形式に対応）
システムが SSE（Server-Sent Events）ストリーミングで処理進捗をリアルタイムに報告します：
- Extracting text...（テキスト抽出中、metadata を自動取得：タイトル、著者、ページ数など）
- Chunking text...（設定された戦略に従ってチャンキング中）
- Generating embeddings...（ベクトル化中、次元数はモデルにより動的に決定）
- Ingested X chunks（完了）

URL 取り込み：

ナレッジベース詳細パネルに URL 入力フィールドがあり、Web コンテンツを直接ナレッジベースに取り込めます：

Web ページの URL を入力します
システムが自動的にページを取得 → テキストを抽出（HtmlExtractor を使用） → KB 設定に従ってチャンキング → embedding → インデックス作成
SSE ストリーミングで進捗をリアルタイムに報告します
取り込んだコンテンツは {domain}_{path}.html のファイル名でナレッジベースに保存されます

同名ファイル置換：

既存ファイルと同じ名前のファイルをアップロードすると、システムが旧ファイルのチャンクを自動的に削除し、新しいファイルを再 ingest します。手動で旧ファイルを削除してから再アップロードする必要はありません。ファイル名の比較は大文字・小文字を区別しません（case-insensitive）。

アップロード後の Chunk プレビュー：

アップロード完了後、進捗エリアに最初の 3 つのチャンクの内容プレビューが表示され、チャンキング品質が期待どおりかすぐに確認できます。プレビューは 10 秒後に自動的に非表示になります。

ファイル管理：

ナレッジベース詳細パネルにアップロード済みファイルのリスト、チャンク数、作成日時が表示されます
パネルのヘッダーにインデックス設定の概要が表示されます（embedding model / chunk strategy / chunk size）
単一ファイルの削除に対応しています（確認ダイアログ付き）。削除するとそのファイルに対応するすべてのチャンクとベクトルデータも同時にクリアされます

ナレッジベース統計：

詳細パネルのヘッダーにファイルタイプの分布が表示されます（例：PDF: 3 · DOCX: 1 · HTML: 2）。ナレッジベースの内容構成を素早く把握できます。

検索テスト（Retrieval Test）：

ナレッジベース詳細パネルの下部に検索テスト機能が用意されており、本番稼働前に検索品質を検証できます：

質問を入力し、検索をクリックします
呼び出されたチャンクが表示されます（ソースファイル名、セクション番号、関連度スコアを含む）
結果をクリックすると展開して完全なチャンク内容を確認できます
テストパラメータを調整できます（TopK、検索モード、最低スコア閾値）

2.3 ワークフローでナレッジベースを使用する

Workflow Studio で rag ノードをドラッグして配置します
rag ノードの設定で使用するナレッジベースを選択します
rag ノードをエージェントノードに接続します

RAG ノードの設定：

ナレッジベース選択： 作成済みのナレッジベースを選択（Embedding Model は読み取り専用で表示、ナレッジベースにより決定）
検索品質スライダー： 精確 ↔ 網羅の3段階切り替え
- 精確： TopK=3, MinScore=0.01（少量の高品質な結果）
- バランス： TopK=5, MinScore=0.005（デフォルト）
- 網羅： TopK=10, MinScore=0.001（多量の結果、漏れを防止）
詳細検索設定（折りたたみ）： TopK、検索モード（Hybrid/Vector/FullText）、最低スコア閾値
クエリ拡張： デフォルトで有効。クエリバリエーションを自動生成して再現率を向上させます。手動でオフにできます。
ファイルフィルター： ファイル名で検索結果をフィルタリング（例：「.pdf」や「report」）
コンテキスト圧縮： デフォルトで無効。有効にすると、検索結果の合計トークン数が Token 予算を超えた場合に LLM でコンテキストを要約圧縮します
Token 予算： デフォルト 1500。コンテキスト圧縮が有効な場合のみ表示されます

実行時、RagChatClient がナレッジベースインデックス内の関連コンテンツを検索し、Rerank で再順位付けした後、エージェントのコンテキストに注入します（ソース metadata の注釈付き）。

引用元追跡：

実行時、RAG 検索で見つかった引用元は STATE_SNAPSHOT を通じてフロントエンドに送信されます。ConsolePanel に「Sources」タブが追加され、各引用のソースファイル名、セクション番号、関連度スコアが表示されます。クリックすると展開して完全なチャンク内容を確認できます。

2.4 検索モード

検索エンジン（AgentCraftLab.Search）は3つの検索モードをサポートしています：

モード	説明	適用シーン
FullText	SQLite FTS5 全文検索を使用（trigram、CJK 対応）	正確なキーワードマッチング、既知の用語検索
Vector	SIMD 加速の Cosine Similarity ベクトル検索を使用	セマンティック類似度検索、曖昧な概念のマッチング
Hybrid（デフォルト）	FullText + Vector を組み合わせ、RRF（k=60）による融合ランキング	ほとんどのシーンで最適な選択

2.5 Advanced RAG コンポーネント

AgentCraftLab は Advanced RAG アーキテクチャの主要コンポーネントを実装しています：

コンポーネント	説明
Relevance Filtering	`MinScore` 閾値で低スコアの結果をフィルタリングし、無関係なコンテンツが LLM に注入されるのを防止
Reranker	`IReranker` インターフェース。NoOp（デフォルト）/ Cohere API / LLM による再順位付けに対応
Metadata Enrichment	各形式の Extractor がドキュメントの metadata（タイトル/著者/ページ数）を自動抽出し、検索結果に注入
Structural Chunker	Markdown/HTML の見出し + 段落境界で分割し、ドキュメントの構造的な意味を保持
クエリ拡張（Query Expansion）	`QueryExpander` が LLM を使用して 2 つのクエリバリエーションを生成し、並列検索後に結果をマージ・重複排除します。再現率を 30% 以上向上させます。デフォルトで有効、RAG ノード設定でオフにできます。
ファイル名フィルター（File Name Filter）	`FileNameFilter` がファイル名の部分文字列で検索結果をフィルタリングします（大文字・小文字を区別しません）。例：「.pdf」で PDF ファイルのみを検索、「report」でファイル名に「report」を含むファイルのみを検索。
コンテキスト並び替え（Context Reorder）	Lost in the Middle 解法 — Rerank 後にチャンクを再配置し、最高スコアのチャンクを先頭と末尾（LLM の注意力が最も高い位置）に、低スコアのチャンクを中間に配置することで、LLM の重要情報に対する記憶を向上
コンテキスト圧縮（Context Compression）	Token 予算に基づく適応的圧縮 — 検索結果が設定された Token 予算を超えた場合に LLM で要約圧縮を実行。予算内であれば圧縮をスキップし、不要なレイテンシーを回避

Hybrid 検索 + Rerank + MinScore フィルタリングの組み合わせにより、LLM が受け取るコンテキストの関連性と正確性が確保されます。

Part 3: スキルシステム

スキルは「指示 + ツール」の事前定義された組み合わせで、エージェントに特定分野の能力を持たせます。

3.1 ビルトインスキル

システムはデフォルトで5つのカテゴリに分類された複数のビルトインスキルを提供しています：

カテゴリ	例	説明
ドメインナレッジ（Domain Knowledge）	コードレビュー、法的契約レビュー	専門分野のレビューガイドラインと判断基準を注入
メソドロジー（Methodology）	構造化推論	思考フレームワーク（Chain-of-Thought など）を注入
出力形式（Output Format）	--	エージェントの出力構造を規定
ペルソナ設定（Persona）	--	エージェントに特定の役割やキャラクターを設定
ツールプリセット（Tool Preset）	--	特定のツールの組み合わせをデフォルトで選択

各スキルには以下が含まれます：

Instructions： エージェントのシステムプロンプトに注入される指示
Tools： 自動的に適用されるツールリスト（認証情報の利用可否をチェックし、未設定のツールはスキップ）

Workflow Studio では、エージェントノードまたはフロー全体にスキルを適用できます。

3.2 カスタムスキル

/skills ページ（Skill Manager）でカスタムスキルを管理します：

カスタムスキルの作成：

Skill Manager ページに移動します
「スキルを追加」をクリックします
以下を入力します：
- 名前
- 説明
- カテゴリ
- アイコン
- Instructions： エージェントに注入する専門的な指示
- ツールリスト： 自動的に適用するビルトインツールを選択

管理操作：

編集：作成済みのスキル設定を変更
削除：不要になったスキルを削除
ビルトインスキルの閲覧：ビルトインスキルの詳細な指示内容を確認可能

カスタムスキルのデータは ISkillStore に保存されます（ストレージバックエンドは設定されたデータベース Provider に依存します）。

クイックリファレンス

機能	ページパス	説明
API Key 設定	`/settings`	各プロバイダーとツールに必要な認証情報を設定
ナレッジベース管理	`/knowledge-bases`	ナレッジベースの作成、ファイルのアップロード、ドキュメントの管理
スキル管理	`/skills`	ビルトインスキルの閲覧、カスタムスキルの作成
サービステスト	Service Tester	MCP / A2A など外部サービスの接続テスト

ツールシステムと RAG ナレッジベース ​

Part 1: ツールシステム ​

1.1 エージェントの4層ツールソース ​

1.2 ビルトインツール（Tool Catalog） ​

1.3 MCP Server 統合 ​

1.4 A2A Agent 統合 ​

1.5 HTTP API ツール ​

1.6 OCR ツール ​

1.7 JS サンドボックススクリプト ​

Part 2: RAG とナレッジベース ​

2.1 RAG の概念説明 ​

2.2 ナレッジベース管理 ​

2.3 ワークフローでナレッジベースを使用する ​

2.4 検索モード ​

2.5 Advanced RAG コンポーネント ​

Part 3: スキルシステム ​

3.1 ビルトインスキル ​

3.2 カスタムスキル ​

クイックリファレンス ​

ツールシステムと RAG ナレッジベース

Part 1: ツールシステム

1.1 エージェントの4層ツールソース

1.2 ビルトインツール（Tool Catalog）

1.3 MCP Server 統合

1.4 A2A Agent 統合

1.5 HTTP API ツール

1.6 OCR ツール

1.7 JS サンドボックススクリプト

Part 2: RAG とナレッジベース

2.1 RAG の概念説明

2.2 ナレッジベース管理

2.3 ワークフローでナレッジベースを使用する

2.4 検索モード

2.5 Advanced RAG コンポーネント

Part 3: スキルシステム

3.1 ビルトインスキル

3.2 カスタムスキル

クイックリファレンス