Knowledge Block

Perform semantic vector search across knowledge bases, upload individual chunks to existing documents, or create new documents from text content. Uses advanced AI embeddings to understand meaning and context for search operations — reach for this block whenever a workflow needs to retrieve, extend, or populate a knowledge base at runtime.

Overview

When to Use

• Retrieve the most relevant document chunks from a knowledge base for a given query (semantic RAG search)
• Filter search results by document tags to narrow retrieval to a specific subset of documents
• Append a new text chunk to an existing document in a knowledge base (incremental ingestion)
• Create a brand-new document from text content produced earlier in the workflow
• Tag documents at creation time so they can be filtered in future search operations
• Ground an Agent block's response in your own proprietary data rather than the model's training knowledge

Configuration

Operation

Selects which action the block performs. Required — defaults to search.

Knowledge Base (all operations)

ID: knowledgeBaseId | Type: knowledge-base-selector | Required: yes

Select the knowledge base to search in, upload a chunk to, or create a document within. Shown for all three operations.

Search Query (operation: search)

ID: query | Type: short-input | Required: no

The text to search for. Optional when tag filters alone are sufficient to retrieve relevant chunks. Accepts {{blockName.field}} references.

Placeholder: Enter your search query (optional when using tag filters)

Number of Results (operation: search)

ID: topK | Type: short-input | Required: no

How many top-matching chunks to return. Must be between 1 and 100. Defaults to 10 when left blank.

Placeholder: Enter number of results (default: 10)

Tag Filters (operation: search)

ID: tagFilters | Type: knowledge-tag-filters | Required: no | Mode: advanced

Add one or more tag name/value pairs to restrict search to documents carrying those tags. Multiple values for the same tag name are combined with OR logic; different tag names are AND-ed together.

Document (operation: upload_chunk)

ID: documentId | Type: document-selector | Required: yes

Select the existing document inside the chosen knowledge base to append the chunk to.

Chunk Content (operation: upload_chunk)

ID: content | Type: long-input | Required: yes

The text content of the chunk to upload. Accepts {{blockName.field}} references.

Placeholder: Enter the chunk content to upload

Document Name (operation: create_document)

ID: name | Type: short-input | Required: yes

Name for the new document. Must be 255 characters or fewer and must not contain < > : " / \ | ? *.

Placeholder: Enter document name

Document Content (operation: create_document)

ID: content | Type: long-input | Required: yes

Full text content of the new document. Maximum size is 1 MB. Accepts {{blockName.field}} references.

Placeholder: Enter the document content

Document Tags (operation: create_document)

ID: documentTags | Type: document-tag-entry | Required: no

Attach metadata tags to the new document. Tags entered here are stored as structured key/value pairs and can later be used as tag filters in search operations.

Inputs & Outputs

Inputs:

• operation (string) — Operation to perform (search, upload_chunk, or create_document)
• knowledgeBaseId (string) — Knowledge base identifier
• query (string) — Search query terms
• topK (number) — Number of results to return
• tagFilters (string) — Tag filter criteria (JSON array of { tagName, tagValue } objects)
• documentId (string) — Document identifier (required for upload_chunk)
• content (string) — Content data (chunk text for upload_chunk; document body for create_document)
• name (string) — Document name (required for create_document)
• documentTags (string) — Document tags as a JSON string of tag objects (used by create_document)

Outputs (produced by the search operation; upload_chunk and create_document return their tool outputs directly):

• results (json) — Search results: array of matched chunks, each with id, content, documentId, chunkIndex, similarity, and metadata
• query (string) — Query used in the search
• totalResults (number) — Total number of results found

Tools

Knowledge Search (knowledge_search) — Sends a POST to /api/knowledge/search with the selected knowledge base ID, query text, topK limit, and optional tag filters. Returns ranked chunks with similarity scores.

Knowledge Upload Chunk (knowledge_upload_chunk) — Appends a new enabled text chunk to an existing document via POST to /api/knowledge/{knowledgeBaseId}/documents/{documentId}/chunks. Returns chunk metadata including id, chunkIndex, contentLength, and tokenCount.

Knowledge Create Document (knowledge_create_document) — Creates a new text document (chunked with a 1024-character chunk size and 200-character overlap) via POST to /api/knowledge/{knowledgeBaseId}/documents. Accepts optional structured tag data to tag the document at creation time. Returns the new document's id, name, and documentId.

YAML Example

# Example 1 — Semantic search with a tag filter
knowledge_1:
  type: knowledge
  name: "Knowledge"
  inputs:
    operation: "search"
    knowledgeBaseId: "{{starter.knowledgeBaseId}}"
    query: "{{starter.userQuestion}}"
    topK: 5
    tagFilters: '[{"tagName":"department","tagValue":"engineering"}]'
  connections:
    outgoing:
      - target: agent_1

# Example 2 — Create a document from workflow-generated content
knowledge_2:
  type: knowledge
  name: "Knowledge"
  inputs:
    operation: "create_document"
    knowledgeBaseId: "{{starter.knowledgeBaseId}}"
    name: "{{agent_1.output}}_summary"
    content: "{{agent_1.output}}"
    documentTags: '[{"tagName":"source","tagValue":"auto-generated"}]'
  connections:
    outgoing:
      - target: response_1