> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# ナレッジベース
ナレッジベースを利用すると、エージェントが必要に応じて取得できるドメイン固有の情報をエージェントに付与できます。いくつかの例：
* **よくある質問**: お客様からよくある質問への回答をエージェントに装備
* **従業員ハンドブック**: 新入社員に PTO（有給休暇）の付与、経費精算、オープン登録の締切などを案内
* **製品カタログ**: 発信者が商品名や SKU で問い合わせた際に、価格、構成、在庫を回答
* **サポートランブック**: ティア 1 のサポートエージェントにトラブルシューティング手順や既知の問題の回避策を提示
## ナレッジベースとは
Cartesia にアップロードしたドキュメントはフォルダー単位で整理されます。エージェントにはフォルダーの内容へのアクセス権が付与され、それがエージェントのナレッジベースを構成します。エージェントが行うクエリは、そのエージェントにアタッチされたフォルダー内のドキュメントだけを検索するため、組織内で異なるエージェントごとに別々のコーパスを保持しつつ、コンテンツの相互流出を防ぐことができます。
## ドキュメントのアップロード
フォルダーを作成し、そこにドキュメントを追加します。フォルダーは親フォルダーの中にネストできます。
1. サイドバーの **Knowledge Base** に移動します
2. **New folder** をクリックして名前を入力します
親フォルダーの行にある「Add subfolder」アイコンをクリックすることで、フォルダーをネストできます。
1. ドキュメントをアップロードしたいフォルダーの **Upload document** アイコンをクリックします。
2. コンピュータからファイルを選択します
3. 後で [フィルタリング](#filter-syntax) したいメタデータを追加します。
ドキュメントはアップロード時に自動的にインデックスされます。
```bash theme={null}
curl -X POST https://api.cartesia.ai/agents/folders \
-H "X-API-Key: $CARTESIA_API_KEY" \
-H "Cartesia-Version: 2026-03-01" \
-H "Content-Type: application/json" \
-d '{"name": "Product Docs", "parent_id": null}'
```
フォルダーをネストするには `"parent_id"` を渡します。レスポンスにはフォルダー `id` が含まれ、後続のリクエストで参照します。
```bash theme={null}
curl -X POST https://api.cartesia.ai/agents/documents \
-H "X-API-Key: $CARTESIA_API_KEY" \
-H "Cartesia-Version: 2026-03-01" \
-H "Content-Type: application/json" \
-d '{
"folder_id": "folder_abc",
"name": "Return Policy",
"content": "Customers may return any unopened item within 30 days...",
"metadata": {"category": "policy", "audience": "customer"}
}'
```
ドキュメントはアップロード時に自動的にインデックスされます。1 回のリクエストで最大 100 ドキュメントをアップロードするには、`documents` 配列を含む `POST /agents/documents/bulk` を使用します。
## エージェントとフォルダーの関連付け
フォルダーをエージェントにアタッチすると、エージェントの `knowledge_base` ツールから検索できるようになります。検索対象になるのはエージェントにアタッチされたフォルダーのみであり、フォルダーがアタッチされていないエージェントは、すべてのクエリに対して空の結果を返します。変更は進行中および今後の通話に即時反映されます。
エージェントを開いて、**Knowledge Base** セクションでアタッチしたいフォルダーを選択します。すべてのフォルダーの選択を解除すると、すべてのフォルダーがデタッチされます。
フォルダーの `agents` フィールドを、そのフォルダーをナレッジベースに含めたいエージェントに設定します。空の配列を送ると、フォルダーがすべてのエージェントからデタッチされます。
```bash theme={null}
curl -X PATCH https://api.cartesia.ai/agents/folders/$FOLDER_ID \
-H "X-API-Key: $CARTESIA_API_KEY" \
-H "Cartesia-Version: 2026-03-01" \
-H "Content-Type: application/json" \
-d '{
"agents": [
{"id": "agent_abc"},
{"id": "agent_def"}
]
}'
```
## エージェントからナレッジベースを使用する
### `knowledge_base` ツール
`knowledge_base` は組み込みのツールです。エージェントの `tools` リストに加えるだけで、LLM が必要に応じて自動的に呼び出します。
```python theme={null}
import os
from line.llm_agent import LlmAgent, LlmConfig, end_call, knowledge_base
agent = LlmAgent(
model="anthropic/claude-haiku-4-5-20251001",
api_key=os.getenv("ANTHROPIC_API_KEY"),
tools=[end_call, knowledge_base],
config=LlmConfig(
system_prompt=(
"You are a customer support agent. "
"Use the knowledge_base tool whenever the user asks about products, policies, or pricing."
),
introduction="Hi! How can I help?",
),
)
```
LLM がクエリ文字列を選択し、それ以外のすべてのパラメータは構築時に固定されます。
```python theme={null}
tools=[knowledge_base(
filters={"category": "billing"},
top_k=10,
description="Look up billing and payment policy details.",
timeout_s=2.0,
is_background=True,
)]
```
オプションの完全なリストについては [パラメータ](#parameters) を参照してください。
### ナレッジベースを直接呼び出す
カスタムの取得ロジック（リランキング、ポストフィルタリング、複数クエリのファンアウトなど）が必要な場合は、自作のツール内から `KnowledgeBase` クライアントを直接呼び出します：
```python theme={null}
from typing import Annotated
from line.llm_agent import loopback_tool
@loopback_tool
async def lookup_policy(
ctx,
topic: Annotated[str, "Policy topic to look up"],
) -> str:
"""Search the policy knowledge base."""
kb = ctx.knowledge_base()
results = await kb.query(
f"policy: {topic}",
filters={"category": "policy"},
top_k=3,
timeout_s=2.0,
)
return "\n\n".join(r["content"] for r in results) or "No policy found."
```
`ctx.knowledge_base()` は、エージェントのセッションスコープトークンで認証済みの `KnowledgeBase` インスタンスを返します。通話開始時に SDK が自動的に設定するため、追加のセットアップは不要です。
`kb.query(...)` は、タイムアウト、トランスポート障害、または非 200 のレスポンス時に `KnowledgeBaseError` を発生させます。別のコードパスにフォールバックしたい場合はこれをキャッチしてください。組み込みの `knowledge_base` ツールではこれが既に処理されています。
`kb.query(...)` が受け付けるオプションについては以下を参照してください。
### パラメータ
| パラメータ | 型 | デフォルト | 説明 |
| --------------- | ------- | -------------- | ------------------------------------------------------------------------------------------------------ |
| `filters` | `dict` | `None` | すべてのクエリに適用されるメタデータフィルター。[フィルター構文](#filter-syntax) を参照。 |
| `top_k` | `int` | `5` | 返されるチャンクの数。値を大きくするとエージェントに与えるコンテキストが増えますが、コンテキストウィンドウのトークン消費とレイテンシも増加します。 |
| `description` | `str` | 汎用のルックアッププロンプト | ツール形式の場合のみ。LLM に表示されるツールの説明を完全に置き換えます。あなたのドメインに合わせてカスタマイズしてください。 |
| `timeout_s` | `float` | `3.0` | 呼び出しごとのタイムアウト。10 秒を超える値は警告がログに記録されます。長時間実行クエリは `is_background` を有効にしていないと通話が停止してしまうためです。 |
| `is_background` | `bool` | `False` | ツール形式の場合のみ。true にすると [バックグラウンドツール](./sdk/tools#long-running-tools) として実行され、クエリ実行中もエージェントは話し続けることができます。 |
### フィルター構文
フィルターはフラットな `{metadata_key: metadata_value}` マップです。各エントリはドキュメントメタデータに対する等価マッチで、複数エントリは AND で結合されます。
```python theme={null}
# documents where category == "billing"
filters={"category": "billing"}
# documents where category == "policy" AND audience == "customer"
filters={"category": "policy", "audience": "customer"}
```
なお、フォルダーベースのアクセス制御は自動的に適用されるため、明示的に指定する必要はありません