Skip to main content

User Guide

This guide explains how to create and manage Knowledge Bases and connect them to CX Assistants.

Creating a Knowledge Base​

Step 1: Navigate to Knowledge Bases​

  1. Log in to the Deepdesk Admin interface
  2. In the left sidebar, navigate to Knowledge Assist > Knowledge Bases
  3. Click Add knowledge base

Step 2: Configure Basic Settings​

FieldDescription
CodeUnique identifier (lowercase letters, numbers, dashes). Cannot be changed after creation.
NameDisplay name for the knowledge base
DescriptionOptional description of the knowledge base contents
info

The code is used to reference the knowledge base in Assistant configurations and API calls. Choose a meaningful, descriptive code like support-articles or product-docs.

Step 3: Add Content Sources​

URLs​

Add URLs to web pages that should be crawled. Enter one URL per line:

https://help.example.com/articles
https://docs.example.com/faq
https://example.com/support/getting-started

The crawler will:

  • Extract text content from each page
  • Follow internal links to discover related pages
  • Index the content for search

Files​

Add URLs to files (PDFs, documents) that should be processed:

https://example.com/files/user-manual.pdf
https://example.com/files/policy-guide.pdf
warning

URLs must be publicly accessible. Private or internal URLs are not allowed for security reasons.

Step 4: Save and Crawl​

  1. Click Save to create the knowledge base
  2. From the knowledge base list, select the knowledge base
  3. Use the Launch Knowledge Base web crawler action to start indexing

Managing Crawl Jobs​

Starting a Crawl​

From the Knowledge Base admin:

  1. Select one or more knowledge bases
  2. Choose Launch Knowledge Base web crawler from the actions dropdown
  3. Click Go

The crawl job will be queued and processed asynchronously.

Monitoring Crawl Status​

Navigate to Knowledge Assist > Crawl Jobs to view all crawl jobs:

StatusDescription
CreatedJob created but not yet queued
QueuedJob sent to the crawler service
StartedCrawling in progress
CompletedCrawling finished successfully
FailedCrawling encountered an error

You will receive an email notification when crawl jobs complete or fail.

Re-crawling Content​

To update the knowledge base with fresh content:

  1. Navigate to the knowledge base
  2. Launch a new crawl job
  3. Wait for completion
info

Only one crawl job can be active per knowledge base at a time. Wait for the current job to complete before starting a new one.

Connecting to an Assistant​

Step 1: Navigate to the Assistant​

  1. Go to Assistants > Assistants
  2. Click on the Assistant you want to configure

Step 2: Set the Knowledge Base​

In the Assistant configuration:

  1. Find the Knowledge base code field
  2. Enter the code of your knowledge base (e.g., support-articles)
  3. Click Save

When this field is set, the Assistant will automatically:

  • Have access to the retrieve_knowledge tool
  • Receive instructions to use the knowledge base for answering questions

Step 3: Test the Assistant​

Evaluate the Assistant with a test question to verify it retrieves knowledge correctly:

  1. Use the Playground or API to send a question
  2. Check that the response references information from the knowledge base
  3. Verify source URLs are included (if configured)

Managing Documents​

Viewing Documents​

Navigate to Knowledge Assist > Documents to see all indexed documents:

  • External ID: Unique identifier from the source
  • Title: Document title
  • URL: Source URL
  • Last Crawled At: When the document was last updated

Manual Document Management​

While most documents are created through crawling, you can also:

  • Edit document content (title, description, body)
  • Delete documents that should be removed from search

Changes are automatically synced to the search index.

Best Practices​

Content Organization​

  1. Use separate knowledge bases for different content types or domains
  2. Keep URLs organized by topic or section
  3. Update regularly to keep content fresh

URL Selection​

  1. Start with high-level pages that link to related content
  2. Avoid duplicate content (same content at different URLs)
  3. Prefer stable URLs that won't change frequently

Testing​

  1. Test with real questions users might ask
  2. Verify accuracy of retrieved information
  3. Check for gaps where knowledge is missing

Troubleshooting​

Crawl Job Failed​

  1. Check the crawl job details for error messages
  2. Verify URLs are accessible and return valid content
  3. Ensure URLs are not private/internal addresses
  4. Try crawling a single URL to isolate the issue

No Results Returned​

  1. Verify the knowledge base has been crawled successfully
  2. Check that documents exist in the knowledge base
  3. Test with different search queries
  4. Verify the Assistant's knowledge_base_code matches the knowledge base

Incorrect Results​

  1. Review document content for accuracy
  2. Consider adding more specific content
  3. Re-crawl to update stale content
  4. Adjust the Assistant's instructions for better query handling

Crawl Not Starting​

  1. Check if another crawl is already in progress
  2. Verify you have the required permissions
  3. Ensure Knowledge Assist is enabled for your account