知識ベースの構築とデータ入力

原則 — 基盤を固め、その後検証する。 ナレッジベースは、ヒントではなく、従わなければならないソースです。instructions でそのカバー範囲を定義し、実際に依存する前に、実在する質問が検索結果を返すことを必ず確認してください — 検索結果が空の場合、エージェントは「対象外」と回答します。詳細は 設計原則 を参照してください。

マウントされたナレッジベースは ターンごとに自動で検索されます — モデルは検索するかどうかを判断しません。関連性はベクトル距離によって決定されます。これは意図的な設計です：ナレッジベースはオプションのツールではなく、従わなければならないソースです。

1. 作成する

create_knowledge_base(
  name="Company policy",
  description="Mortgage policy and rates, effective 2026 — not car or personal loans",  # routes questions here
  instructions="Authoritative current mortgage policy; overrides any industry norm. "
               "Covers home mortgages only; for car or personal loans, say so and hand off.",  # for the model
)

名前は作成時に URL 安全なスラッグに正規化されます — "Company policy" は company-policy として返されます。作成後のすべての操作（add_knowledge_text(kb_name=…), search_knowledge_base(kb_name=…), およびエージェントへのアタッチ）では、この 返された 名前を使用してください。後から元のスペース付きの名前を入力すると、404 エラーになります。

2. description を記述する — これが質問をこのベースにルーティングする

description はキャプションではありません。回答のたびにプラットフォームは、アタッチされた各ベースの description を読み、この質問にどのベースが必要かを判断します — そして、どのベースも必要でない場合は、検索を一切行いません。3つのベースを持つエージェントは、訪問者が「こんにちは」と言った場合でも、ターンごとに3つのベクトル検索を実行し、3セットの抜粋をプロンプトに追加することになります。

したがって、description が曖昧または空のベースは、検索すべきでないときに検索され、また — さらに悪いことに — 検索すべきときに検索されません。これらの失敗は明示的に通知されません：前者は関連のない引用付きの遅い回答として現れ、後者は「その件については何も持っていません」として現れます。

訪問者が使用する言葉で、主題を名指す1行を記述してください：

✅ "Country-by-country medical device registration requirements"
✅ "Regulatory change news by country and authority, 2022–2026 — what changed and when"
✅ "Selpercatinib — for lung and thyroid cancer"
 
❌ "Knowledge base"                ← routes nothing
❌ "Imported from the website"     ← says where it came from, not what is in it
❌ "Sandbox test, safe to delete"  ← says why it exists, not what is in it

重要なのは、長さにこだわることではなく、他のベースと区別できることです。 9つのベース（8つの薬品と1つの会社概要、それぞれ1行、12語以内）を持つテナントは、10問中10問を正しくルーティングします。「lung and thyroid cancer（肺および甲状腺がん）」と「IgA nephropathy（IgA腎症）」は決して混同されないためです。測定されたもの、推測されたものではありません。

2つのベースが重複する場合にのみ境界線を設けてください。 製品ページとニュースアーカイブの両方で同じ主題について言及している場合、どちらがどちらであるかを明記してください — 「…— 価格や会社情報ではない」が、アーカイブが価格に関する質問に答えるのを防ぎます。ベースがすでに明らかに区別できる場合、境界節を追加しても何も得られません。

この1行はコンソールのリストでも表示されますが、それは副次的な役割です。

3. 想定される使用方法から instructions を記述する — 作成時、「後から」ではなく

instructions は検索精度（recall）に影響しません — 検索精度はベクトル検索と max_distance によります。これは回答時にこのナレッジベースの抜粋の横に注入されるため、モデルが検索した結果をどのように使用するかを規定します。空白の場合、KB は依然として検索されますが、回答からは KB 固有のルール（権威、境界、引用規約）がすべて失われます。空白で許されるのは、特別なルールがない一般的な参照資料 のみ です。

KB が実際にどのように使用されるかから導き出し、質問ごとに1行を記述してください：

KB 種別別のナレッジベース指示の例：

# Website-content KB (products, services, team, blog)
instructions="Company website content: products, services, team and blog posts. Authoritative
for what we offer and who we are. Marketing copy is not a contractual promise — for prices,
terms or eligibility prefer the policy KB; if only this KB answers, attribute it to the website."
 
# Policy / regulation KB
instructions="Current company policy, effective 2026; overrides industry norms and prior
knowledge. Covers home mortgages only — for car or personal loans, say so and hand off.
Any quoted rate or fee must state its effective date."
 
# Product-docs KB
instructions="Official product documentation for the current release. State the version when a
feature is version-dependent. If the docs don't cover something, say so — never fill the gap
from general knowledge."

4. コンテンツを追加する

add_knowledge_text(kb_name="Company policy", title="2026 late-fee rule",
                   content="From 1 July 2026 the daily late fee is 0.019% …")

バイナリファイル（pdf/docx）やフォルダ全体（zip化）は add_knowledge_file を通じて追加します — サブフォルダは再帰的に探索され、各 md/txt/pdf/html/docx はアーカイブ内のパスに従ってインポートされます。

4b. 検索されたい文章を記述する

検索は 意味 に基づいて一致し、値そのものにはほとんど意味がありません。これはあなたが制御できる中で最も高いレバレッジを持つ要素であり、エラーが発生しないため、誤りやすいものです — 検索は依然として何かを返しますが、それは正しいものではありません。

実際の顧客カタログには、1,500レコード中 1,480 にこの1行が含まれていました：

Reading level: 1 · Age: 5 · Words: 1951

そして、「自分で読み始め始めた子供に適した本はどれか」という質問に対して、音楽の神童に関する本が返ってきました。その事実はテキストに含まれていましたが、到達不可能でした：1 は、1つの単語が別の単語に似ているのと同様に、beginner reader（初心者向け読者） とは似ても似つきません。

値の横に1行追加することで修正されました — 同じレコードで測定済み：

Reading level: 1 · Age: 5
Suitable for around age 5, for children just starting to read on their own.

（数値が低いほど近い。このモデルでは、2つの 無関係な 段落は約 0.61 に位置するため、最後の行は「偶然よりわずかに良い」から本格的な一致へと移動し — その効果は言語を超えて持続します。）

ルール：プロパティ（価格、日付、レベル、在庫、在庫数）ではなく文章によって回答される質問の場合、それを言葉でも記述してください。 構造化された値はフィルタリング用です；検索は書かれたものを見つけます。

時間の価値がないもの

エクスポートはしばしば自身を繰り返します — 同一の文章を含む summary と description。それは無駄に見え、「ベクトルを使い果たす」という直感が働きますが、それは誤りです：測定したところ、重複を削除しても検索精度は 60レコード全体で距離が +0.002 変化 — つまり、何の変化もありません。埋め込みベクトルは予算ではなく方向です；同じことを2回言うことは、主に同じ方向を2回指すことに他なりません。

そのままにしてください。その代わりに、上記の文章に努力を費やしてください。

4c. ドキュメントに共通のヘッダーがある場合、構造化インデックスを構築する

ベクトル検索は、カウントしたり、数値でフィルタリングしたり、グループ化したりできません。「いくつあるか」、「200語未満のものはどれか」、「カテゴリごとにいくつあるか」は悪く回答されるのではなく、構造的に回答不可能 であり、エージェントは断るか、たまたま取得した数少ないレコードについて報告するだけです。

build_knowledge_index(name="books", roles=["identity", "link", "image"])

ドキュメントが機械可読なヘッダーを共有している場合にのみ呼び出す価値があります — メタデータテーブル、YAML フロントマター、Field: value 行など。製品エクスポート、カタログ、リーフレット、コースリストは通常該当します；散文は該当せず、すべての値が異なるテーブルを構築する呼び出しは却下されます。却下は、回避すべきエラーではなく、正しい結果です。

roles は、正確に 抽出され、決して要約されないフィールドの名前を指定します：

これらのフィールドが何かをユーザーに問い、推測しないでください。 顧客に送るべき3つのURLのうちどれが それ かは、データが示さないビジネス上の事実です。宣言されたロールが見つからない場合、roles.unresolved に 候補フィールド名 として返されます — 1つを選ぶのではなく、それらをユーザーに提示してください。

dropped を読み、ユーザーに伝える

{"built": true, "documents": 4523,
 "columns": ["title", "age", "word_count", "genre", "read_url", "cover_url"],
 "dropped": [["isbn", "not_found", "no anchor 'ISBN: ' in the sample"]]}

ドロップされた列は 他のすべての場所で不可視です — 後の回答は単にそれを回避して動作するため、このレポートは唯一言及される場所です。get_knowledge_index も同様で、その警告は顧客が知らなかったデータ問題を日常的に浮上させます — 実際のカタログの1つでは、レコードの10%がページ数 0 を持っており、これは短い本ではなく、ゼロとして記録された欠損値であり、これに基づいて計算されるすべての平均値を低下させる原因となっていました。

それらを顧客自身の用語で報告してください。プラットフォームの他のどこにもありません。

後から変更する

patch_knowledge_index(name="books", request="also track the author", apply=false)

まず apply=false で実行し、ユーザーに変更内容を提示し、複数の編集をバッチ処理してから、一度適用します。適用すると 保存されたテキストからフィールドを再読み込みします；再埋め込みは行いません ので、コストは低いです。

ドキュメントに含まれていないものを要求すると、理由付きの refused エントリが返されます — 回避策を考案するのではなく、それをそのままユーザーに渡してください。

5. ★ 検索を検証する — 省略するな ★

search_knowledge_base(kb_name="Company policy", query="how is the late fee calculated")
#   hits  → the agent can answer this
#   empty → the agent will treat it as "not covered" and say so

6. マウントする

update_agent(name="Support", add_knowledge_bases=["company-policy"])   # incremental — keeps existing mounts

instructions に「常に抜粋を引用せよ」と書かないでください — その動作は組み込まれています。 この ライブラリ固有のことのみを記述してください：権威の順序付け、カバー範囲の境界、特別な使用方法（例：「利率を引用する場合は有効日付を明記すること」）。

報告せよ — 「インポートされた」で終わるな。 ユーザーに、どのくらいのチャンクが着地したかを伝え、ナレッジベースとその ナレッジスターマップ（インポートされた内容の3Dビュー）を開くためのクリック可能なリンクを提供してください：https://console.agent4.io/#/knowledge-bases/Company%20policy — その後、エージェントにアタッチされていることを確認してください。