Overview

Knowledge base (kb) tools give the agent the ability to perform a RAG (Retrieval-Augmented Generation) search over documents you’ve uploaded. When the agent calls the tool, the worker runs a semantic similarity search against the document chunks and returns the most relevant passages.

Documents are uploaded and managed via the Knowledge Base API.

Tool definition

{
  "name": "search_docs",
  "kind": "kb",
  "description": "Search the company knowledge base for policy, product, and procedure information. Use this when the user asks a question that might be answered in our documentation.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The question or topic to search for"
      },
      "top_k": {
        "type": "integer",
        "description": "Number of results to return (default 5)",
        "default": 5
      }
    },
    "required": ["query"]
  },
  "config": {}
}

The config object is empty for kb tools — the worker uses the session-level kb_query_url and kb_query_api_key configured on the character.

How it works

1. The LLM calls the kb tool with a query string
2. The worker sends GET /api/knowledge-base/query/?q={query}&top_k={top_k} to the backend
3. The backend embeds the query using OpenAI text-embedding-ada-002 and runs a cosine similarity search across all document chunks
4. The top-k passages are returned to the LLM as tool output:

[
  {
    "text": "Our refund policy allows returns within 30 days of purchase...",
    "metadata": { "source": "refund-policy.pdf", "page": 2 }
  },
  {
    "text": "Digital products are non-refundable once downloaded...",
    "metadata": { "source": "refund-policy.pdf", "page": 2 }
  }
]

5. The LLM synthesises an answer from the passages and speaks it to the user.

Tips for good retrieval

• Upload focused documents. One document per topic retrieves better than one giant PDF.
• Use descriptive file names. The file name is included in metadata.source and helps the LLM cite sources.
• Ask specific queries. The agent’s query quality determines result quality — prompt the LLM to extract the user’s core question before calling the tool.
• Tune top_k. The default is 5 passages. For dense technical docs, increase to 8–10. For short FAQs, 3 is sufficient.

Uploading documents

See Knowledge Base → Documents for the upload API.

Supported formats: PDF, DOCX, TXT.

Documents are automatically chunked (≈500 tokens) and embedded on upload. Status transitions from PENDING → PROCESSED (or FAILED on error).