Knowledge Bases

Overview

Knowledge bases give agents access to your domain knowledge without stuffing everything into the system prompt. Instead of pre-loading context, the agent retrieves relevant chunks at runtime — a pattern called RAG (retrieval-augmented generation).

There are two retrieval modes:

Manage knowledge bases from the Knowledge Bases hub. Each KB has a unique slug used to reference it in agent bindings.

Enabling the service

Knowledge bases require an embedding model. Set the EMBEDDING_MODEL environment variable on your backend to enable the service:

# Example: use OpenAI's text-embedding-3-small
EMBEDDING_MODEL=openai/text-embedding-3-small

# Or a Gemini model
EMBEDDING_MODEL=gemini/text-embedding-004

When enabled, the GET /api/management/capabilities endpoint returns { knowledge_base: { enabled: true, embedding_model: "..." } }. The dashboard shows a warning banner on KB pages when the service is disabled.

Creating a knowledge base

Go to Knowledge Bases → New. Set a name, slug, and optional description. The slug is how you reference the KB in agent bindings — choose something stable like product-docs or faq.

After creating the KB, upload documents (PDF, DOCX, TXT, Markdown) or paste text directly. Each document is chunked, embedded, and indexed automatically.

Binding to agents

Give an agent access to a KB using the knowledge array on an Agent node. Each entry specifies a KB slug and retrieval mode:

{
  "type": "Agent",
  "id": "support",
  "model": "gpt-4o",
  "system_prompt": "You are a helpful support agent.",
  "input": "{{run.question}}",
  "knowledge": [
    { "slug": "faq", "mode": "tool" },
    { "slug": "product-docs", "mode": "context", "query": "{{run.question}}" }
  ]
}

Registered agents can also have knowledge bindings in their configuration. Node-level bindings are merged with agent-level bindings at runtime.

Each binding accepts optional constraint fields. Constraints are an upper bound: the model can narrow them at call time (fewer results, a subset of classes) but can never widen them — the server clamps any widening attempt back to the binding.

Tool mode

mode: "tool" (the default) injects a scoped knowledge_search tool the agent can call dynamically. The tool is restricted to the bound KB(s) — the agent cannot search arbitrary slugs.

{
  "knowledge": [{ "slug": "faq" }]
}

When the agent calls the tool, it passes a search query and receives relevant document chunks. Use this mode when:

• The agent should decide when to search
• You have multiple KBs and want the agent to pick which to query
• You want to minimize upfront latency

Context mode

mode: "context" pre-retrieves relevant chunks before the agent loop begins and injects them as context. The query field specifies what to search for (template-resolved):

{
  "knowledge": [
    { "slug": "product-docs", "mode": "context", "query": "{{run.question}}" }
  ]
}

The retrieved content appears in the agent's input as a "Retrieved Knowledge" block. Use this mode when:

• You always want context from a specific KB
• You know the query upfront (e.g. the user's question)
• You want to avoid tool-call overhead

Hybrid retrieval

Every search runs two legs: a vector similarity leg over embeddings and a lexical full-text leg (Postgres FTS), fused with reciprocal rank fusion (RRF). This means exact identifiers — SKUs, error codes, names — rank well even when they embed poorly. Each result reports its provenance (vector, lexical, or both) in search responses and the KB Search tab.

Lexical search is on by default. Opt out per-KB with { "search": { "lexical": false } } in the KB configuration.

Wiki & navigation

Wiki-enabled document classes compile ingested documents into an interlinked markdown wiki with citations back to source chunks. By default compilation is incremental: each ingested document compiles into page create/update operations (LLM-merged into existing pages) rather than rebuilding the whole wiki. A full rebuild is available from the KB page or POST /knowledge-bases/{id}/recompile.

Agents bound to a wiki-enabled KB get a second tool, knowledge_read_page, alongside knowledge_search. Wiki search results include the page slug, parent, and outbound wiki links; the agent can follow them to read full pages — including the index table-of-contents page — turning retrieval into navigation. Disable this per-binding with navigation: false.

Pages can also be manually authoredin the full-page wiki editor. Manual edits use optimistic concurrency: if someone else saved first, the editor shows a conflict dialog (keep mine / take theirs / copy). Compiled pages can't be deleted directly — recompilation would resurrect them — so convert them to manual pages first ("Convert to manual"), which forks them out of the compiler's ownership.

Ingesting from workflows

The knowledge_ingest tool lets workflows add content to a KB programmatically. Use it in a Tool node:

{
  "type": "Tool",
  "id": "save-to-kb",
  "tool": "knowledge_ingest",
  "input": {
    "kb_slug": "customer-feedback",
    "content": "{{collect.feedback}}",
    "metadata": {
      "customer_id": "{{run.customer_id}}",
      "date": "{{run.date}}"
    }
  }
}

The content is chunked, embedded, and indexed just like uploaded documents. Use this to build KBs dynamically from workflow outputs — transcripts, summaries, feedback, etc.

Visibility & scoping

Knowledge bases are project-scoped. An agent can only bind a KB from its own project, unless the KB's visibility is set to org (shared workspace-wide, configurable in KB Settings). Out-of-scope bindings are rejected at save time (the editor problems panel shows the error), re-checked at deploy time, and enforced again at runtime.

At deploy time, KB slugs resolve the same way connection slugs do: the deployment's connection_bindings map is checked first (useful for per-environment KB aliases), then a direct slug match. Most deployments use direct slugs with no bindings.