Agentic Assistant and Knowledge Bases

Relevant source files

• src/backend/base/langflow/__main__.py
• src/backend/base/langflow/agentic/utils/assistant_runner.py
• src/backend/base/langflow/agentic/utils/flow_component.py
• src/backend/base/langflow/api/utils/kb_helpers.py
• src/backend/base/langflow/api/v1/flows.py
• src/backend/base/langflow/api/v1/flows_helpers.py
• src/backend/base/langflow/api/v1/folders.py
• src/backend/base/langflow/api/v1/knowledge_bases.py
• src/backend/base/langflow/api/v1/store.py
• src/backend/base/langflow/helpers/folders.py
• src/backend/base/langflow/initial_setup/setup.py
• src/backend/base/langflow/main.py
• src/backend/base/langflow/server.py
• src/backend/base/langflow/services/database/models/flow/guards.py
• src/backend/base/langflow/services/database/service.py
• src/backend/base/langflow/services/settings/base.py
• src/backend/base/langflow/services/utils.py
• src/backend/base/langflow/utils/util.py
• src/backend/tests/conftest.py
• src/backend/tests/integration/components/astra/test_astra_component.py
• src/backend/tests/integration/components/output_parsers/test_output_parser.py
• src/backend/tests/unit/agentic/mcp/test_run_assistant_tool.py
• src/backend/tests/unit/agentic/utils/test_flow_component.py
• src/backend/tests/unit/api/v1/test_flows.py
• src/backend/tests/unit/base/tools/test_component_toolkit.py
• src/backend/tests/unit/components/flow_controls/test_loop.py
• src/backend/tests/unit/components/models_and_agents/test_tool_calling_agent.py
• src/backend/tests/unit/components/vectorstores/test_chroma_vector_store_component.py
• src/backend/tests/unit/initial_setup/starter_projects/test_memory_chatbot.py
• src/backend/tests/unit/initial_setup/starter_projects/test_vector_store_rag.py
• src/backend/tests/unit/services/database/test_migration_advisory_lock.py
• src/backend/tests/unit/test_cli.py
• src/backend/tests/unit/test_database.py
• src/backend/tests/unit/test_initial_setup.py
• src/backend/tests/unit/test_knowledge_bases_api.py
• src/frontend/src/hooks/flows/__tests__/use-save-flow.test.ts
• src/frontend/src/hooks/flows/use-save-flow.ts
• src/frontend/tests/core/features/playground.spec.ts
• src/frontend/tests/core/regression/generalBugs-shard-9.spec.ts
• src/frontend/tests/core/unit/chatInputOutput.spec.ts
• src/frontend/tests/extended/regression/generalBugs-shard-3.spec.ts
• src/lfx/src/lfx/base/vectorstores/chroma_security.py

This section documents the agentic subsystem of Langflow, which provides AI-assisted component generation and flow building capabilities. It also covers the Knowledge Base API, a specialized infrastructure for managing document storage, chunking, and retrieval using Chroma-backed vector stores.

Agentic Assistant Subsystem

Langflow includes an "Agentic Experience" that allows the system to act as an assistant for users. This system is responsible for generating Python code for CustomComponent instances and providing troubleshooting feedback.

Component Generation and Validation

The assistant uses an agentic flow to generate Python code. This process involves iterative validation and retry logic to ensure the generated code is functional within the Langflow environment.

1. Code Generation: The LLM generates the Component class code as a string.
2. Validation: The generated code is evaluated using validate_code src/lfx/src/lfx/custom/validate.py32-34 This function parses the code into an AST to check for syntax errors src/lfx/src/lfx/custom/validate.py38-45 and attempts to resolve imports src/lfx/src/lfx/custom/validate.py52-58
3. Execution Context: Validation occurs within a specialized Langflow execution context that provides common types like Data, Message, and Component src/lfx/src/lfx/custom/validate.py76-110
4. Retry Logic: If validate_code returns errors in the function or imports keys src/lfx/src/lfx/custom/validate.py34 the assistant uses these error messages to refine the code. The frontend tracks these attempts, providing feedback on the generation progress.

Assistant Runner and Component Logic

The AssistantRunner class orchestrates the execution of assistant-related tasks src/backend/base/langflow/agentic/utils/assistant_runner.py12-14 It interfaces with the FlowComponent to manage how generated components are integrated into a user's workspace src/backend/base/langflow/agentic/utils/flow_component.py10-15

Logic Flow: Assistant Component Generation

The following diagram illustrates how natural language prompts are transformed into functional code entities and validated within the backend.

Sources: src/lfx/src/lfx/custom/validate.py32-133 src/backend/base/langflow/agentic/utils/assistant_runner.py12-25 src/backend/base/langflow/agentic/utils/flow_component.py10-40

---

Knowledge Base API

The Knowledge Base (KB) API provides a structured way to manage document storage, indexing, and retrieval. It is primarily backed by ChromaDB for vector storage.

Core Operations

The KB system supports several key operations accessible via the /knowledge_bases router src/backend/base/langflow/api/v1/knowledge_bases.py78:

• Creation: create_knowledge_base initializes a new KB directory and a Chroma collection src/backend/base/langflow/api/v1/knowledge_bases.py246-302 It verifies permissions via _guard_kb_action src/backend/base/langflow/api/v1/knowledge_bases.py95-165
• Ingestion: The KBIngestionHelper processes data into vector stores src/backend/base/langflow/api/utils/kb_helpers.py440-441
• Retrieval: The KnowledgeBaseComponent allows searching and retrieving data from a selected collection src/backend/base/langflow/api/v1/knowledge_bases.py33-48
• Chunk Preview: preview_chunks allows users to test RecursiveCharacterTextSplitter settings before final ingestion src/backend/base/langflow/api/v1/knowledge_bases.py1015-1049
• Deletion: KBStorageHelper.delete_storage handles the teardown of ChromaDB SQLite file locks using exponential backoff and a .kb_deleted sentinel file src/backend/base/langflow/api/utils/kb_helpers.py166-224

Security and Path Validation

To prevent path traversal attacks, the KB API enforces strict containment checks.

• Path Validation: validate_kb_path ensures the requested path is within the allowed knowledge bases directory src/backend/base/langflow/api/utils/kb_helpers.py20-30
• Guard Logic: _guard_kb_action resolves the effective KB owner and ensures the actor has appropriate KnowledgeBaseAction permissions src/backend/base/langflow/api/v1/knowledge_bases.py95-165
• Allowed Roots: Ingestion from folders is restricted by kb_allowed_folder_roots defined in system settings src/backend/base/langflow/api/v1/knowledge_bases.py18-24

Knowledge Base Implementation Architecture

This diagram maps the API requests to the internal helper classes and storage mechanisms.

Sources: src/backend/base/langflow/api/v1/knowledge_bases.py78-302 src/backend/base/langflow/api/utils/kb_helpers.py103-224 src/backend/base/langflow/api/v1/knowledge_bases.py1015-1049

---

Ingestion and Metrics

The ingestion process transforms raw files or dataframes into vectorized chunks.

Ingestion Pipeline

1. Text Splitting: chunk_text_for_ingestion uses RecursiveCharacterTextSplitter to divide text based on chunk_size and chunk_overlap src/backend/base/langflow/api/utils/kb_helpers.py74-100
2. Metadata Persistence: KBAnalysisHelper.get_metadata reads and updates embedding_metadata.json, tracking fields like embedding_provider, embedding_model, and avg_chunk_size src/backend/base/langflow/api/utils/kb_helpers.py270-320
3. Metrics Update: KBAnalysisHelper.update_text_metrics calculates the total word count, character count, and average chunk size across the entire collection src/backend/base/langflow/api/utils/kb_helpers.py340-365

Key Metrics and Constants

The system uses several constants to manage performance and reliability:

• Batch Size: INGESTION_BATCH_SIZE (default 100) controls document batching during ingestion src/backend/base/langflow/api/utils/kb_helpers.py52
• Retries: MAX_RETRY_ATTEMPTS (default 3) and MAX_DELETE_RETRIES (default 5) manage transient failures and file lock issues src/backend/base/langflow/api/utils/kb_helpers.py53-55

Core KB Entities

Class / Function	Role	Source
KBStorageHelper	Manages root paths, directory sizes, and Chroma clients	src/backend/base/langflow/api/utils/kb_helpers.py103-104
KBAnalysisHelper	Detects embedding models and calculates metrics	src/backend/base/langflow/api/utils/kb_helpers.py267-268
KBIngestionHelper	Orchestrates the ingestion of items into backends	src/backend/base/langflow/api/utils/kb_helpers.py440-441
_guard_kb_action	Validates permissions and resolves KB ownership	src/backend/base/langflow/api/v1/knowledge_bases.py95-100

Sources: src/backend/base/langflow/api/v1/knowledge_bases.py1-172 src/backend/base/langflow/api/utils/kb_helpers.py1-441

---

Vector Store Security and Configuration

Langflow enforces security measures for ChromaDB collections to prevent the execution of unsafe server-side embedding functions.

Security Kwargs

The chroma_security.py module provides utility functions to ensure collections are created with disabled server-side embedding functions src/lfx/src/lfx/base/vectorstores/chroma_security.py1-15

• chroma_langchain_collection_kwargs(): Returns a dictionary setting embedding_function to None within the collection_configuration src/lfx/src/lfx/base/vectorstores/chroma_security.py22-24
• chroma_client_create_collection_kwargs(): Similarly disables the embedding function for direct Chroma client calls src/lfx/src/lfx/base/vectorstores/chroma_security.py27-30

Persistent Client Management

To avoid readonly errors on concurrent access, KBStorageHelper.get_fresh_chroma_client clears the SharedSystemClient registry for the specific path before creating a new PersistentClient src/backend/base/langflow/api/utils/kb_helpers.py136-152

Chroma Integration Mapping

This diagram maps the component inputs to the underlying langchain_chroma.Chroma initialization.

Sources: src/lfx/src/lfx/base/vectorstores/chroma_security.py1-30 src/backend/base/langflow/api/utils/kb_helpers.py136-165

---

Starter Projects and RAG Patterns

Langflow includes pre-built starter projects that demonstrate the integration of Agentic Assistants and Knowledge Bases.

Vector Store RAG Starter

The Vector Store RAG starter project illustrates a standard ingestion and retrieval pipeline src/backend/tests/unit/initial_setup/starter_projects/test_vector_store_rag.py73

• Ingestion Graph: Consists of a FileComponent connected to a SplitTextComponent src/backend/tests/unit/initial_setup/starter_projects/test_vector_store_rag.py31-37
• RAG Graph: Connects ChatInput to a Prompt Template, which uses context from a ParserComponent (processing split text) to feed a LanguageModelComponent src/backend/tests/unit/initial_setup/starter_projects/test_vector_store_rag.py41-70

Implementation Details

• File Parsing: The ParserComponent stringifies ingested data for inclusion in prompts src/backend/tests/unit/initial_setup/starter_projects/test_vector_store_rag.py50-51
• Prompt Construction: Prompts are dynamically built using template variables like {context} and {question} src/backend/tests/unit/initial_setup/starter_projects/test_vector_store_rag.py54-61

Sources: src/backend/tests/unit/initial_setup/starter_projects/test_vector_store_rag.py1-173 src/backend/tests/unit/initial_setup/starter_projects/test_memory_chatbot.py1-50