Knowledge / RAG

Retrieval-Augmented Generation (RAG) lets agents answer questions based on your documents. Instead of relying solely on the LLM’s training data, the agent searches a knowledge base and includes relevant passages in its context before generating a response.

How it works

Set knowledge: "./path/" in agent config to enable RAG for that agent.
The engine auto-indexes all documents in the folder at startup. Supported formats: .md (Markdown) and .txt (Plain text).
A knowledge_search tool is injected automatically when a knowledge path is configured.
When the agent calls knowledge_search, the engine performs a vector similarity search and returns the most relevant passages.
The agent uses these passages to generate grounded, accurate responses.

# Document indexing flow:
#
#   |-- faq.md              --> chunked, embedded, indexed
#   |-- returns-policy.txt  --> chunked, embedded, indexed
#
#   Agent calls knowledge_search("return policy for electronics")
#   --> Engine finds the most relevant chunks from returns-policy.txt
#   --> Agent uses them to answer: "Our electronics return policy..."

Configuration

agents:
  support-bot:
    model: glm-5
    knowledge: "./docs/support/"     # Path to knowledge base folder
    tools:
      - knowledge_search             # Injected automatically, but explicit is fine
    system: |
      Answer customer questions using the knowledge base.
      Always cite which document you found the information in.
      If you cannot find the answer, say so honestly -- do not
      make up information.

Per-agent isolation

Each agent has its own isolated knowledge base. Agent A cannot search agent B’s documents. This is important for multi-tenant deployments and role-based access:

agents:
  sales-bot:
    knowledge: "./docs/sales/"         # Only sales materials
    tools: [knowledge_search]

  hr-bot:
    knowledge: "./docs/hr-policies/"   # Only HR policies
    tools: [knowledge_search]

# sales-bot cannot see HR policies
# hr-bot cannot see sales materials

Best practices

Keep documents focused — smaller, topic-specific documents work better than large monolithic ones.
Use clear headings — Markdown headings help the chunking algorithm split documents at logical boundaries.
Update regularly — keep knowledge bases current. Outdated information leads to incorrect agent responses.
Tell the agent to cite sources — add instructions in the system prompt to reference which document the answer came from.
Set honest boundaries — instruct the agent to say “I don’t know” rather than hallucinate when the knowledge base does not contain the answer.

Managing knowledge bases via Admin Dashboard and API

The YAML knowledge: path is the simplest way to attach documents to an agent. For more control — uploading files without restarting, linking multiple knowledge bases, or managing content dynamically — use the Admin Dashboard or the API directly.

Admin Dashboard

Go to Knowledge Bases in the sidebar.
Create a knowledge base and give it a name.
Upload .md or .txt files. The engine indexes them automatically.
Go to your agent’s detail page → Capabilities tab → add the Knowledge capability and select the knowledge base.

One knowledge base can be linked to multiple agents, and one agent can use multiple knowledge bases.

API

# Create a knowledge base
curl -X POST http://localhost:8443/api/v1/knowledge-bases \
  -H "Authorization: Bearer bb_your_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "product-docs", "description": "Product documentation"}'

# Upload a file
curl -X POST http://localhost:8443/api/v1/knowledge-bases/product-docs/files \
  -H "Authorization: Bearer bb_your_token" \
  -F "file=@./docs/faq.md"

# Link a knowledge base to an agent
curl -X POST http://localhost:8443/api/v1/knowledge-bases/product-docs/agents/sales-bot \
  -H "Authorization: Bearer bb_your_token"

# List files in a knowledge base
curl http://localhost:8443/api/v1/knowledge-bases/product-docs/files \
  -H "Authorization: Bearer bb_your_token"

# Reindex a file (after updating content)
curl -X POST http://localhost:8443/api/v1/knowledge-bases/product-docs/files/file_id_here/reindex \
  -H "Authorization: Bearer bb_your_token"

YAML path vs API

Approach	When to use
`knowledge: "./path/"` in YAML	Simple setups, static documents, Git-managed content.
Admin Dashboard / API	Dynamic content, multiple knowledge bases per agent, file uploads without restarts.