Knowledge

Knowledge sources (ks_…) hold the facts your agent answers from: prices, opening hours, policies, a product catalog, a live feed from your systems. Sources belong to the project, so several agents can share them, and each agent chooses which sources it uses and how.

Kinds of source

Kind	Content	Good for
text	Free text, up to 200,000 characters	Policies, FAQs, service descriptions
catalog	One item per line, or CSV	Price lists, product and branch lists
api	Fetched from your URL on a schedule and turned into lines	Stock, schedules, anything that changes daily

curl https://api.k-agent.kerneltics.com/v1/knowledge_sources \
  -H "Authorization: Bearer $KAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Price list",
    "kind": "catalog",
    "content": "Royal oud oil 12 ml — 450 SAR\nWhite musk perfume 100 ml — 220 SAR\nBakhoor box — 95 SAR\nGift set (perfume + bakhoor) — 280 SAR"
  }'

Always or searchable

An agent attaches sources in knowledge.sources, each with a mode:

{
  "knowledge": {
    "sources": [
      { "source_id": "ks_01k6rz2n5q8t1w4z7c0f3h6k9m", "mode": "always" },
      { "source_id": "ks_01k6rz2p9r3t5w7y1a3c5e7g9j", "mode": "searchable" }
    ]
  }
}

Mode	How the agent uses it	Use it for
always	The whole source is in the prompt, under “Context Information”, in the order you list it.	Short, essential facts the agent needs in every conversation.
searchable	The agent looks things up with the built-in search_knowledge tool when it needs them.	Long catalogs and documents.

Each source shows a token estimate. When the always sources of an agent add up to more than about 8,000 tokens, the dashboard suggests making some of them searchable: big prompts cost more on every turn and dilute attention.

Knowledge is live across versions: editing a source changes the answers of every version of every agent that uses it, without publishing. The editor and the prompt X-ray label it “Live: applies to all versions”, and each run step records the updated_at of the sources it used.

Arabic-aware search

search_knowledge is built for how people actually type in Arabic. Both your content and the query are folded before matching:

• أ إ آ become ا, ة becomes ه, ى becomes ي;
• diacritics (harakat) and tatweel (ـ) are removed;
• Arabic-Indic digits (٠١٢٣٤٥٦٧٨٩) become ASCII digits;
• common stop words are ignored.

Matching is word-by-word with typo tolerance: one edit for words of 3–5 letters, two edits for 6 letters or more, and none below 3. A line that matches every word of the query ranks above partial matches, ties go to the shorter line, and at most 25 hits are returned. So صندق بخور (a common misspelling) still finds صندوق بخور — 95 ريال.

Catalog and API sources are split into one chunk per line; text sources into paragraphs of up to 800 characters.

When nothing matches

A missed search is only treated as evidence when every searched source is marked complete — “this list is everything we sell”. Then the agent may say you don’t offer it. Otherwise it is told that nothing matched in the notes it searched, that this does not show the business lacks it, and to answer from what it knows or hand the question to your team.

complete defaults to true for catalog and transformed api sources, and false for text.

Test a search

curl https://api.k-agent.kerneltics.com/v1/knowledge/search \
  -H "Authorization: Bearer $KAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "كم سعر صندق البخور", "source_ids": ["ks_01k6rz2n5q8t1w4z7c0f3h6k9m"]}'

API sources

An api source fetches JSON from your URL on a schedule and turns it into lines the agent can use:

{
  "name": "Products and prices",
  "kind": "api",
  "config": {
    "url": "https://api.example.com/products?status=active",
    "headers": { "Authorization": "Bearer {{secret.CATALOG_TOKEN}}" },
    "refresh_minutes": 60,
    "transform": {
      "items_path": "data.products",
      "line": "- {name} — {price} SAR",
      "group_by": "category",
      "sort_by": "price",
      "skip_when_zero": "price",
      "max_items": 500,
      "header": "Current prices"
    }
  }
}

• refresh_minutes is between 15 and 1440 (default 60). The source also syncs right away when you change its URL or transform, and on demand with POST /v1/knowledge_sources/{ks}/sync.
• transform turns the response into lines: items_path points at the list; line is a template with single-brace {field} placeholders; group_by adds a ### <value> heading per group, biggest group first; sort_by sorts ascending within each group; skip_when_zero drops items whose field is zero or missing; max_items caps the list; header goes on top.
• Headers use secrets by name, never plain values, and the secret’s allowed_hosts must include the URL’s host.
• The request goes through the same protected client as HTTP tools: public https:// URLs on port 443 or 8443 only, no redirects, a 1 MiB limit.
• Failures keep the last good copy. A non-2xx response, invalid JSON, a missing items_path or an empty result counts as a failure: the previous content stays in use, the source shows the error, the knowledge_source.sync_failed webhook fires and the agent’s readiness shows knowledge_sync_failing.

Endpoints

Method and path	Purpose
GET, POST /v1/knowledge_sources	List and create sources
GET, PATCH, DELETE /v1/knowledge_sources/{ks}	Read, update, delete
POST /v1/knowledge_sources/{ks}/sync	Fetch an api source now
POST /v1/knowledge/search	Run a test search

Request bodies for knowledge can be up to 5 MiB.