Knowledge Management Agents

Status: Implementation qualification | Last reviewed: 2026-10-09

Knowledge Management is an optional text_to_text agent subtype, knowledge_management_agents, with agent_type: knowledge_management and a versioned knowledge configuration. Its workspace is /agents/{id}/knowledge. FEATURE_KNOWLEDGE_AGENTS=true enables creation, authoring, query routes and workers; the default is off. This is a Vanguard capability under qualification. The delivery plan separates the native first release from subsequent connectors and destinations.

Setup and execution

Apply migration 075_knowledge_agents.sql through the city migration runner. Start npm run knowledge:worker from apps/ai-manager with the effective Studio environment; the devcontainer Procfile includes knowledge-worker for new stack starts. It needs the same database, encryption and asset-storage settings as Studio's Analytics worker. A running Overmind instance must be restarted to recognize an added process, or the worker can run separately using .devcontainer/scripts/start-knowledge-worker.sh.

In Health, a configuration administrator sets the tenant's native RAGFlow URL and API token. The token is encrypted in tenant_settings.knowledge_ragflow and returned only as a mask. Agent configurations, builds and browser storage do not contain it. Select a tenant LLM integration in Answer for synthesis, discovery and optional preparation operations. Native embedding and graph models are qualified model@provider identifiers configured inside RAGFlow.

The compatibility installer in deploy/ragflow/knowledge-agent-compat/ targets RAGFlow 0.26.4, Infinity 0.7.4, Infinity SDK 0.7.4, and Thrift 0.24.0 on the tested Python 3.13 / x86_64 image. The engine and client must be upgraded together. The installer checks pinned wheel digests and uses a separate Python directory. It fixes a nested connection-close error during duplicate-folder reconciliation and adds GET /api/v1/datasets/{id}/graph?full=true. The existing bounded graph preview remains unchanged. Complete exports include the trueserve.native-graph.v1 profile and exact node/edge counts. Tests cover folder-child preservation, complete exports beyond preview limits and rejection of another tenant.

Preparation contract

A collection contains revisioned website and uploaded-file sources. Website acquisition enforces HTTPS, DNS-pinned SSRF checks, declared hosts, optional path scope and an explicit crawl limit. Hitting the limit fails an incomplete crawl. Folder upload retains relative filenames. Originals are encrypted in shared asset storage; each build freezes source configuration and metadata.

The canvas supports Sources, Parse, Split, AI transformation, AI enrichment, Metadata, Decision, Fork, Merge, Validate, Native index and Native graph. Every possible path must parse, split and validate after its last mutation before indexing. Conditional routing uses the existing visual workflow rule editor; Decision scope selects a whole document or individual split units. Missing fields do not satisfy negative comparisons. Fork copies input; Merge makes fan-in explicit. Cycles, disconnected outputs and implicit branching fail validation. Graph compilation follows indexing and ends the preparation DAG.

HTML preserves headings, definitions and table headers/spans; Markdown retains headings, tables and fenced text; Word retains paragraphs and table rows; Excel retains sheet names, original row numbers and sparse column positions. PDFs retain page references. Text-poor/scanned pages require an explicitly selected OpenAI vision integration. Unsupported inputs fail rather than silently omit content. PDF table reconstruction and complex Word styling still need broader fixture qualification. Plain text, Markdown and HTML accept UTF-8, or UTF-16 with a byte-order mark. Invalid encodings and binary control bytes fail before indexing. Common raster signatures select OCR even when an upload has a generic content type.

A prepared unit separates searchable text, original evidence, source locators, typed metadata and generated derived fields. Headings accompany source evidence. AI-generated summaries and mappings never replace evidence. Generated supporting quotations must occur in that evidence.

Native RAGFlow 0.26 exposes metadata at document granularity. The adapter writes one prepared unit per synthetic native document, adds one exact chunk, then reads back content and typed metadata. Retries reconcile the same container by stable unit identity. A candidate dataset belongs to one tenant/build. Preparation artifacts are reused only when document identity, operation and effective input hash match, within the same tenant and agent. Model/prompt changes invalidate corresponding dependent artifacts. Parser changes bump the engine cache version. Queued builds also freeze that engine version. An older build that still needs preparation cannot resume under changed parsing semantics; create a new candidate instead. Graph-only recovery can finish an already verified older index without rerunning preparation or mixing generations.

Jobs use four-minute leases, transaction locks and durable checkpoints. Writes recheck job state, lease ownership, expiry and the feature flag. Cancellation revokes the lease; an old worker cannot overwrite a replacement. Index writes are sequential while native concurrency is being qualified. A failed job keeps completed artifacts for Retry. Native graph tasks are polled independently; empty graphs and exports without verified completeness markers block completion. The native completion receipt must report one document and one chunk per indexed unit, with no failed documents: RAGFlow 0.26.4 can otherwise report task progress 1 after partial document failures. The graph's merged source inventory must also match every verified native unit-container identifier, with no missing or substituted documents. Graph-only retries and recovery after an expired worker lease retain the completed index and its evidence identities, recheck the source snapshot, and continue observing the native task. An incomplete completed native task is restarted on retry; native document subgraph checkpoints can be reused. The compatibility overlay keeps those checkpoints separate from combined-graph snapshots, which previously deleted unfinished extraction work. Resumed tasks count all source chunks and recognize documents already present in the persisted graph. Explicit native graph deletion also removes the separate checkpoints. The native profile saves graph merges in groups of up to 32 documents, retaining individual extraction checkpoints. A separate durable journal records an unfinished graph write. Retry replays it before checking persisted source IDs, replacing previous entity/relation rows and committing the graph snapshot last. This prevents a partially inserted graph from being mistaken for a completed merge. Cancellation waits for outstanding database writes before releasing the dataset lock; the native batch-merge timeout defaults to 900 seconds. Completion totals remain available when every document was already merged. Cleanup compares literal stored names against the changed graph, then deletes matching record IDs in bounded groups. Entity names never become full-text query syntax or deeply nested keyword filters. Entity resolution rejects provider failures and missing or duplicate pair judgments instead of reporting them as resolved. Other in-flight candidate batches are cancelled and drained before retry; successful batch checkpoints remain reusable. Graph locks use unique execution tokens and renew every 30 seconds, including while cancellation drains writes. Lost ownership or a failed renewal fails the phase. The job banner distinguishes extraction, checkpoint reuse, record repair, graph merging, entity resolution and community summarization. Native numeric stage markers are not displayed as overall completion percentages.

The worker runs two job slots and an independent refresh scheduler, so waiting for a native graph does not block every evaluation behind it. Set KNOWLEDGE_WORKER_CONCURRENCY from 1 to 4 to change the slot count. This limits concurrent framework jobs; native graph extraction has its own concurrency. Shutdown stops new claims and allows owned jobs to finish.

Query, tests and publication

Preview, evaluation and published query calls share queryKnowledge. Explicit source/date/typed metadata constraints are intersected with the profile before retrieval. Unknown effective dates do not satisfy a requested applicability date. An omitted or empty source-ID list adds no source-ID restriction; nonempty lists restrict the profile. Metadata constraints that match no units return an explicit information gap. Source revisions/enabled state are checked before and after synthesis. Native use_kg does not enforce the requested document filter in 0.26.4, so the adapter retrieves hybrid hits with an authorized document inventory and expands native graph references locally against that inventory. It does not silently fall back when graph retrieval was required. Original evidence, rather than model-generated graph assertions, is passed to synthesis. Citation IDs must refer to returned evidence. Graph links define additional retrieval candidates. Small candidate sets are included whole; larger sets receive a second native hybrid/reranking pass scoped to their authorized document identifiers. The initial hits remain intact and the combined answer window is limited to 50 units. Answers report candidate/selected counts and whether ranking was needed. This is bounded retrieval, not a claim that every connected document is relevant or that all relevant evidence was found. Every selected original evidence unit reaches synthesis without clipping. The shared answer contract asks for a direct answer within the question's scope, with [N] citations and the limiting qualifications of any necessary exception. missingInformation concerns absent facts needed to answer that question; optional follow-up details and explicitly excluded adjustments are not gaps.

Terminology candidates retain source-unit quotations and review state. Each build freezes reviewed mappings. Expansion requires the quoted unit to be present and in scope; editing a mapping does not change a published build.

The case editor and CSV/JSON import support questions, reference answers, required sources/claims, applicability filters and insufficient-evidence expectations. Generated Q&A and transcript discoveries are candidates. Unreviewed cases remain unmeasured. Evaluation freezes the build/query profile and cases, records source recall and model judgments with explanations, and checkpoints each result. The judge receives numbered original evidence and the answer's citations. It checks added claims and their qualifications as well as the required claims; a correct main conclusion does not establish that every added detail is supported. Discovery commits each complete window and its resume marker atomically, including empty windows; invalid source quotations get one bounded regeneration attempt and then fail. A fluent answer or successful index does not establish correctness.

Direct transcript text passes through shared Analytics redaction before job storage. Ready Analytics releases can also provide complete ordered transcripts; windows overlap and retain conversation/turn ranges, including late turns. Conversation and unit bounds are explicit samples. Spoken answers remain observations, never automatically verified labels. Semantic grouping and demand aggregation remain follow-up work.

Publication locks the agent, checks saved configuration/build identity, current sources and native connection, and binds a matching evaluation. By default, all measured reviewed cases must pass and mean required-source recall must meet the configured threshold. The central agent publish path enforces this contract. Publication history records the agent version and immutable build. Restore rechecks current source access and produces a new publication; it cannot revive removed access. Saving, publishing a refreshed build, and restoring history recreate a draft from the current publication when its old draft was deleted. Scheduled refreshes create candidates, never automatically publish them. The candidate change report compares source snapshots, original content hashes and prepared-unit identities, and lists cases/mappings tied to changed sources. It is a dependency report, not semantic approval of a policy change.

API and permissions

All endpoints under /api/knowledge-agents/{agentId} require tenant-scoped Studio authentication. RunAgents permits published queries. Draft previews, inspection, source/config changes, job control, discovery, case/mapping review and publication require ManageAgents plus agent edit access. Native connection changes also require ManageConfiguration. Tenant predicates and composite foreign keys supplement RLS because the service role can bypass it.

Method/path suffix	Operation
GET /	Authorized workspace and current publication
POST /config	Save an authored DAG/query profile with revision check
POST /sources	Create/update a revisioned source
POST /uploads; PUT /upload/{id}	Reserve then stream an encrypted file
POST /builds; GET /builds/{id}	Enqueue build; inspect documents/units/steps
GET /builds/{id}/artifact?nodeId=…&documentId=…	Inspect one preparation artifact
GET /builds/{id}/graph; GET /builds/{id}/impact	Inspect native relations and candidate changes
POST /jobs/{id}	Cancel or retry a job
POST /chat; POST /mcp	Preview/published query; published ask_knowledge MCP tool
POST /cases; POST /cases/import; POST /evaluations; GET /evaluations/{id}	Edit/import/review cases and run/inspect a suite
POST /discovery; POST /terms/{id}	Discover questions/terms and review mappings
POST /publish; POST /rollback	Publish a tested build or restore history
GET/POST /connection	Masked tenant native connection settings

Uploads bypass the proxy's small JSON body buffering while preserving route authentication. File limits are 100 MB; ordinary knowledge JSON bodies are bounded to 4 MB. Cloud/Salesforce acquisition, external destination adapters, full media preparation, semantic demand grouping and large-volume query pagination are not yet qualified capabilities. Follow the delivery plan before advertising them as supported.

Validation

Run npm run test:knowledge and npm run typecheck in apps/ai-manager. deploy/ragflow/knowledge-agent-compat/test_patch.py validates patched upstream source using SQLite and fake graph storage. scripts/knowledge/inspect-corpus.ts checks structural extraction across the 16 public corpus documents without committing third-party originals. Native contract probes and the persistent Public Policy Knowledge Lab exercise the actual tenant connection. Corpus reference questions must be reviewed before reporting answer accuracy.

The native conformance test is an explicit opt-in because it creates an isolated dataset and invokes the configured embedding and graph models. It requires the local development database, an explicit tenant UUID, and that tenant's configured native connection. From apps/ai-manager, run:

bash ../../.devcontainer/scripts/with-env.sh env \
  KNOWLEDGE_NATIVE_TESTS=1 \
  KNOWLEDGE_TEST_TENANT_ID="your-tenant-uuid" \
  node_modules/.bin/tsx --test lib/knowledge-agents/native.integration.test.ts

Optional KNOWLEDGE_TEST_EMBEDDING_MODEL and KNOWLEDGE_TEST_GRAPH_MODEL override the qualified native model identifiers. The test checks exact units, typed metadata, retry identities, scoped retrieval, complete graph export, post-graph chunk retention and deletion of its own dataset. Ordinary test:knowledge runs skip it.

The published MCP endpoint uses normal tenant API tokens with agents:run scope. It resolves the current publication server-side and accepts only a question and narrowing filters. The API guide and generated AI Manager OpenAPI inventory describe the same routes.

Step inspection exposes saved per-document artifacts next to the selected operation. List view includes explicit connection/branch selectors and disconnection controls. Undo history retains the most recent 100 authored changes. Graph inspection resolves native node and relation references back to original evidence excerpts with document/page/row locations. A view is limited to 50 entities, 100 relations and 100 excerpts of 2,000 characters each; missing or clipped support is identified explicitly. Switching builds clears earlier graph, impact, answer and evaluation views.