> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge bases and knowledge tools

A Knowledge base is a managed collection of documents and data sources that an agent can search during conversations. Knowledge bases in the Agent Platform serve as the primary retrieval layer for enterprise content, enabling agents to query and access information across heterogeneous data sources. Content can be ingested via file uploads, web crawling, and external connectors, and is indexed to support vector, keyword, and structured retrieval. At query time, the platform applies enterprise search and RAG pipelines to automatically contextualize agent requests—resolving intent, enriching queries, and retrieving relevant chunks. This retrieved context is then made available to agents and tools, allowing them to perform grounded reasoning, execute workflows, and generate accurate, context-aware responses.

## How knowledge bases work

A knowledge base processes content through an ingestion pipeline (index-time) and serves it via a retrieval pipeline (query-time).

### Ingestion process

The ingestion pipeline transforms raw content into retrieval-ready chunks with embeddings and metadata.

```mermaid actions={false} theme={null}
%%{init: {'theme': 'base', 'themeVariables': {'background': 'transparent', 'primaryColor': '#EAF8E4', 'primaryTextColor': '#1a1a1a', 'primaryBorderColor': '#5CC83A', 'lineColor': '#5CC83A', 'secondaryColor': 'transparent', 'tertiaryColor': 'transparent', 'clusterBkg': 'transparent', 'clusterBorder': '#5CC83A', 'titleColor': '#1a1a1a', 'clusterLabelBackground': 'transparent', 'edgeLabelBackground': '#EAF8E4'}}}%%
flowchart LR
    A[Ingest] --> B[Extract]
    B --> C[Chunk]
    C --> D[Enrich]
    D --> E[Embed]
    E --> F[Store]
```

1. **Ingestion**: Registers and tracks content for processing. For uploaded files, the platform checks for duplicates using content hashing, files that have already been indexed with unchanged content are skipped. For connected data sources, the platform discovers and tracks all documents within the source.

2. **Extraction**: The extraction stage pulls content from your source files. Depending on the content format, different extraction strategies are used.

   | Format | Extraction approach |
   | - | - |
   | Plain text, Markdown | Used as-is |
   | HTML | Tags stripped, structure preserved where meaningful |
   | PDF | Text extracted from pages (layout-aware extraction for complex PDFs) |
   | DOCX / Office formats | Document content extracted from the file structure |
   | JSON | Values extracted and concatenated with structural context |

   The extraction stage also captures document metadata (titles, headings, page numbers) that's used later for enrichment and search result context.

3. **Chunking** - The chunking stage splits text into smaller segments that can be individually embedded and retrieved. The chunking strategy you choose directly affects search quality — it determines how coherent and complete each retrievable unit of content is. The platform supports three chunking strategies:

   | Strategy | How it splits | Best for |
   | - | - | - |
   | Fixed-size | Token windows of a configurable size with overlap between chunks | Predictable, uniform content where consistency matters |
   | Semantic | Natural boundaries such as paragraphs, sections, and topic shifts | Narrative or long-form content where coherence is important |
   | Sliding window | Overlapping windows that slide across the full text | Content where context continuity across boundaries is critical |

   > [!NOTE]
   >
   > Chunk overlap ensures that context at chunk boundaries is not lost. A concept that spans two paragraphs will appear in both chunks when overlap is configured. Always configure overlap when your content spans section boundaries.

4. **Enrich**: The enrichment stage adds metadata to each chunk, improving search quality and enabling filtering. The following enrichments are applied:

   | Enrichment | What it adds |
   | - | - |
   | Entity detection | Identifies emails, URLs, dates, and monetary values within the chunk |
   | Summary generation | Creates a brief summary of the chunk's content |
   | Language detection | Identifies the language of the content |
   | Knowledge graph extraction | Extracts entities and relationships to build a knowledge graph. This feature is available on request. |

   Enrichment metadata is stored alongside each chunk and can be used to filter and rank search results at query time.

5. **Embedding Generation**: The embedding stage converts each text chunk into a vector representation that captures its semantic meaning. These vectors enable semantic search — finding content that's conceptually related to a query even when the exact words differ.

6. **Store**: The final stage writes the processed chunks to the vector database for fast retrieval. Each stored chunk includes:

   * The original text content
   * The vector embedding
   * Enrichment metadata
   * Source information — document ID, source ID, and page number
   * Permission metadata for access control

   After a chunk is stored, it's immediately available for search.

### Retrieval process

When an agent needs information from a knowledge base, the platform executes a search query and returns the most relevant chunks as context for the agent to compose a response. The search pipeline runs in the following sequence:

1. The agent sends the query to the runtime.
2. Runtime embeds the query text into a vector representation.
3. Hybrid search runs - semantic and keyword search execute simultaneously.
4. Results from both strategies are merged.
5. Merged results are re-ranked by relevance.
6. Permission filters are applied to the re-ranked results.
7. Filtered, ranked chunks are returned to the agent as context.
8. The agent uses the context to compose a response.

![Retrieval Process](https://mintcdn.com/koreai/pdyel7KzGgeDz37v/agent-platform/images/knowledge/retrieval-process.png?fit=max\&auto=format\&n=pdyel7KzGgeDz37v\&q=85\&s=8daf43818e4de81742b7930a90376a6e)

#### Key concepts

1. **Hybrid Search**: The platform uses hybrid search by default, combining two complementary strategies to maximize retrieval quality.

   * **Semantic Search** : Semantic search finds chunks whose vector embeddings are most similar to the query embedding. This helps retrieve conceptually relevant content even when the user's phrasing does not directly match the source text.

     Example:
     A query for "How do I get my money back?" can match a chunk about "Refund policy and procedures" even though none of the query words appear in the chunk heading.

     Use semantic search when users are likely to phrase queries in natural language that differs from the terminology used in the source content.

   * **Keyword Search**: Keyword search finds chunks containing the exact terms in the query. This helps retrieve content with specific names, product codes, technical terms, or identifiers that semantic search might miss due to low vector similarity.

     Use keyword search when the content contains precise terms — such as model numbers, error codes, or proper nouns — that must match exactly.

   Hybrid search merges and re-ranks results from semantic and keyword search to produce a single ranked list of the most relevant chunks.

2. **Re-Ranking**

   After the initial search, results are re-ranked to improve relevance ordering. Re-ranking evaluates the merged result set and adjusts the order based on relevance signals beyond initial similarity scores.

3. **Permission Aware Search**

Search results are filtered based on the requesting user's permissions before they're returned to the agent. If your knowledge base is connected to a data source with access controls, such as SharePoint or other enterprise connectors, only documents the user has permission to see are included in the results.

> [!NOTE]
>
> Permission filtering happens after re-ranking. The agent only receives chunks the requesting user is authorized to access, regardless of their relevance score. This means result counts may vary between users querying the same knowledge base with the same query.

## Adding knowledge base

Knowledge bases are created and managed at the project level and are available to all agents within that project. Every knowledge base in the project is automatically exposed as a tool that any agent can attach to and use.

To create a knowledge base:

* Navigate to **Knowledge Bases** in the left sidebar.

* Click **+ New Knowledge Base**.

* Enter a name and description.

  * Name: used to identify the knowledge base across the project.
  * Description: helps agents identify when to use this knowledge base as a tool. Write this clearly and specifically.

* Click **Create**.

The knowledge base is created with default configurations applied. You can review and update these configurations at any time from the knowledge base dashboard.

### Adding data sources

A knowledge base can ingest content from multiple source types simultaneously. Each source is managed independently, and you can add, sync, and remove sources without affecting others.

When you add a data source to the knowledge base, the platform immediately begins processing it in the background. You don't have to perform any other steps to trigger ingestion or indexing.

To add a data source, follow these steps:

* Go to the **Sources** and select **+ Add Data Source**.
* Select the source connector and select **Connect**.
* Provide configuration details for the source.

#### File uploads

Upload files directly from your local system. The intelligence pipeline immediately processes the uploaded files. If a source file changes, re-upload it.

* Supported file types: PDF, DOCX, TXT, CSV, MD, XLSX, JSON, HTML.
* Maximum file size: 100 MB per file
* Maximum batch size: 40 files per upload.

> [!NOTE]
>
> If the source file changes, you need to re-upload it.

**Metadata Fields**

While uploading a file, you can tag the upload with file metadata:

* **Essential Fields** - the most commonly used fields like Author, Category, Tags, Department.
* **More Fields** - a list of additional fields covering document metadata such as Title, Content Summary, Language.
* **Advanced (custom JSON)** — add custom fields not covered by the standard list, as JSON, for example, `{"custom_string_1": "value", "custom_number_1": 42}`.

> [!NOTE]
>
> Fields filled in during upload become searchable. Only filled fields create vocabulary entries for natural language queries — empty fields are not indexed.

Click **Upload** to start ingestion. The uploaded content is automatically indexed after the ingestion completes.

#### Web crawl

Crawl and index web pages from any public or authenticated website.

Navigate to **Sources** > **Add Source** > **Web Crawler** to manage web sources.

* Provide the domain URL.
* Enter auth details, if required.
* Select Discovery method.
  * Crawl Full Sitemap: Discovers the sitemap and retrieves the list of URLs to be crawled.
  * Guided Discovery: Guide the system to identify pages based on a given URL pattern.
  * Direct URLs: Directly provide URLs to crawl.
* From the list of the discovered URLs, select the URls to crawl.
* Configure the web crawl settings.
* Start Crawl.

**Web Crawl Settings**

**How much should we crawl?** : Choose how many pages to crawl in a single run.

**Crawl Strategy**

* **Rendering** controls how pages are processed before content is extracted. **Standard** option fetches the raw HTTP response only. It's the fastest option, but doesn't capture content that's rendered client-side (for example, React/Vue apps, JS-loaded sections). Best for static HTML sites. **Full rendering** loads the page in a headless browser and executes JavaScript before extracting content, capturing dynamic content like expandable sections, tabs, and client-rendered text. Slower and more resource-intensive, but necessary for JavaScript-heavy sites. **Auto** allows the system to automatically choose per page whether a lightweight HTTP fetch or full browser rendering is needed, based on page characteristics.
* **Learned patterns** determines whether the crawler reuses extraction patterns from previous crawl runs. Set to **Keep** by default, which reuses known page layouts and skips the AI layout detection step — making repeat crawls faster. Select **Reset** after a site redesign or template change so the crawler re-learns the new structure from scratch.
* **Crawl Speed** controls the delay between page requests. Default value is 200 ms. Faster speeds can trigger rate limits on external sites.

**Limits**

* **Max pages** caps the number of pages fetched in a batch. The default is 1,000 per batch.
* **Max depth** controls how many link-hops from the seed URL the crawler will follow. Default: 5, Range: 1-20.
* **robots.txt** honors crawler directives in robots.txt.

**Content Processing**

* **Extraction quality** controls how aggressively the crawler cleans and filters page content during extraction. Default value is **Balanced**.

  | Option | Description |
  | - | - |
  | Thorough | Keeps more content from each page. |
  | Balanced | Default quality and completeness for most sites. |
  | Minimal | Aggressively strips noise. |
  | Custom | Fine-tune quality gate and content preservation thresholds manually. |

  **Custom thresholds**

  | Field | Description |
  | - | - |
  | Quality gate | Minimum quality score required to accept extracted content, on a 0–1 scale (default 0.5). Lower values are more permissive — more content is accepted even if extraction confidence is lower. |
  | Content preservation | How much of the original content to keep when cleaning, on a 0–1 scale (default 0.3). Lower values clean more aggressively, stripping more content. |

* **Duplicate content** - Controls how pages with identical content at different URLs are handled. Options: **Deduplicate** (default) or **Keep all**.

- **Cookie consent** - Rejects or closes cookie popups before extraction; never accepts tracking. Options: **Auto-dismiss** (default) or **Ignore**.

**Scheduled Crawl**

Use this option to automatically recrawl the configured website at a specified date and time. Scheduled crawls help keep indexed content up to date without requiring manual execution.

To configure a scheduled crawl:

* Enable the Scheduled Crawl toggle.

* Specify the following settings:

  | Field | Description | |
  | - | - | - |
  | **Date** | Select the date on which the scheduled crawl should begin. | |
  | **Time** | Specify the time when the crawl should start. | |
  | **Timezone** | Select the timezone in which the scheduled crawl should run. | |
  | **Repeat** | Specify how often the crawl should run. Select **Run Once** to execute the crawl only once, or choose a recurring schedule to automatically recrawl the website at the configured interval (if supported). | run. Select Run Once to execute the crawl only once, or choose a recurring schedule to automatically recrawl the website at the configured interval (if supported). |

* Click **Save** to save the schedule.

> [!NOTE]
>
> This configuration is available only after the initial sync is successful. Go to the source, click **Reconfigure Crawl Strategy** and then click on **Configure** to view the scheduler.

**Extraction Preview** shows samples of what will be extracted from each section using the current configuration before the full crawl runs.

**Recrawl the entire source**

Click **Recrawl** at the bottom of the page to start a new crawl for the entire source. Recrawl submits all source URLs for crawling, irrespective of earlier crawl results.

Use Recrawl when you want to:

* Crawl all pages again after making significant changes to the source.
* Refresh the indexed content for the entire source.
* Re-run the crawl for a historical crawl job.

**Retry failed pages**

Use **Retry** when you want to crawl only specific failed or timed-out pages instead of running the entire crawl again.

You can retry failed pages from the **Crawl Status** section under **Content** tab for the source. Locate the relevant error group (for example, Duplicate Content or Timeout or Error) and click Retry. This resubmits only the URLs in that error group. Expand the group to view the affected URLs before retrying.

> [!NOTE]
>
> A targeted retry submits only the selected page URLs. Successfully crawled pages are not crawled again.

#### Connectors

Pre-built integrations for third-party applications. Navigate to **Sources** > **Add Source** to configure integrations.

**Connector Setup Workflow**

For each connector,

1. Authentication — Provide OAuth credentials, API keys, or tokens to enable connection with the third party application.
2. Ingestion — Select content types and apply filters.
3. Field Mapping — Align source fields with the inbuilt schema. Map custom fields, if required.
4. Permissions — Configure security settings to enable authorized access to information from the third-party applications.

**Enabling/Disabling permissions**

When permission-aware ACL is disabled, all content ingested through a connector is indexed as accessible to all users as no document-level permissions are stored.

Enabling permission-aware ACL does not automatically update permissions for previously indexed content. The connector continues to use the existing permission information until a permission synchronization is performed.

A permission synchronization is triggered only in the following scenarios:

* Manually perform a full content synchronization. Incremental or delta synchronizations do not trigger a permission sync.
* A scheduled permission synchronization run. During a permission synchronization, the connector does not re-ingest content. It retrieves the latest permissions from the source system and applies them to the documents that are already indexed.

> [!NOTE]
>
> Until a permission synchronization completes after enabling permission aware ACL, content indexed while ACL was disabled remains accessible to all users.

**Field Mapping**

When Artemis ingests content, it automatically maps each field in the source (the raw field) to an internal field, which determines how the value is stored and indexed. **After the dry run** and before you **approve and start** indexing, **Review field mapping** lets you check these mappings and change them. This step appears for every connector.

Mappings matter most when you search across several connectors. Different sources name the same information differently, such as `LastModifiedDate` in one and `updated_at` in another. If both map to `Modified Date`, filters, sorting, and search work the same across all sources. Other common cases are:

A source's `Owner` and another's `Assignee`, both may be mapped to `Assignee`.
A source's `PublishStatus` and another's `state`, both may be mapped to `Status`.
A source's `Url` and another's `link`, both may be mapped to `Source URL`.

**To review and update field mappings during initial setup**

After the **dry run completes**, click **Review field mapping**.

* Mappings are scoped per source and object type, so you review each type separately. Each type shows its raw field count and number of suggestions.
* Review each row. To change a mapping, select a different field in `Map to available field`.
* To skip a field, uncheck it.
* (Optional) Click Suggest mappings to have Artemis suggest mappings for fields that aren't mapped.
* Status indicates whether the mapping is accepted or only suggested by the platform.
* Select `Embed` to use the field for embedding generation.

Click Save mappings, followed by **Approve & start** to begin indexing.

**Monitor and manage connector**

After the initial synchronization, you can monitor the connector's health, review failed documents, retry failed processing, and configure scheduled synchronizations.

**View connector status**: Open the connector to view its **Overview** page. It shows:

* Current connector status
* Last synchronization time
* Number of processed and failed documents
* Configured connector objects
* Recent synchronization activity

If any documents fail during synchronization, the connector displays a **Needs attention** notification with the number of failed documents.

To review the failures, click **View failures**. Select a failed document to view its processing details, including the failure reason and the pipeline stage where processing stopped. If the underlying issue has been resolved, click **Retry** to reprocess only the selected document.

> [!NOTE]
>
> Retrying a document reprocesses only that document. It does not resynchronize or reprocess the entire connector.

**View synchronization activity**: The Activity tab shows the history of connector synchronization runs, including the sync status, duration, and processing statistics. Select a run to view additional details and any associated failures.

**Manage field mappings**: Use the Field Mapping tab to review and customize how connector fields are mapped to your knowledge base schema. The available object types and fields vary by connector.

**Update connector settings**: Use the Settings tab to modify connector-specific configuration, such as content scope, filters, scheduling, permissions, and other supported options. Available settings vary by connector, and some options are available only after the initial synchronization.

**Schedule automatic synchronizations**

After the connector completes its initial synchronization, you can configure **automatic content synchronization** from the **Settings** tab under **Schedule and sync**.

> [!NOTE]
>
> This schedule applies only to **content synchronization**. Permission synchronization can be configured separately under **RACL (Permission-aware search)**.

Configure the following options:

| Option | Description |
| - | - |
| **Schedule** | Select how often the connector synchronizes content, such as hourly, daily, or weekly. |
| **Start time** | Specify when the scheduled content synchronization begins. |
| **Day of week** | For weekly schedules, select the day on which the synchronization runs. |
| **Timezone** | Select the timezone used for the scheduled start time. |
| **Recrawl permissions after saving** | Runs a permission synchronization after saving configuration changes to keep document permissions up to date. |
| **Allow this sync to remove most of the indexed documents** | Allows a scheduled content sync to remove a large number of indexed documents when the connector scope has been intentionally reduced, such as after excluding sites, libraries, or folders. This safeguard helps prevent accidental large-scale deletions. |

**Configure permission synchronization (RACL)**: If Permission-aware search is enabled, you can configure a separate schedule for synchronizing document permissions. This keeps search permissions up to date independently of content synchronization.

| Option | Description |
| - | - |
| **Scheduled permission sync** | Enables automatic synchronization of document permissions independently of content synchronization. |
| **Sync frequency** | Specifies how often document permissions are synchronized to keep search access permissions up to date. |

**Available Connectors**

| Connector | Description |
| - | - |
| Aha! | Index ideas, features, and roadmaps from Aha! |
| Airtable | Index spreadsheets and databases from Airtable bases |
| Amazon S3 Connector | Index files from S3 buckets |
| Asana | Index tasks and projects from Asana |
| [Axero](https://koreai.mintlify.site/agent-platform/connectors/axero) | Index Axero spaces, articles, blogs, wikis, files, announcements, and comments |
| Azure Blob Storage | Index blobs from Azure Blob Storage containers |
| Bitbucket | Index repository metadata, pull requests, comments, and commit timelines |
| Bigtincan | Index training courses and content from Bigtincan |
| [Box Connector](https://koreai.mintlify.site/agent-platform/connectors/box) | Index files and folders from Box cloud storage |
| ClickUp | Index tasks and spaces from ClickUp |
| Coda | Index docs and tables from Coda |
| [Confluence Cloud Connector](https://koreai.mintlify.site/agent-platform/connectors/confluence) | Index Cloud spaces, pages, blogs, attachments, comments, and tables |
| [Confluence Server](https://koreai.mintlify.site/agent-platform/connectors/confluence-server) | Index Server spaces, pages, blogs, attachments, and comments |
| Datadog | Index metrics, dashboards, and monitors from Datadog |
| Discord | Index messages from Discord servers and channels |
| DotCMS | Index content and pages from DotCMS |
| Dropbox | Index files and folders from Dropbox |
| Dynamics 365 | Index entities and records from Microsoft Dynamics 365 |
| Egnyte | Index files and folders from Egnyte cloud storage |
| [FAQ](https://koreai.mintlify.site/agent-platform/connectors/faq) | Index FAQs from files or ingest them manually. |
| Figma | Index design files and components from Figma |
| File Upload | |
| Freshdesk | Index tickets and knowledge base from FreshDesk |
| [Freshservice](https://koreai.mintlify.site/agent-platform/connectors/freshservice) | Index solution articles from Freshservice |
| Front | Index knowledge base articles from Front |
| GitBook | Index documentation from GitBook spaces |
| GitHub | Index repositories, issues, and wikis from GitHub |
| GitLab | Index repositories, issues, and wikis from GitLab |
| Gmail | Index emails and attachments from Gmail |
| Google Chat | Index messages from Google Chat spaces |
| Google Cloud Storage | Index objects from Google Cloud Storage buckets |
| Google Docs | Index documents from Google Docs |
| [Google Drive Connector](https://koreai.mintlify.site/agent-platform/connectors/googledrive) | Index files and folders from Google Drive |
| Guru | Index knowledge cards and collections from Guru |
| Help Scout | Index docs, articles, and conversations from HelpScout |
| Hive | Index projects, tasks, and actions from Hive |
| HubSpot | Index contacts, deals, and knowledge base from HubSpot |
| Intercom | Index conversations and articles from Intercom |
| Invision Community | Index forums, articles, and discussions from Invision Community |
| JFrog Artifactory | Index artifacts and repositories from JFrog Artifactory |
| Jenkins | Index build jobs, pipelines, and logs from Jenkins |
| [Jira Connector](https://koreai.mintlify.site/agent-platform/connectors/jira) | Index Jira Cloud issues, comments, worklogs, and attachments |
| Jira Data Center | Index Jira Data Center or Server issues, comments, worklogs, and attachments |
| [Custom Connector](https://koreai.mintlify.site/agent-platform/connectors/custom-connector) | Index structured data from JSON endpoints and files |
| Linear | Index issues and projects from Linear |
| LumApps | Index content and communities from LumApps intranet |
| Microsoft Teams | Index messages and files from Microsoft Teams channels |
| Microsoft Word Online | Index documents from Microsoft Word Online |
| Miro | Index boards and content from Miro whiteboards |
| Monday.com | Index boards and items from Monday.com |
| Notion | Index pages and databases from Notion workspaces |
| OneDrive | Index files and folders from Microsoft OneDrive |
| Opsgenie | Index alerts, incidents, and on-call schedules from Opsgenie |
| Oracle Knowledge | Index records and knowledge articles from Oracle applications |
| PagerDuty | Index incidents and services from PagerDuty |
| Pipedrive | Index deals, contacts, and activities from Pipedrive |
| Quip | Index documents and spreadsheets from Quip |
| ReadMe | Index API documentation from ReadMe |
| Re:amaze | Index conversations and knowledge base from Re:amaze |
| Rich Media | Upload and index images, audio, and video files |
| RSS Feed | Index articles and content from RSS feeds |
| SAP | Index records and documents from SAP systems |
| [Salesforce Connector](https://koreai.mintlify.site/agent-platform/connectors/salesforce) | Index Salesforce Knowledge, cases, CRM records, attachments, comments, and custom objects with native ACL sync |
| [ServiceNow Connector](https://koreai.mintlify.site/agent-platform/connectors/servicenow) | Index knowledge articles, tasks, attachments, comments, and ACL-aware records |
| [SharePoint Connector](https://koreai.mintlify.site/agent-platform/connectors/sharepoint) | Index sites, libraries, and documents from Microsoft SharePoint |
| Shortcut | Index stories, epics, and iterations from Shortcut |
| Shopify | Index products, orders, and content from Shopify stores |
| Slab | Index posts and topics from Slab knowledge base |
| Slack | Index messages and files from Slack channels |
| Slite | Index notes and documents from Slite |
| Sitemap | Discover and index pages from XML sitemaps |
| Stack Overflow for Teams | Index questions and answers from Stack Overflow for Teams |
| Swagger / OpenAPI | Index API specifications from Swagger and OpenAPI definitions |
| Teamwork | Index projects, tasks, and milestones from Teamwork |
| TestRail | Index test cases, runs, and plans from TestRail |
| Trello | Index boards and cards from Trello |
| Vimeo | Index video transcripts and metadata from Vimeo |
| Wolken Service Desk | Index tickets and knowledge articles from Wolken Service Desk |
| Workday | Index employee records and documents from Workday |
| WordPress | Index posts, pages, and content from WordPress sites |
| Wrike | Index projects, tasks, and folders from Wrike |
| xMatters | Index incidents, on-call schedules, and workflows from xMatters |
| YouTrack | Index issues and projects from JetBrains YouTrack |
| YouTube | Index video transcripts and metadata from YouTube |
| [Zendesk Connector](https://koreai.mintlify.site/agent-platform/connectors/zendesk) | Index tickets, Help Center articles, and comments from Zendesk |
| Zeplin | Index design specs and styleguides from Zeplin |
| Zoho CRM | Index leads, contacts, and records from Zoho CRM |
| Zoom | Index meeting transcripts and recordings from Zoom |
| Zulip | Index messages and topics from Zulip chat streams |

### View ingested content

To view the ingested content, follow these steps:

1. Go to the **Documents** page.
2. The ingested documents are listed. Click on any document to view the extracted content and the related metadata. Following details of the document are shown.

* Metadata - Provides general information about the document like type, language, size, page count.

* Extraction Quality - Provides metrics that help evaluate the quality of content extraction.

  | Metric | Description |
  | - | - |
  | Overall | Overall extraction quality score. |
  | Noise Reduction | Effectiveness of removing irrelevant content. |
  | Content Preservation | Degree to which original content is retained. |
  | Structure Preservation | Accuracy of preserving headings, sections, and document structure. |
  | Metadata Extraction | Quality of metadata extraction from the source document. |

* Extraction Report - Shows the extraction configuration used for the document. Use Re-extract to rerun document extraction if extraction settings have changed, metadata needs to be regenerated or extraction quality needs improvement.

* Content Analysis - Displays attributes identified during content processing like detected language.

* Processing Pipeline - Series of steps through which the document is processed. Also indicates the current status of each step. A document is available for retrieval only after all processing stages are successfully completed.

* Source Info - Details of the source of the document.

* Raw Metadata - Document metadata in JSON format.

3. You can reprocess a given document to ingest, extract and index it again. By default, it uses the **Extraction quality** configuration for the source. Use the **Extraction Preset** option to change the config for a given document.

4. Use the Delete button to delete a single page from the source. If you synchronize the source again, the deleted document is ingested again. To prevent repeat ingestion, explicitly add the deleted document to the exclude list.

### View extracted chunks

1. Navigate to **Chunks** page.
2. Click on a document to see the chunks extracted from the document.
3. See token distribution across chunks from the document.

### Configure content processing pipeline

By default, the platform creates a default pipeline for processing of the ingested content automatically to make it searchable.

The default pipeline consists of the following stages. You can reconfigure any stage as required. Alternatively, you can add a new flow to the pipeline for custom configurations.

**Extraction**: Extracts raw text and structure from ingested files and connected sources. The extraction strategy varies by file type, for example, tables in spreadsheets are extracted differently from paragraphs in a PDF. Configure extraction settings to control how the platform interprets your content structure.

**Chunking**: Splits extracted content into smaller segments for indexing. Chunk size and overlap affect search quality; smaller chunks return more precise results while larger chunks retain more surrounding context. Configure the chunking strategy based on the nature of your content and how users are likely to query it.

**Content Intelligence**: Enriches chunks with additional metadata, such as topic tags, summaries, or classifications, to improve search relevance. Configure what enrichment is applied to your content at this stage.

**Visual Analysis**: Processes visual content in ingested files, such as images, diagrams, and charts, and extracts text or descriptions for inclusion in the index. Enable this stage when your content contains visual elements that carry meaningful information.

**Embedding Fields**: Defines which fields from the extracted and enriched content are included in the embedding. Controlling embedding fields lets you tune what the vector search considers when matching a query to a chunk.

**Embedding**: Converts the selected fields into vector representations using the configured embedding model. The choice of embedding model affects the quality of semantic search results. Configure the model here based on your language and domain requirements.

**Opensearch**: At this stage, the processed and embedded chunks are written to the index using their embeddings. You can run test queries to see what is currently indexed and verify search quality as content is added.

> [!NOTE]
>
> The pipeline runs in sequence. A change to an upstream stage, such as chunking, affects all downstream stages. Re-indexing is required when pipeline configuration changes are saved.

#### Adding a Pipeline Stage

Click **+** at any connection point in the pipeline canvas to insert a new stage. There are two categories of stages that can be added to a pipeline. Add a stage and select it for configuration.

**Pipeline Stages** — content-processing stages that run as part of the core ingestion flow.

| Stage | Description |
| - | - |
| Chunking | Splits content into smaller chunks. |
| Content Intelligence | Adds summarization, question synthesis, and document-level intelligence. |
| Visual Analysis | Analyzes images, tables, charts, and screenshots using a multimodal LLM. |
| Enrichment | Enriches chunks with LLM-generated metadata. |

**Utility Stages**

Utility stages add custom processing to a pipeline. You can insert them at different points and use more than one. Their position matters: each stage receives the data available at its configured point, and later stages receive its output.

| Stage | What it does | What to consider |
| - | - | - |
| Field Mapping | Applies configured conditions to set target fields, such as canonical metadata fields. | Choose conditions and target fields that match the data available at this point in the pipeline. |
| API Call | Sends the current document content and metadata to an external HTTP API for processing. | Configure the endpoint and authentication. Production endpoints must use HTTPS. Calls have a timeout and can be retried; the service must return a successful response for processing to continue. |
| LLM | Runs a prompt against document or chunk content and can replace the content, add the response as metadata, or do both. | Configure the prompt and an available model. LLM calls add processing time and may incur model usage costs. |
| Transform Script | Runs JavaScript to update content, metadata, or canonical metadata. | Scripts run in a sandbox with no network access or Node.js globals, and are subject to execution and size limits. Choose the pipeline phase carefully: some phases operate on the whole document, while later phases operate on individual chunks. |

> [!NOTE]
>
> Utility stages can be inserted at different points, but they don’t all run against the same input. For example, a stage configured before extraction receives document input; a stage after chunking can run on individual chunks. Place each stage where the required input exists and where downstream stages can use its output.

##### Field Mapping

Configure one or more rules to map or transform fields during processing. Each rule is independently set to one of two modes, so a single stage can mix Visual and CEL rules as needed.

* **Visual mode** — Build a rule using an IF/THEN structure: IF a selected field meets a condition (equals, and so on) against a value, THEN set a target field to a new value. The source (`Select field...`) and target (`Select target field...`) dropdowns list the indexed fields available from your source documents.
* **CEL mode** — Write a CEL expression that evaluates directly to the target value, for example, `document.source_type == 'pdf' ? 'document' : 'other'`.

Click **Add Rule** to add additional rules — each can independently use Visual or CEL mode; rules run in order.

##### API Call

Calls an external HTTP endpoint during processing.

| Field | Description |
| - | - |
| Provider | The API provider type. Select **Custom API** to call any external HTTP endpoint. |
| Endpoint URL | The URL the platform sends requests to, for example, `https://api.example.com/extract`. |
| HTTP Method | The HTTP method used for the request, for example, `POST`. |
| Pipeline Mode | Controls how the API response is applied to the pipeline. **Replacement** replaces the stage output with the API response. **Transformer** modifies data in place. **Source** provides input. |
| Output Type | The expected format of the API response. It can be `Text`, `Pages`, `Chunks`, `Document` and `Enriched Chunks`. |
| Entry Point | Determines when the API is called during document processing. |

* **Auth & Headers** — Configure authentication (for example, API key, bearer token, basic auth) and custom request headers sent with each call.
* **Behavior** — Configure request behavior such as timeout duration, retry attempts, and error handling.
* **Test** — Send a test request using sample data to validate the results of the .

##### LLM

Enriches content with a large language model call.

| Field | Description |
| - | - |
| Model | The model used to run the prompt, for example, Auto-select fast model. |
| Prompt Template | The prompt sent to the model. Click any available field chip (Title, Content Summary, Source Type, Source URL, Created Date, Modified Date, Author, Language, Status, Category, Description, Tags, Priority, Assignee, Department, Project) to insert its value into the template. |
| Output | Where the model's response is written, for example, **Save to metadata**. |
| Output Field | The target field the output is saved to. |
| Advanced | Additional configuration options (collapsed by default). |

##### Custom Script

Runs sandboxed JavaScript to transform document content and metadata.

> [!NOTE]
>
> Custom Script runs for document files (PDF, DOCX, text, HTML, web pages). It does not run for JSON, CSV, or Excel uploads. Use a structured-ingestion path for JSON, CSV, or Excel content formats.

| Field | Description |
| - | - |
| Run at Phase | When the script runs during processing, for example, **After Extraction (whole document text)** — runs once per document, after extraction, with `content` set to the full extracted text (markdown for PDF/DOCX). Best place to clean or normalize whole-document text. |
| Transform Script | A `transform(content, metadata)` function to make changes to the input. Use `return { content?, metadata? }` to update content or metadata or both. The script runs once per chunk/document; you can add your own helper functions and call them from `transform()`. |

Content changes made by the script are embedded and searchable. Metadata changes are stored on the chunk/document but are not searchable (canonical) fields yet. Provide sample content and **Run on sample** to test the script behavior.

Each Utility Stage also supports an optional **Execution Condition** — a CEL expression that, when set, limits the stage to run only if the expression evaluates to `true`. Click **Apply** to save a stage's configuration, or **Reset** to discard changes.

### Field Intelligence

Manage indexed fields and how agents can use them in search.

**Summary** — Dashboard of field health: active field count, indexed records, connected sources, open warnings, and quick links to review fields/capabilities.
**Fields** — Full inventory of mapped fields, each showing its data type, storage field name, and which search capabilities (Answer, Semantic, Filter, Sort, Aggregate) are enabled on it.
**Capabilities** — Review and assign fields to each search capability (Answer, Semantic, Filter, Sort, Aggregate).
**Agent View** — Read-only view of what's exposed to agents: coverage %, a confidence breakdown per capability, and the field labels/keys agents can discover.

### Configure vocabulary

Vocabulary lets you define aliases for terms that appear in your knowledge base content. When a user queries using an alias, the platform expands the query at runtime to include both the alias and the canonical term — improving search coverage without requiring the user to know the exact terminology used in the source documents.

Configure vocabulary when:

* Your source documents use formal or technical terminology that users are unlikely to search for exactly.
* Your content uses abbreviations or acronyms that users may spell out — or vice versa.
* Different teams or user groups use different terms for the same concept.
* Search queries consistently miss relevant content despite the content existing in the knowledge base.

**Add Vocabulary**

To add a vocabulary entry, click Add Entry on the Vocabulary page and provide the following details.

| Field | Description |
| - | - |
| Term | The canonical term as it appears in the document. This is the authoritative form the platform uses for matching. Example: priority, status, assignee |
| Aliases | Alternative terms a user might search for, entered as comma-separated values. Maximum 10 aliases per term. Example: pri, urgency, importance |
| Description | A brief explanation of what the term represents. Used for internal reference. |
| Field Reference | The schema field this term is associated with. Select from the fields detected during schema extraction. Scopes the vocabulary mapping to a specific field in the index. |
| Capabilities | Define how the term and its aliases are used in the results. |
| Display With | Specify additional fields to show alongside this term in the results. |

### Configure AI

This section controls the models and LLM-powered features used for document ingestion, enrichment, and search in the given project.

**Tenant Models**: Manage the LLM providers and models available for this workspace. Click Configure Models to add or update model configurations. See Models for details.

#### Embedding models

Embedding models convert documents into vectors for semantic search. The active model applies to all document ingestion and retrieval in this workspace. BGE-M3 is the default embedding model.

> [!NOTE]
>
> Changing the embedding model requires re-ingestion. All documents are automatically re-processed and re-embedded. This operation may take time and incur costs depending on your provider.

#### Enrichment features

LLM-powered features that run during ingestion to generate summaries, questions, field mappings, and vocabulary. Each feature can be enabled or disabled independently and uses a configurable model. Click Change on any feature to switch its model.

* **Progressive Summarization**: Generates 2–3 sentence summaries per chunk using context from previous chunks. Improves retrieval quality for long documents.
* **Question Synthesis**: Generates 3–5 answerable questions per chunk. Improves retrieval accuracy by matching user queries to pre-generated questions.
* **Field Mapping Suggestions**: Suggests field mappings from the connector schema to the canonical schema during source configuration.
* **Domain Vocabulary Generation**: Enriches domain vocabulary with aliases, descriptions, and capabilities to improve search relevance for domain-specific terms.
* **Knowledge Graph Extraction**: Extracts entities and relationships to build a knowledge graph. This feature can be enabled upon request.

#### Advanced features

Higher-cost features for visual and multimodal content analysis. Each feature uses a balanced-tier model and can be enabled or disabled independently.

* **Vision Analysis**: Analyzes page screenshots and images to understand visual content. Useful for documents that contain charts, diagrams, or image-heavy pages.
* **Multimodal Deep Analysis**: Performs deep analysis of images, tables, and charts with data extraction. Use this for documents where structured visual content needs to be indexed.

#### Query pipeline LLM

Controls the LLM used at query time to understand and process queries.

**Query Intelligence**: When enabled, it automatically assigns the best available model for vocabulary resolution, query classification, filters, aggregations, structured queries, and enhanced search accuracy.

> [!NOTE]
>
> Query Intelligence applies to direct search queries only. It is not used when searching through Agent and Tools.

### Knowledge Graph

Knowledge Graph classifies documents against a configurable taxonomy, extracts entities from your content, and links them into a searchable graph, in addition to the standard chunk-based search index.

Standard knowledge base search retrieves chunks based on text similarity, treating each chunk largely as an independent unit. Knowledge Graph adds structure on top of this. It organizes content into a taxonomy (such as , domain → category → product → attribute) and connects related entities across documents, so the platform understands not just *what text matches a query*, but *how concepts relate to each other*.

This is useful when:

* Your content naturally maps to a structured taxonomy — such as a product catalog, service categories, or a domain with defined categories and attributes.
* You want to answer relationship-aware queries, such as "what products fall under Pharmacy" or "what attributes does this product have" — questions that depend on structure, not just text similarity.
* The same entity (a product, term, or concept) appears across multiple documents, and you want it recognized and linked as a single connected entity rather than treated as separate, unrelated mentions.
* You want to filter or facet search results by category, product, or attribute, rather than relying purely on keyword or semantic match.

### Setting Up the Knowledge Graph

Setting up Knowledge Graph involves:

1. Picking an industry domain (or letting AI generate one).
2. Building a taxonomy of products and attributes for that domain.
3. Automatically classifying every document against the taxonomy.
4. Extracting entities from content and linking them into the graph.

* Navigate to **Knowledge Graph** in the left sidebar of the knowledge base.

* Click **Select your domain**.

* Configure **Taxonomy**: Configuring the taxonomy defines the schema that the Knowledge Graph will classify the content against.

  | Field | Description |
  | - | - |
  | Domain | The industry domain the taxonomy is based on. |
  | Generate Profile with AI | Automatically generates a taxonomy profile using AI, based on the website provided. |
  | Organization Name | Optional. Your organization's name, used to help AI generate a more relevant taxonomy profile. |
  | Which products do you offer? | Optional. Select the products/services relevant to your organization. Available options are grouped by category (for example, Clinical Care, Health Insurance, Pharmacy, Diagnostics for a Healthcare domain) and vary by the selected domain. Click **Show Advanced** for additional options. |

* Click **Set Up Taxonomy** to save the configuration and create the taxonomy.

Once a taxonomy is configured, click **Run Enrichment** to classify documents and extract entities against the taxonomy, building the knowledge graph. Re-run enrichment after taxonomy changes or when new content has been added to the knowledge base.

* **Graph View** - Visualizes the knowledge graph as a network of connected nodes.
* **Statistics** — Summary metrics about the documents as per the taxonomy.
* **Attributes** — Lists the attributes defined in the taxonomy and their occurrences in the indexed content.

### Search and test

The Search and Test tab lets you validate the knowledge base configuration by running queries against indexed content before connecting it to an agent. It shows exactly how the knowledge base will respond to a query, including which chunks are returned, how they are ranked, and how each stage of the search pipeline performed.

**Query Settings**

Enter a query in the Query field and configure the following settings before running a search:

**Query Type** controls how the search matches the query to indexed content. Three options are available:

* Hybrid - combines semantic search and keyword search. Returns results that are both conceptually relevant and lexically matched. Recommended for most use cases.
* Semantic - finds conceptually relevant content based on meaning, even when the exact words don't appear in the source.
* Keyword - finds exact or near-exact matches. Best for structured content where precise term matching is important.

**Top K** defines the maximum number of chunks returned per query. Set this based on how much context the agent needs to compose an accurate response. A higher value returns more context but increases token consumption when the agent processes the results. Defaults to 10, and can be set from 1 to 100 in the index's Top K setting (see [Additional settings](#additional-settings)); an explicit request from a tool call is capped at 100 regardless.

#### Run a Test Query

Click Search to execute the query. The platform returns:

* Search retrieval time - total time taken and the time per search engine.
* Results - ranked list of matching chunks showing relevance score, source file, content preview, and metadata fields.
* Resolution Chain Debug, a step-by-step breakdown of how the query was processed.

The **Diagnostics** panel on the right provides a real-time view of the knowledge base's health across three areas:

* Data and Indexing - Shows the current state of indexed content, document count, chunk count, and the last indexed timestamp.
* Enrichment - Shows the configuration status of vocabulary and field mappings.
* Pipeline Health - Shows the embedding model in use, the current pipeline status, and whether any index errors have occurred.

The **Query** History section shows recent queries run against the knowledge base, along with the number of results returned, query type, and time taken.

#### Images in Search Results

During ingestion, SearchAI stores extracted images embedded in PDF, DOCX and PPTX files. HTML pages can also include inline base64 encoded images using a `data:` URL, commonly written as `data:image/png;base64,...`; extracted image bytes are stored with the document. Remote images referenced by an HTML page, such as `<img src="https://…">`, are not fetched. Their position can remain as an `<!-- image -->` marker in the chunk text, without a stored image to display.

If a search result contains references to stored images, it includes an `images` array.

```json theme={null}
{
  "chunkId": "01a177e0-fb6c-7064-bf3c-8f0b27af10ac",
  "content": "Click on the Settings icon in the top right corner:\n\n<!-- image -->",
  "images": [
    {
      "url": "https://<searchai-base>/documents/<documentId>/images/1/0?token=<signed>",
      "format": "png",
      "pageNumber": 1,
      "imageIndex": 0
    }
  ]
}
```

The images array contains the following information for each image:

* url: A signed URL that returns the image. The URL is tied to a specific image in a document, and access permissions are validated each time it is requested. The URL continues to work after the document is reprocessed, but becomes invalid if the document is deleted.
* format: The image format.
* pageNumber: The page containing the image.
* imageIndex: The index of the image on the page.

Points to Note:

* The `images` list is part of the SearchAI query API response; Studio does not display these links inline in its search results.  You can preview only extracted images in Studio in the document details.
* Image URLs can retrieve only the referenced image. They cannot be used to download the source document.
* Image URLs are persistent and authorize access to a single image within a specific document. Access is validated on every request, so the URL continues to work after the document is reprocessed but becomes invalid if the document is deleted.
* Search results return image URLs, not Base64-encoded image data. If your application requires a Base64 representation, retrieve the image using the returned `url` and encode the image bytes in your application.
* For PDF, DOCX, and PPTX files, each chunk lists the images from the pages it spans.
* For HTML pages, each chunk lists the images referenced by its content.
* Results without stored images do not include the images field.
* Existing documents must be reprocessed before image URLs are included in search results.

> [!NOTE]
>
> Agent responses currently use only the chunk text. The images metadata is returned in search results but is not passed to the model, so images are not included in generated responses.

### Additional settings

Manage knowledge base configuration, view indexing details, configure citation behavior, access API information, and perform administrative actions such as rebuilding or deleting the knowledge base.

* General - Basic information about the knowledge base.

* Index Configuration - Displays the retrieval and indexing settings used by the knowledge base.

  | Setting | Range | Default | What it does |
  | - | - | - | - |
  | Top K | 1 to 100 | 10 | Chunks returned when a search call doesn't specify a count. |
  | Similarity threshold | 0 to 1 | 0.2 | Minimum match score; 0 means no threshold. Raise it if weak matches are causing off-topic answers. |
  | Keyword Weight (Hybrid) | 0 to 1 | 0.5 | The balance between exact-term and semantic matching for a Hybrid query. Raise it toward 0.7 for FAQ or product-code content. |
  | Relevance Scoring | NA | `Classic` | `classic` / `advance`. **Classic**: Uses the existing relevance scoring behavior. Keyword and hybrid searches use rank-based scoring, so the highest-ranked result typically receives the highest score regardless of how completely it matches the query. **Advance**: Calculates relevance scores based on the quality of the keyword and semantic matches. Keyword scores consider both the BM25 score and query term coverage, vector scores use true cosine similarity, and hybrid scores combine both using the configured keyword weight. |

* Citations - Controls how source references appear in search results and AI-generated responses. When enabled, response includes references to the content used to generate the answer.

  | Option | Description |
  | - | - |
  | **Direct links** | Provides direct access to the source document when a citation is selected. |
  | **Time-limited links** | Generates temporary links that expire after a configured period. This helps control access to source content. Provide link expiry time in hours. |
  | **Click-limited links** | Generates links that can only be accessed a limited number of times before they become invalid. Provide the maximum time and maximum number of clicks for link expiry. |
  | **No links** | Displays citations without providing clickable links to the source document. |

  > [!NOTE]
  >
  > Available link behavior options may depend on the source type.

* API & SDK - Provides programmatic access information for the knowledge base.

* Rebuild Index - Reprocesses all documents and rebuilds the search index. Time taken to rebuild index depends on the content volume and knowledge base size.

* Delete Knowledge Base - Permanently deletes the knowledge base and all associated data.

## Use knowledge base as a tool in agents

Every knowledge base in the project automatically has a corresponding knowledge tool. Agents access the knowledge base content by attaching this tool. Once attached, the agent can invoke it at runtime to search the knowledge base and retrieve relevant content.

To attach a knowledge tool from the agent configuration:

1. Navigate to the agent and open the **Tools** section.
2. Click **Attach Tool**.
3. From the list of available tools, locate the knowledge tool for your knowledge base — knowledge tools are listed alongside all other project tools.
4. Select the tool to attach it to the agent.

**Attach a Knowledge Tool via DSL**

To attach a knowledge tool using the DSL editor, follow these steps:

1. Navigate to **Knowledge Tools** at the project level.
2. Open the knowledge tool that corresponds to your knowledge base.
3. Copy the DSL definition shown on the tool page.
4. Open the agent's DSL editor by clicking **DSL** at the top of the agent page.
5. Paste the copied DSL into the **Tools** section of the agent definition.
6. Compile and save the changes.

## Add business rules

Use business rules to control which search results are returned and the order in which they appear. Business rules are declarative. Define a condition and the action to apply when the condition is met. The search engine evaluates the rules for each query.

Business rules can:

* **Filter** results to a specific subset of content.
* **Hide** content that should not appear in search results.
* **Boost** specific results so they appear higher in the results.
* **Lower** specific results so they appear lower in the results.

> [!NOTE]
>
> * This feature is available only via DSL.
> * Business rules are not an access-control mechanism. Business rules are used to further filter or narrow down results that a user is authorized to access.

### Configuring business rules for an agent

Rules declared on an agent apply only to its searches. Different agents can govern the same knowledge base differently.

Author the rules as a JSON array in the `business_rules` block of the knowledge-base tool definition, alongside other tool fields.

**Example**

```yaml theme={null}
search_kb_policies(query: string) -> object
  description: "Search the policy knowledge base"
  type: searchai
  business_rules: |
    [{"id":"hide_archived","when":{"kind":"always"},
      "then":{"hide":[{"field":"status","operator":"eq","value":"archived"}]}}]
```

**Rule structure**

Each business rule has an `id`, a `when` condition, and a `then` effect. Other properties are optional.

| Field | Description |
| - | - |
| `id` | Stable identifier for the rule. Must be unique within the rule set. |
| `label` | Human-readable name shown in traces and UI. Defaults to the `id`. |
| `enabled` | Determines whether the rule is evaluated. |
| `priority` | Determines the order in which rules are evaluated. Lower numbers are evaluated first. |
| `enforced` | Applies only to knowledge-base rules and changes rule precedence. |
| `relaxable` | Determines whether an empty-result fallback can drop the rule's filters. |

**Conditions**

The `when` condition determines when a rule is applied. A rule can have exactly one condition.

| Condition | Description |
| - | - |
| `always` | Applies the rule to every search. |
| `query` | Applies the rule based on the question text. |
| `value` | Applies the rule based on a named value supplied by the caller. |
| `intent` | Applies the rule based on a category supplied by the caller. |

**Examples:**

```yaml theme={null}
"when": { "kind": "always" } # `always` - Fires on every search. Use for standing policy.
```

```yaml theme={null}

# `query` - Fires when the question text contains a phrase. Case-insensitive substring match. Supply exactly one of `value` or `anyOf`.

// one phrase
"when": { "kind": "query", "operator": "contains", "value": "refund" }

// several phrasings, OR-ed
"when": { "kind": "query", "operator": "contains",
          "anyOf": ["401k", "401 (k)", "retirement", "pension"] }
```

**`not_contains` means none of them.** Negating a list is “the question mentions *none* of these”, not “it is missing at least one” — which would fire on almost every query.

```yaml theme={null}
# `value` - Fires when a named value the conversation already established matches. The caller must send it with the request as `callerValues`.

"when": { "kind": "value", "name": "customer_tier",
          "operator": "eq", "value": "enterprise" }
```

* Operators: `eq` `neq` `in` `not_in` `exists` `not_exists` `gt` `gte` `lt` `lte`
* `eq` and `in` compare as text, so a caller sending `"5"` matches a rule written as `5`.
* `gt` `gte` `lt` `lte` coerce to a number or date and report `value_not_comparable` rather than guessing.
* A value the caller never sent makes the rule **inert, not broken** — reported as `condition_not_met`.

```yaml theme={null}
# `intent` - Fires when the turn was classified into one of the listed categories. The search engine never computes this; the caller supplies it as `callerIntent`.

"when": { "kind": "intent",
          "anyOf": ["refund_request", "return_request"],
          "minConfidence": 0.7 }
```

* Matching is case-insensitive, up to 50 ids.
* `minConfidence` is optional. A caller that sends no confidence is treated as certain.
* If no intent arrives at all, the trace says `intent_absent` — see [Observability](#trace).

**Effects**

The `then` property defines what happens to the search results. A rule can use multiple effects.

| Effect | Description |
| - | - |
| `filters` | Keeps only results that match the specified filters. |
| `hide` | Removes matching results. |
| `boost` | Increases the ranking of matching results. |
| `lower` | Decreases the ranking of matching results. |

**Examples:**

```yaml theme={null}
"then": {
  "filters": [ { "field": "source_type", "operator": "eq", "value": "hr_portal" } ],
  "hide":    [ { "field": "status", "operator": "eq", "value": "archived" } ],
  "boost":   [ { "field": "category", "value": "official", "weight": 30 } ],
  "lower":   [ { "field": "source_type", "value": "forum", "weight": 10 } ]
}
```

* `weight` ranges 0-100. A weight of 1 is effectively a no-op.
* When there are multiple `filters` entries, a logical AND is performed between them.

```yaml theme={null}
{ "field": "source_type", "operator": "eq", "value": "sharepoint" }
```

| Operator | Meaning |
| - | - |
| `eq` · `neq` | Equals / does not equal |
| `in` · `not_in` | Is one of / is none of an array |
| `contains` · `not_contains` | Substring match on text |
| `gt` · `gte` · `lt` · `lte` | Numeric or date comparison |
| `exists` · `not_exists` | Field is present. Omit `value`. |

**Nested groups**

A `filter` entry may be a group as shown below. Groups can be nested up to five levels.

```yaml theme={null}
// manual uploads, OR ServiceNow articles for India and the UK
"filters": [ {
  "mode": "any",
  "filters": [
    { "field": "source_type", "operator": "eq", "value": "manual" },
    { "mode": "all", "filters": [
        { "field": "source_type", "operator": "eq", "value": "servicenow" },
        { "field": "custom_string_1", "operator": "in", "value": ["IND", "ENG"] } ] }
  ] } ]
```

**Fields**

Business rules can target all canonical fields(normalized fields that every source can access) such as `content`, `origin`, `classification`, etc.

### Tool-level search settings

Beyond the Studio configuration in [Configure AI](#configure-ai) and [Search and test](#search-and-test), the generated `search_kb_<name>` tool itself takes a few settings. Set them on the project tool definition -- a tool library file, or the Studio tool editor. An agent's own `TOOLS:` entry for the same tool can set `search_instructions`, `kb_fast_path` and `business_rules`.

```yaml theme={null}
TOOLS:
  search_kb_hr_policies(query: string) -> object
    description: "Search the HR policy handbook. Use for leave, benefits and conduct questions."
    type: searchai
    kb_name: "HR Policies"
    retrieval_profile: object-aware
    compaction:
      max_search_tokens: 6000
    search_instructions: |
      Prefer the current policy year.
      Always filter by the employee's country when it is known.
```

| Setting | Values | Default | What it does |
| - | - | - | - |
| `kb_fast_path` | `on`, `off` | off | `on` turns on the automatic first search for this tool, if the agent meets the conditions in [How the platform searches](#how-the-platform-searches). An agent's own value overrides the project tool's. |
| `search_instructions` | free text | none | Added to the tool description, and turns on query planning for the automatic first search. Query planning also runs when the knowledge base has vocabulary fields. An agent-file value is used only when the project tool has none of its own. |
| `retrieval_profile` | `object-aware` | standard retrieval | Splits a question into up to 10 document categories, searches each in parallel with reranking, and merges the results. Useful for a knowledge base that mixes document types where one question needs several of them. |
| `compaction.max_search_tokens` | 1 to 40,000 | none when 10 or fewer chunks return; 40,000 above that | Token budget for the results the model reads. Whole chunks are dropped from the end, never cut mid-text. Lower it for voice agents and short answers -- a large budget slows the reply and dilutes grounding. |
| `queryType`, `topK`, `filters`, `similarityThreshold` (optional parameters) | `queryType`: `vector`, `hybrid`, `structured`, `semantic`, `keyword`, `aggregation`; `topK` up to 100 | not exposed; the tool takes only `query` | Declare these as optional parameters to let the model set the result count or filters on each call. The platform runs `hybrid` search unless the customer's message or the search instructions explicitly ask for another mode, so a `queryType` the model writes on its own becomes `hybrid`. An `aggregation` search keeps its type. Use only when the model must steer the search itself -- otherwise leave it to the planner. |

> [!NOTE]
>
> Other tool-result [compaction](https://koreai.mintlify.site/agent-platform/abl-reference/tools.md#result-compaction) settings don't apply to knowledge base results -- `max_search_tokens` is the lever to use. The only other limit is the shared budget when several tools run in parallel in the same turn (100,000 characters divided across them).

Silent traps:

* `retrieval_profile` accepts only the exact value `object-aware`. Any other value, including different casing, is ignored.
* An agent-file `search_instructions` is ignored once the project tool already has instructions of its own.
* If citations are turned off on any one knowledge base attached to an agent, they are turned off for all of that agent's knowledge bases.
* Test retrieval with a real customer identity where possible. Studio test chats search with public permissions, so permission-restricted content may not show up there. Search applies per-user document permissions only when the session carries the user's verified identity with an email.
* Always set `max_search_tokens` in the agent's copy of the search tool, so results stay small as the documents grow.

### Diagnose a wrong answer

Read the search call in the session's traces. Then run the same query in the knowledge base's **Search & Test**.

| Failed layer | Sign | Fix |
| - | - | - |
| Not indexed | The document is missing or not indexed. | Ingestion |
| Not retrieved | The right chunk isn't in the results. | Query, description, Top K, chunking |
| Cut by the budget | The trace shows omitted results. | `max_search_tokens`, Top K |
| Ignored | The right chunk came back, but the answer is wrong. | Instructions |

Add test questions that the documents can't answer. They catch invented answers. Give the agent the sentence to say when the documents don't cover a question.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.