Knowledge sources

A knowledge source is a system agents read rather than act on: its content is indexed into a knowledge base and searched with citations, with source permissions preserved.

مصدر المعرفة هو نظام يقرأه الوكلاء بدل أن يتصرّفوا فيه: يُفهرَس محتواه في قاعدة معرفة ويُبحث فيه مع الاستشهادات، مع الحفاظ على صلاحيات المصدر.

A system agents read: content indexed into a knowledge base and searched with kb.search, not called. That is the whole distinction from a connector: a connector gives an agent tools to act with; a knowledge source gives it text to cite. The same SharePoint site could be either — indexed as a knowledge source so agents can answer from the policy manual, or exposed through an MCP server so an agent can file a document into it. Ask which verb you need.

Knowledge source kinds

Every kind lands in the same place: a knowledge base (/v1/knowledge-bases) that chunks and embeds the content and that an agent manifest binds by id. Uploads are the simplest source — a file posted once. The other five are connected sources: a definition (site, space, folder, bucket or start URL in config), a credential bag that is encrypted at rest and never returned (the API shows only credential_meta.keys), and a sync that fetches, diffs and re-indexes.

Sync schedule and state

Two items here are roadmap, not shipped, and are labelled wherever they appear. Next: a knowledge-source test-connection endpoint that probes the source before the first sync (today the first sync is the test — its result lands in status and last_error). Next: persisted health for knowledge sources, so the console badge derives from a recorded check rather than from the last sync.

How agents read: kb.search

Agents never see a knowledge source; they see the knowledge base through one builtin tool, kb.search, which retrieves the best-matching chunks with citations back to the source document. The manifest lists which knowledge bases an agent may search (knowledge_bases[]) and must name the tool in tools.builtin for the agent to search at all; approval rules match it as builtin:kb.search; and POST /v1/knowledge-bases/:id/search with { query, top_k? } performs the same retrieval from the outside — useful to see exactly what an agent would be handed before you point it at a source.

Permissions travel with the document

Source permissions are preserved rather than flattened. Each document carries an access-control list (…/documents/:docId/acls) of principals — public, an end_user id, or a group name that is matched against the end user’s attributes.groups — and retrieval filters chunks by the end user of the run, so a citizen on the widget and a case officer in the Workspace get different answers from the same knowledge base. An empty list means unrestricted within the tenant. Replacing a document’s ACLs is audited (kb.document.acl.set).

API mapping

The API path for connected sources is /v1/knowledge-bases/:id/connectors — labelled knowledge sources (path kept for compatibility). The noun changed so that “connector” means one thing on these pages; the path did not, so nothing you have written breaks. Every path takes an API key plus X-Tenant-Id; adding, changing, deleting or syncing a source needs the admin role (an API key acts as admin; a console session needs it explicitly); listing and searching need member.