Knowledge Base & RAG

RAG (Retrieval Augmented Generation) enables your AI agents to access and retrieve information from your organization’s knowledge base during conversations. This allows agents to provide accurate, up-to-date responses based on your company’s documentation, FAQs, policies, and other content.

Overview

What is RAG?

RAG combines the power of large language models with your organization’s specific knowledge:

Document Storage: Upload your documents in MD format to knowledge bases
Automatic Indexing: Documents are processed and indexed for semantic search
Real-time Retrieval: During conversations, relevant content is retrieved based on user queries
Context-aware Responses: The agent uses retrieved content to provide accurate answers

When to Use RAG

Ideal Use Cases:

Customer support with product documentation
Internal helpdesk with company policies
Sales agents with pricing and product information
Healthcare with protocol and procedure guides
Legal assistants with contract templates and regulations

Benefits:

Reduce hallucinations by grounding responses in actual documents
Keep information current without retraining models
Provide source-backed answers for compliance
Scale knowledge across multiple agents

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        USER CONVERSATION                            │
└─────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        AI AGENT (LLM)                               │
│                                                                     │
│   User asks: "What's your return policy?"                          │
└─────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     KNOWLEDGE BASE QUERY                            │
│                                                                     │
│   Query: "return policy refund exchange"                           │
└─────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    DOCUMENT RETRIEVAL                               │
│                                                                     │
│   Retrieved: "30-day return policy..."                             │
│              "Refund processing takes 5-7 business days..."        │
└─────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    AUGMENTED RESPONSE                               │
│                                                                     │
│   Agent: "Our return policy allows returns within 30 days.         │
│           Refunds are processed in 5-7 business days..."           │
└─────────────────────────────────────────────────────────────────────┘

Configuration

Step 1: Create a Knowledge Base

First, create a knowledge base to store your documents:

Via Dashboard
Via API

Navigate to Knowledge Bases in the sidebar
Click Create Knowledge Base
Enter a name and optional description
Click Create

const response = await fetch('https://blackbox.dasha.ai/api/v1/rag/kb', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Customer Support KB",
    description: "Product documentation and FAQ for customer support agents",
    type: "Files"
  })
});

const knowledgeBase = await response.json();
console.log('Knowledge Base ID:', knowledgeBase.id);

Step 2: Upload Documents

Add documents to your knowledge base:

Via Dashboard
Via API

Open your knowledge base
Click Upload Documents
Select files (only MD format supported)
Wait for processing to complete (status: “Indexed”)

const formData = new FormData();
formData.append('file', documentFile);

const response = await fetch(
  `https://blackbox.dasha.ai/api/v1/rag/kb/${knowledgeBaseId}/documents`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    },
    body: formData
  }
);

const result = await response.json();
console.log('Document ID:', result.documentId);
console.log('Status:', result.status); // "Uploaded" -> "Processing" -> "Indexed"

Step 3: Link Knowledge Base to Agent

Enable RAG on your agent and link the knowledge base:

Via Dashboard
Via API

Open your agent configuration
Navigate to Features tab
Enable RAG / Knowledge Base
Select the knowledge base(s) to link
Save your agent

const agent = await fetch('https://blackbox.dasha.ai/api/v1/agents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Support Agent with RAG",
    config: {
      version: "v1",
      primaryLanguage: "en-US",
      llmConfig: {
        version: "v1",
        vendor: "openai",
        model: "gpt-4.1-mini",
        prompt: "You are a helpful customer support agent. Use the knowledge base to answer customer questions accurately."
      },
      ttsConfig: {
        version: "v1",
        vendor: "ElevenLabs",
        voiceId: "YOUR_VOICE_ID"
      },
      features: {
        version: "v1",
        rag: {
          version: "v1",
          isEnabled: true,
          kbLinks: [
            { id: "YOUR_KNOWLEDGE_BASE_ID" }
          ]
        }
      }
    }
  })
});

Schema Reference

RAGFeature

Configuration for the RAG/Knowledge Base feature on an agent.

{
  "version": "v1",
  "isEnabled": true,
  "kbLinks": [
    { "id": "kb_123e4567-e89b-12d3-a456-426614174000" },
    { "id": "kb_987fcdeb-51a2-3bc4-d567-890123456789" }
  ]
}

Property	Type	Default	Description
`version`	`"v1"` \| `null`	`"v1"`	Schema version
`isEnabled`	`boolean` \| `null`	`false`	Whether RAG is enabled for this agent
`kbLinks`	`Array<KBLink>`	`[]` (required)	Links to knowledge bases the agent can query

KBLink

A reference to a knowledge base.

{
  "id": "kb_123e4567-e89b-12d3-a456-426614174000"
}

Property	Type	Constraints	Description
`id`	`string`	minLength: 1, maxLength: 255	Knowledge base identifier

KnowledgeBaseInfo

Full knowledge base information returned by API.

{
  "id": "kb_123e4567-e89b-12d3-a456-426614174000",
  "customerId": "cust_abc123",
  "name": "Customer Support KB",
  "description": "Product documentation and FAQ",
  "type": "Files",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "status": "Active",
  "statistics": {
    "knowledgeBaseId": "kb_123e4567-e89b-12d3-a456-426614174000",
    "documentsByStatus": {
      "Indexed": 15,
      "Processing": 2,
      "Failed": 0
    }
  }
}

Property	Type	Description
`id`	`string` (UUID)	Unique knowledge base identifier
`customerId`	`string` (UUID)	Organization identifier
`name`	`string`	Knowledge base name
`description`	`string`	Optional description
`type`	`"Files"`	Knowledge base type
`createdAt`	`string` (ISO 8601)	Creation timestamp
`updatedAt`	`string` (ISO 8601)	Last update timestamp
`status`	`KnowledgeBaseStatus`	Current status
`statistics`	`KnowledgeBaseStatistics`	Document processing statistics

KnowledgeBaseStatus

type KnowledgeBaseStatus = "Active" | "PendingDelete" | "Deleting";

DocumentStatus

type DocumentStatus =
  | "Uploaded"    // File received, awaiting processing
  | "Queued"      // In queue for processing
  | "Processing"  // Currently being indexed
  | "Indexed"     // Successfully indexed and searchable
  | "Failed"      // Processing failed
  | "Cancelled"   // Processing was cancelled
  | "PendingDelete"  // Marked for deletion
  | "Deleting";      // Currently being deleted

API Endpoints

Knowledge Base Management

Method	Endpoint	Description
`POST`	`/api/v1/rag/kb`	Create a knowledge base
`GET`	`/api/v1/rag/kb`	List knowledge bases
`GET`	`/api/v1/rag/kb/{id}`	Get knowledge base details
`PUT`	`/api/v1/rag/kb/{id}`	Update knowledge base
`DELETE`	`/api/v1/rag/kb/{id}`	Delete knowledge base

Document Management

Method	Endpoint	Description
`POST`	`/api/v1/rag/kb/{id}/documents`	Upload document
`GET`	`/api/v1/rag/kb/{id}/documents`	List documents
`GET`	`/api/v1/rag/kb/{id}/documents/{docId}`	Get document details
`DELETE`	`/api/v1/rag/kb/{id}/documents/{docId}`	Delete document

Search

Method	Endpoint	Description
`POST`	`/api/v1/rag/search`	Search across knowledge bases

Examples

Complete Agent Configuration with RAG

const createAgentWithRAG = async () => {
  const response = await fetch('https://blackbox.dasha.ai/api/v1/agents', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: "Product Support Agent",
      config: {
        version: "v1",
        primaryLanguage: "en-US",
        llmConfig: {
          version: "v1",
          vendor: "openai",
          model: "gpt-4.1-mini",
          prompt: `You are a knowledgeable product support agent for TechCorp.

INSTRUCTIONS:
- Use the knowledge base to answer product questions accurately
- If you're not sure about something, say so honestly
- For complex issues, offer to transfer to a human specialist
- Always be helpful and professional

KNOWLEDGE BASE USAGE:
- Product specifications and features are in the knowledge base
- Warranty and return policies are documented
- Troubleshooting guides are available for common issues`
        },
        ttsConfig: {
          version: "v1",
          vendor: "ElevenLabs",
          voiceId: "YOUR_VOICE_ID",
          model: "eleven_turbo_v2_5"
        },
        features: {
          version: "v1",
          rag: {
            version: "v1",
            isEnabled: true,
            kbLinks: [
              { id: "kb_product_documentation" },
              { id: "kb_support_policies" }
            ]
          },
          silenceManagement: {
            version: "v1",
            isEnabled: true,
            maxReminderAttempts: 2,
            reminderSilenceThresholdSeconds: 5,
            endWhenReminderLimitExceeded: true
          }
        }
      }
    })
  });

  return response.json();
};

Linking Multiple Knowledge Bases

Link different knowledge bases for different purposes:

{
  config: {
    version: "v1",
    features: {
      version: "v1",
      rag: {
        version: "v1",
        isEnabled: true,
        kbLinks: [
          // Product documentation
          { id: "kb_products" },
          // Company policies
          { id: "kb_policies" },
          // FAQ and common questions
          { id: "kb_faq" }
        ]
      }
    }
  }
}

Searching Knowledge Base Programmatically

Test your knowledge base with direct search:

const searchKnowledgeBase = async (query) => {
  const response = await fetch('https://blackbox.dasha.ai/api/v1/rag/search', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: query,
      knowledgeBaseNames: ["Customer Support KB"],
      maxResults: 5,
      minScore: 0.5
    })
  });

  const results = await response.json();

  results.items.forEach((item, index) => {
    console.log(`Result ${index + 1}:`);
    console.log(`  Score: ${item.score}`);
    console.log(`  Title: ${item.title}`);
    console.log(`  Content: ${item.content?.substring(0, 200)}...`);
  });

  return results;
};

// Example usage
await searchKnowledgeBase("What is the return policy?");

Best Practices

Document Preparation

1. Structure Your Content

Use clear headings and sections
Include relevant keywords
Keep paragraphs focused on single topics
Use consistent terminology

2. Content Quality

Remove outdated information before uploading
Ensure accuracy of all content
Include common variations of terminology
Add context for acronyms and technical terms

Knowledge Base Organization

1. Separate by Domain

kb_products       - Product specifications and features
kb_support        - Troubleshooting and support guides
kb_policies       - Return, warranty, and company policies
kb_faq            - Frequently asked questions

2. Keep Updated

Regularly review and update documents
Remove outdated versions
Track document status for processing failures

3. Test Thoroughly

Test searches with common customer queries
Verify retrieval accuracy
Adjust content based on results

System Prompt Integration

1. Reference the Knowledge Base

You have access to our product knowledge base. Use it to:
- Answer specific product questions
- Provide accurate policy information
- Troubleshoot common issues

2. Set Expectations

When you're not sure about something:
- Check the knowledge base first
- If not found, be honest about limitations
- Offer to transfer to a human specialist

3. Handle Gaps

If the knowledge base doesn't contain the answer:
- Acknowledge the limitation
- Offer alternative help options
- Collect feedback for future improvements

Troubleshooting

Documents Not Indexing

Symptoms:

Documents stuck in “Processing” status
Documents showing “Failed” status

Solutions:

Check document format is supported (MarkDown)
Ensure file size is within limits
Verify document content is extractable
Check for special characters or encoding issues
Re-upload the document if processing failed

Agent Not Using Knowledge Base

Symptoms:

Agent doesn’t reference KB content
Responses seem generic or incorrect

Solutions:

Verify RAG is enabled (isEnabled: true)
Check knowledge base links are correct
Ensure documents are in “Indexed” status
Test search directly via API
Improve system prompt to explicitly mention KB usage

Poor Search Results

Symptoms:

Irrelevant content retrieved
Missing expected results

Solutions:

Review document content structure
Add more context and keywords to documents
Adjust minScore threshold if too high
Increase maxResults for broader coverage
Test different query phrasings

Slow Responses

Symptoms:

Long delays before agent responds
Timeout errors

Solutions:

Reduce maxResults in search configuration
Optimize document count per knowledge base
Split large knowledge bases by topic
Check network latency to API

Limitations

File Size: Individual documents have size limits
Processing Time: Large documents may take longer to index
Format Support: Limited to MD format
Query Length: Search queries have character limits
Results Count: Maximum results per search is limited

Next Steps

Now that you understand RAG and Knowledge Base:

Create Your First KB: Start with a small set of core documents
Test Retrieval: Use the search API to verify content is accessible
Configure Agent: Link KB and update system prompt
Monitor Performance: Track usage and accuracy
Iterate: Add documents and refine based on real conversations

Agent Basics - Core agent configuration
LLM Configuration - System prompt best practices
Advanced Features - Other agent features
Webhooks - Capture call results

Introduction

Build

Deploy

Monitor

Webhooks & Events

Advanced

WebSockets

​Knowledge Base & RAG

​Overview

​What is RAG?

​When to Use RAG

​Architecture

​Configuration

​Step 1: Create a Knowledge Base

​Step 2: Upload Documents

​Step 3: Link Knowledge Base to Agent

​Schema Reference

​RAGFeature

​KBLink

​KnowledgeBaseInfo

​KnowledgeBaseStatus

​DocumentStatus

​API Endpoints

​Knowledge Base Management

​Document Management

​Search

​Examples

​Complete Agent Configuration with RAG

​Linking Multiple Knowledge Bases

​Searching Knowledge Base Programmatically

​Best Practices

​Document Preparation

​Knowledge Base Organization

​System Prompt Integration

​Troubleshooting

​Documents Not Indexing

​Agent Not Using Knowledge Base

​Poor Search Results

​Slow Responses

​Limitations

​Next Steps

​Related Documentation

​API Cross-Refs

Knowledge Base & RAG

Overview

What is RAG?

When to Use RAG

Architecture

Configuration

Step 1: Create a Knowledge Base

Step 2: Upload Documents

Step 3: Link Knowledge Base to Agent

Schema Reference

RAGFeature

KBLink

KnowledgeBaseInfo

KnowledgeBaseStatus

DocumentStatus

API Endpoints

Knowledge Base Management

Document Management

Search

Examples

Complete Agent Configuration with RAG

Linking Multiple Knowledge Bases

Searching Knowledge Base Programmatically

Best Practices

Document Preparation

Knowledge Base Organization

System Prompt Integration

Troubleshooting

Documents Not Indexing

Agent Not Using Knowledge Base

Poor Search Results

Slow Responses

Limitations

Next Steps

Related Documentation

API Cross-Refs