Skip to main content

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.

Knowledge bases let you augment your agent with domain-specific information it can retrieve on the fly. A few examples:
  • Frequently asked questions: Equip your agent with answers to common customer questions
  • Employee handbooks: Talk a new hire through PTO accrual, expense reimbursement, or open-enrollment deadlines.
  • Product catalogs: Quote prices, configurations, and stock when a caller asks about an item by name or SKU.
  • Support runbooks: Surface troubleshooting steps and known-issue workarounds for a tier-1 support agent.

​
What does a knowledge base look like?

Documents you upload to Cartesia are organized into folders. Agents can be granted access to the contents of folders, which comprise the agent’s knowledge base. Queries made by an agent only search documents in folders attached to that agent, so your organization can keep separate corpora for different agents without leaking content across them.
Knowledge Base in playground

​
Upload documents

Create a folder, then add documents to it. Folders can be nested within parent folders.
1

Create a folder

Knowledge Base in playground
  1. Go to Knowledge Base in the sidebar
  2. Click New folder and enter a name
Folders can be nested by clicking the “Add subfolder” icon on the parent folder’s row.
2

Upload a document

Knowledge Base in playground
  1. Click the Upload document icon on the folder you wish to upload documents to.
  2. Select the files from your computer
  3. Add any metadata you want to filter by later.
Documents are automatically indexed on upload.

​
Associate folders with an agent

Attach folders to an agent to make them queryable from the agent’s knowledge_base tool. Only folders attached to the agent are searched; an agent with no folders attached returns empty results from every query. Changes take effect immediately for in-progress and future calls.
Knowledge Base in playground
Open your agent, then select the folders to attach in the Knowledge Base section. Deselect all folders to detach every folder.

​
Using the knowledge base from your agent

​
knowledge_base tool

knowledge_base is a built-in tool. Drop it into an agent’s tools list and the LLM calls it on its own when it needs to look something up. 
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?",
    ),
)
The LLM picks the query string; every other parameter is fixed at construction time. 
tools=[knowledge_base(
    filters={"category": "billing"},
    top_k=10,
    description="Look up billing and payment policy details.",
    timeout_s=2.0,
    is_background=True,
)]
See Parameters for the full list of options.

​
Call the knowledge base directly

For custom retrieval logic—reranking, post-filtering, fanning out multiple queries—call the KnowledgeBase client directly from inside your own tool: 
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() returns a KnowledgeBase instance authenticated with the agent’s session-scoped token. No setup is required—the SDK wires this up when the call starts. kb.query(...) raises KnowledgeBaseError on timeout, transport failure, or non-200 responses. Catch it if you want to fall back to a different code path; the built-in knowledge_base tool already handles this for you. See below for the options accepted by kb.query(...).

​
Parameters

ParameterTypeDefaultDescription
filtersdictNoneMetadata filter applied to every query. See Filter syntax.
top_kint5Number of chunks to return. Higher values give your agent more context, at the cost of more tokens in the context window and higher latency.
descriptionstrGeneric lookup promptTool form only. Fully replaces the tool description shown to the LLM. Tailor it to your domain.
timeout_sfloat3.0Per-call timeout. Values above 10s log a warning, as long running queries stall the call if is_background is not enabled.
is_backgroundboolFalseTool form only. When true, runs as a background tool so the agent can keep speaking while the query is in flight.

​
Filter syntax

Filters are a flat {metadata_key: metadata_value} map. Each entry is an equality match against a document’s metadata; multiple entries are combined with AND. 
# documents where category == "billing"
filters={"category": "billing"}

# documents where category == "policy" AND audience == "customer"
filters={"category": "policy", "audience": "customer"}
Note that folder-based access control is applied automatically, so does not need to be explicitly specified