Knowledge Agent architecture¶

Status: Draft | Last reviewed: 2026-10-09

This proposal defines the runtime, graph, storage, and publication contracts for Knowledge Management Agents. Use it when designing the implementation behind the product proposal; names below describe proposed interfaces.

Identity and availability¶

Register knowledge_management_agents as a subtype in the existing text-to-text group, with a dedicated editor at /agents/{agentId}/knowledge. The group is a Studio classification; this agent does not execute as an ordinary chat or voice pipeline.

Keep identity in agents and authored runtime settings in agent_versions.config. Add a versioned knowledge_management envelope containing the collection binding, preparation graph, query graph, versioned knowledge-model profile, destination bindings, and evaluation policy references. Saved configurations contain credential references, never credential values.

Use FEATURE_KNOWLEDGE_AGENTS, default false, together with the parent Agents capability. Apply the gate to creation, lists, direct reads, duplicate/import, editor routing, management APIs/MCP, tests, publication, and worker claims. Send the server value through StudioFeaturesProvider. A baked NEXT_PUBLIC_* value must not enable this feature.

Enable the flag only in the selected Vanguard runtime configuration. Keep shared templates and other deployments off. Disabling it stops new work and publication; workers finish or checkpoint the current bounded operation before stopping. Re-enabling resumes eligible durable jobs. Gate changes do not delete data.

The existing tenant Knowledge Sources setting continues to govern that connection. Its URL is a source-service endpoint, not necessarily a raw RAGFlow API endpoint. Resolve destination credentials through an explicit tenant integration/native-service binding; do not reinterpret that URL or use host environment credentials as a fallback.

Runtime boundaries¶

Component	Responsibility
ai-manager	Authoring, validation, tenant authorization, run submission, progress, inspection
Knowledge worker	Leased preparation tasks, retries, checkpoints, dependency scheduling
Fixed document processors	Parsing, OCR adapters, structural conversions, splitting
Destination adapters	Capability checks, candidate writes, verification, deletion, retrieval
Native graph integration	Configure, run, inspect, and verify RAGFlow graph/compilation work
Query executor	The same term resolution, retrieval, graph expansion, and synthesis for every consumer
Evaluation executor	Versioned assertions and judges over recorded artifacts and query results

Initially package knowledge-worker alongside ai-manager, as Analytics does. Use fixed Python document processors where appropriate and bounded object-store references between processors. Heavy work runs outside Next.js requests. Extract shared lease, storage, model-binding, and usage helpers behind tested interfaces; do not make the worker depend on private imports from another app.

RAGFlow is the first graph and index engine. The worker submits native operations and records job handles, artifacts, and readiness. Reuse supported extraction, entity resolution, and compilation instead of implementing a second graph engine. Managed stages expose their verified settings and outputs through the provider capability profile.

A later media worker image can carry FFmpeg and other heavy dependencies. Separate worker concurrency for acquisition, document processing, model calls, and media. This is one task protocol with several worker capabilities, not a requirement to introduce a new broker or orchestration platform.

Use PostgreSQL durable work records and transactional enqueueing initially. Queues, retries, and batched mapping are runtime concerns. General LangGraph conversation state is not the storage format for a corpus.

Typed forward-only graphs¶

A graph contains stable node IDs, node kind/version, typed configuration, explicit ports, and edges. Author geometry is separate from the execution specification; selection, measured layout, preview samples, and run status are view state.

Each node manifest declares:

Input/output artifact types and schema versions.
Processing scope: document, section, chunk, batch, or collection.
Cardinality: one-to-one, one-to-many, filter, or explicit aggregation.
Supported model capabilities and optional structured-output schema.
Error behavior, resource bounds, and cache eligibility.
The field descriptions needed by the visual editor and generated JSON Schema.

Representative ports are RawDocument, StructuredDocument, SectionSet, ChunkSet, EnrichedChunkSet, TopicAssignments, TermMappingSet, AssertionSet, and KnowledgeBundle. A run passes artifact references and paginated manifests, not the whole document collection inside node JSON.

Semantic extraction can branch from structured documents and combine with chunk outputs through source anchors. The bundle carries chunks, concepts, mappings, topics, and supported assertions; each destination consumes its declared subset. Knowledge-graph cycles do not relax the processing graph's acyclicity rule.

Validate acyclicity, reachable outputs, port compatibility, required fields, branch coverage, sink ownership, and destination capabilities before execution. Reject a back edge regardless of where the cards are drawn. Structured-output schemas and node contracts are validated before downstream work consumes them.

Decisions and merges¶

Reuse the existing canonical Decision shape: outputs=[{id,label,expression}], with outgoing edge condition=output.id. Keep the visual rule editor, typed field selection, and validated AI-assessment contract. Adapt the evaluation context to a document artifact and its metadata. Credentials remain outside model-visible input.

Node	Semantics
Route	Ordered first match; exactly one ordinary output per input
Fork	Explicitly create distinct derived views of the same input
Merge streams	Union compatible branch outputs, retaining their lineage
Join views	Combine matching parent IDs under an explicit field/conflict policy
Filter	Record an intentional exclusion and its reason
Quarantine	Retain failed input and diagnostics for review/retry

The existing workflow runtime permits unconnected Decision outcomes to end. The knowledge compiler requires each outcome to reach a valid continuation or an explicit exclusion/quarantine terminal, so documents cannot disappear unnoticed. AI refusal/error handling remains explicit; a failed assessment is not a normal classification. Deterministic MIME/structure routing is the default.

A merge understands that an unselected route is complete with zero items; it must not wait forever for work that was never scheduled. A failed selected branch remains a failure. Do not infer a Cartesian join from two incoming edges. Collection-wide operations wait for the frozen input manifest to be complete.

Source and document contracts¶

Keep acquisition and processing ownership distinct:

Pipeline-owned acquisition: enumerate and fetch raw content into a collection snapshot. The TrueServe graph owns subsequent transformations.
Provider-managed source: an existing connector owns acquisition and parsing. Its output is an opaque managed stage or a read-only retrieval target.

An existing RAGFlow connector that starts indexing is not a raw-source API. For editable pipelines, port/extract the crawler's acquisition function and add native bucket/CRM acquisition adapters. Reuse the integration forms and connector configuration, but do not run two ingestion owners over the same dataset.

A source adapter exposes validate, enumerate, fetch, checkpoint, and, where available, changes and readAccess. It advertises capabilities such as incremental cursor, authoritative deletion inventory, stable remote version, and document permissions.

Use source ID plus native object/record ID as document identity. Preserve URLs, folder paths, and display names separately. Record raw content hash, provider version/ETag, fetch time, source metadata, access digest, and acquisition outcome. An ETag is a change hint; do not assume it is a content digest.

Every source contributes a manifest at a declared watermark. A multi-source snapshot is a recorded vector of those watermarks, not a claim of a simultaneous transaction across unrelated systems. Display the oldest source watermark.

Transcript discovery has a separate input binding from the answer corpus. Reference authorized, ready Analytics releases and optional annotation/input snapshots through a narrow complete-turn reader. Reuse normalized/redacted data; direct uploads use shared preparation interfaces under the Knowledge feature gate. The discovery contract pins source membership, filters, sampling, compiler/taxonomy versions, and turn-level evidence.

Discovery runs produce question candidates, occurrence groups, and evidence requirements. Reviewed cases enter the existing evaluation path. Transcript text and observed answers do not become authoritative corpus content through this binding; indexing transcripts is a separate explicit source decision.

Structured documents and chunks¶

Preserve original bytes. Normalize into a versioned document representation that can carry ordered headings, paragraphs, lists, code, tables, figures, and media. Keep parser-native output as a retained artifact when useful for debugging. Do not make Markdown the only source of truth.

Contract field	Meaning
`document_version_id`	Immutable acquired source version
`block_id`, `parent_block_id`	Structural identity inside that version
`source_locator`	Page/bounding box, HTML element, text span, sheet/cell, or media interval
`body`	Extracted source content, with extraction method and confidence when supplied
`derived_fields`	Generated summaries, labels, alternate phrasings, questions
`provenance`	Input artifacts, processor/model/prompt versions, parameters, evidence references
`access_binding`	Trusted source access policy; not an AI-extracted field

For chunks, add chunk_id, parent/neighbor IDs, ordinal, canonical evidence references, evidence_text, retrieval_text, typed metadata, and named representations. Assign immutable IDs within a build. Cross-build comparison uses source anchors/content lineage rather than expecting identical chunk IDs after re-splitting.

Distinguish metadata namespaces:

Source/system: identity, original location, acquisition timestamps, access.
Authored: business labels and approved overrides, with who changed them.
Derived: model-extracted entities, summaries, applicability, confidence.

Define each field's type, null behavior, allowed values, extraction provenance, and uses: filter, display, embedding input, ranking, or citation. Prevent generated fields from overwriting identity or access. Conflicts produce an explicit resolution requirement; missing metadata must not quietly match every filter.

Keep table cells, headers, units, notes, and continuation relationships together. Row-group chunks repeat the appropriate headers and retain a reference to the full table. Generated table explanations supplement the table's evidence.

HTML/Markdown conversion renders the structured representation using a declared conversion profile. Sanitize rendered HTML. Preserve tables and locators in a sidecar when the target format cannot express them; report losses. Arbitrary HTML → Markdown → HTML conversion is not promised to be lossless.

Persistence¶

The table families below are proposed logical responsibilities, not migration files. Native artifact references may satisfy the semantic families; M0 decides the physical schema without requiring a duplicate graph store. Use UUID tenant keys, forced RLS, explicit tenant predicates, and compound ownership constraints for TrueServe records.

Family	Stored data
`knowledge_corpora`, `knowledge_sources`	Reusable identities and authorized connection references
`knowledge_source_snapshots`	Versioned inventory, source watermarks, additions/deletions
`knowledge_documents`, `knowledge_document_versions`	Stable identities and acquired revisions
`knowledge_builds`	Frozen graph/configuration, manifest, status, and budget
`knowledge_work_items`, `knowledge_node_runs`	Leases, attempts, dependency completion, checkpoints
`knowledge_artifacts`, `knowledge_chunk_records`	Artifact references, hashes, schema, lineage, typed chunk catalogue
`knowledge_concepts`, `knowledge_terms`, `knowledge_term_mappings`	Definitions, aliases, scoped mapping/review history
`knowledge_topic_models`, `knowledge_topic_assignments`	Versioned taxonomy, discovered clusters, and evidence-linked membership
`knowledge_assertions`, `knowledge_assertion_evidence`	Native assertion references, source support, review decisions, and retained evidence exports
`knowledge_graph_releases`	Native dataset/artifact/job references, verified graph version, and schema/profile
`knowledge_index_releases`, `knowledge_external_ids`	Destination generation and external document/chunk mappings
`knowledge_publications`	Matching source, terminology, topic, graph/index, agent, and query versions
`knowledge_discovery_runs`	Transcript release/input bindings, extraction profile, sampling, coverage, and checkpoints
`knowledge_question_candidates`, `knowledge_question_occurrences`, `knowledge_question_groups`	Normalized requests, source turn references, reviewed group membership, demand counts, and case links
`knowledge_evaluation_suites`, `knowledge_evaluation_cases`	Versioned questions, policy/scenario tasks, and evidence requirements
`knowledge_evaluation_runs`, `knowledge_evaluation_results`	Pinned experiments, assertions, judgments, and exclusions
`knowledge_sessions`, `knowledge_answers`	Private query traces, retrieved evidence, answers, and citations

Keep bytes and large output manifests in the shared encrypted object store. Use bounded work batches and paginated artifact inspection. Aggregate successful item counters; retain detailed failure records without requiring a UI row or large JSONB record for every token or vector.

Reuse the existing Test UI patterns and scorer lease helpers, but introduce knowledge-specific case/evidence storage and a knowledge executor. Current agent_test_cases queries join conversation simulation attempts and reviews; forcing corpus tests into that model would invent conversations with no purpose.

TrueServe owns source lineage, authored schemas, review history, and publication manifests. RAGFlow owns its native graph representation. Retain sufficient source-linked artifacts for inspection, evaluation, export, and rebuild; avoid mirroring every native node and edge into a second database by default.

Where native artifacts lack required review or evidence fields, test a small sidecar or native extension before introducing another graph engine. Specify which store owns each field and how approved changes reach retrieval. Verify source links, graph readiness, generation scope, and representative queries before activation. A required graph read failure cannot silently select a semantically different query strategy.

The graph contract defines ontology, terminology, validity, and review semantics. The combined native representation and evidence records must retain them; a bare entity-relation graph is insufficient.

Durable execution and cache rules¶

Submit a frozen run after flushing saved authoring changes. Pin graph hash, source snapshot, processor versions, model bindings, prompt hashes, output schemas, ontology/topic/terminology versions, destination profiles, and budget. A draft can run without publication, but subsequent edits cannot change that run.

Claim work with short SKIP LOCKED transactions, lease tokens, expiry, and heartbeats. Perform provider work outside the transaction. Every checkpoint rechecks the lease and run state. A stale worker cannot overwrite newer work or promote a cancelled build.

Expect at-least-once delivery. Use idempotency keys and external-ID reconciliation for writes, including an uncertain timeout after a provider accepted a request. Distinguish retriable failures, permanent format failures, refusals, and budget exhaustion. Cap retries and expansion; retries count against the same budget.

Cache keys include tenant, input artifact hash, node/processor version, configuration, prompt, schema, model binding, policy, and knowledge-model version. Authored changes invalidate the affected node and descendants. A collection aggregate also depends on membership; access changes invalidate relevant serving caches.

Reusing a stored model output is reproducible. Asking a hosted model to regenerate it is not guaranteed to return identical bytes, even at a low temperature. Offer explicit regeneration and retain the resulting attempt as new evidence.

Refresh and publication¶

Acquire source changes into a new snapshot. Reprocess changed documents and affected aggregates, retaining unchanged immutable artifacts. An authoritative completed inventory can establish deletion; a failed crawl, access error, pagination interruption, or missed notification cannot.

Do not move the successful source checkpoint until its manifest is committed. Deduplicate overlapping triggers, serialize/coalesce refreshes per source, and run periodic reconciliation even when notifications or CDC are available. Keep source errors and staleness visible independently of an index's health.

The default first-release policy requires all selected sources and required processing stages to complete. Exclusions must be explicit. If a later policy permits a degraded release, record its omitted documents/sources and quality impact; do not mark silent partial success as complete.

Build candidate vector and native graph artifacts from the same frozen build, verify their contents and query behavior, run the applicable suite, and create an immutable publication record. These are logical versions within the RAGFlow release, not a requirement for two database services. Pin matching terminology/topic/ontology versions. Atomically move TrueServe's active pointer after the required targets pass. A new query configuration can reuse an existing index release after reevaluation.

Start with a separate RAGFlow dataset per candidate generation, including the graph/compilation artifacts required by its query profile. Verify their readiness independently of ordinary parsing. This simplifies isolation but duplicates storage and may repeat embedding work; measure that cost. Large-corpus generation filters, copy-on-write, or provider snapshots are later optimizations that must preserve the same publication contract.

A TrueServe pointer swap only governs TrueServe consumers. External consumers need a destination-specific alias/retriever activation mechanism or a documented manual activation step. Do not promise atomic promotion across independent cloud systems. Track each target's actual activation and rollback state.

New sessions pin a publication. Existing sessions retain it while rechecking current access. Confirmed revocations and deletion deny rules override old snapshots, cached contexts, and rollback. Citation access and replayed history must also respect current authorization.

Retire old provider generations after retained sessions/evaluations no longer need them. Reference-count shared objects. Garbage collection handles abandoned uploads, failed candidates, superseded versions, and provider deletions with auditable outcomes.

Scale and access boundaries¶

Use resumable multipart/direct-to-object-store uploads through an authorized upload session. Validate ownership, expected length, checksums, and finalization before processing. Keep tenant encryption requirements at the storage boundary. Do not route multi-gigabyte folder uploads through a buffered Next.js request.

Stream bucket inventory and large manifests. Batch model calls within declared token limits. Bound file/archive expansion, page/image resolution, chunk fan-out, temporary disk, model concurrency, and total cost. The acceptance workload is defined and measured in the delivery plan, not inferred from an unbounded upload control.

Source content is untrusted data: parser and model instructions cannot grant tools, alter tenant identity, or select arbitrary network destinations. Apply the shared PII policy before model/export boundaries, sandbox parsers, validate crawl redirects and outbound fetches, and sanitize rich previews.

Enforce tenant/source access before retrieval, before external reranking/model calls, and when resolving citations. User filters can narrow trusted policy, never widen it. Reject an adapter for protected content if it cannot implement the required restriction; filtering only after answer generation is insufficient. Derived content combining several sources requires access to every contributing source, or separate derivations per access group.