Knowledge Base

​

What is a Knowledge Base?

• Answer specific questions - Provide accurate answers from your documentation
• Cite sources - Reference specific documents and sections
• Stay up-to-date - Access current information, not just training data
• Handle complex queries - Search across multiple documents
• Reduce hallucinations - Ground responses in actual data

​

Knowledge Base Architecture

​

Collections

• Product Documentation
• Company Policies
• FAQ Database
• Technical Support Guides
• Sales Playbooks

​

Files

• PDF documents
• Text files (.txt)
• Markdown files (.md)
• Word documents (.docx)
• HTML files

​

Many-to-Many Relationship

Collection: "Product Support"
  ├── product-overview.pdf
  ├── troubleshooting-guide.pdf
  └── warranty-info.pdf

Collection: "Sales Resources"
  ├── product-overview.pdf (shared)
  ├── pricing-sheet.pdf
  └── case-studies.pdf

​

Setting Up Your Knowledge Base

​

Step 1: Create Collections

const collection = {
  name: "Product Documentation",
  description: "Technical documentation for all products"
};

const response = await fetch('https://prod.featherhq.com/api/v1/knowledge-base/collection', {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(collection)
});

const createdCollection = await response.json();

​

Step 2: Upload Files

const urlRequest = {
  fileId: "product-guide-v2.pdf",
  prompt: "Technical product documentation" // Optional
};

const urlResponse = await fetch('https://prod.featherhq.com/api/v1/knowledge-base/file/generate-presigned-url', {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(urlRequest)
});

const { uploadUrl, fileId } = await urlResponse.json();

// Upload the actual file
const fileBlob = await fs.readFile('./product-guide.pdf');

await fetch(uploadUrl, {
  method: 'PUT',
  body: fileBlob,
  headers: {
    'Content-Type': 'application/pdf'
  }
});

// Create the file record
const fileRecord = {
  fileId: fileId
};

const fileResponse = await fetch('https://prod.featherhq.com/api/v1/knowledge-base/file', {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(fileRecord)
});

​

Step 3: Add Files to Collections

const linkRequest = {
  collectionId: "collection-123",
  fileId: "file-456"
};

const response = await fetch('https://prod.featherhq.com/api/v1/knowledge-base/collection/file', {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(linkRequest)
});

​

Step 4: Enable in Agent

const agentVersion = {
  mode: "PROMPT",
  useKnowledgeBase: true,
  prompt: {
    system: "You are a helpful support agent. Use the knowledge base to answer customer questions. Always cite your sources.",
    preBuiltTools: ["knowledge-search"]
  },
  // ... other configuration
};

const response = await fetch(`https://prod.featherhq.com/api/v1/agents/${agentId}`, {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(agentVersion)
});

​

File Processing

​

Processing States

1. PENDING - File uploaded, processing not started
2. PROCESSING - File being indexed and embedded
3. COMPLETED - File ready for search
4. FAILED - Processing error occurred

​

Checking File Status

const response = await fetch(`https://prod.featherhq.com/api/v1/knowledge-base/file/${fileId}`, {
  headers: {
    'X-API-Key': API_KEY
  }
});

const file = await response.json();
console.log(file.status); // PENDING, PROCESSING, COMPLETED, or FAILED

​

Processing Time

• File size
• File format
• Document complexity
• Current system load

• Small PDFs (< 10 pages): 10-30 seconds
• Medium PDFs (10-100 pages): 30-120 seconds
• Large PDFs (> 100 pages): 2-5 minutes

​

Using Knowledge Base in Conversations

​

Automatic Search

• Customer asks a specific question
• Information isn’t in the agent’s training data
• Agent needs to verify details
• Customer requests documentation

Customer: "What's your return policy?"
Agent: [Searches knowledge base for "return policy"]
Agent: "According to our return policy, you can return items within 30 days
       of purchase for a full refund. The item must be unused and in original
       packaging. Source: Returns and Refunds Policy, Section 2.1"

​

Prompt Engineering for Knowledge Base

{
  system: `You are a technical support agent with access to our knowledge base.

When answering questions:
1. Search the knowledge base first
2. Cite specific documents and sections
3. If information isn't found, be honest about limitations
4. Don't make up information not in the knowledge base

Example response format:
"According to [Document Name], [answer]. This information is from [specific section]."

If you can't find the answer, say:
"I don't have that information in our current documentation. Let me transfer you to a specialist who can help."`
}

​

Managing Your Knowledge Base

​

Listing Collections

const response = await fetch('https://prod.featherhq.com/api/v1/knowledge-base/collections', {
  headers: {
    'X-API-Key': API_KEY
  }
});

const collections = await response.json();

​

Listing Files

const response = await fetch('https://prod.featherhq.com/api/v1/knowledge-base/files', {
  headers: {
    'X-API-Key': API_KEY
  }
});

const files = await response.json();

​

Removing Files from Collections

const removeRequest = {
  collectionId: "collection-123",
  fileId: "file-456"
};

const response = await fetch('https://prod.featherhq.com/api/v1/knowledge-base/collection/file', {
  method: 'DELETE',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(removeRequest)
});

​

Deleting Files

const response = await fetch(`https://prod.featherhq.com/api/v1/knowledge-base/file/${fileId}`, {
  method: 'DELETE',
  headers: {
    'X-API-Key': API_KEY
  }
});

​

Best Practices

​

Content Organization

1. Use descriptive collection names - Make it easy to identify content
2. Group related content - Keep similar documents together
3. Avoid duplication - Use shared files across collections instead
4. Regular maintenance - Remove outdated documents
5. Version control - Include version numbers in file names

​

Document Preparation

1. Clear structure - Use headings, sections, and lists
2. Consistent formatting - Maintain uniform document styles
3. Remove unnecessary content - Strip out navigation, headers, footers
4. Include metadata - Add titles, dates, and version numbers
5. Plain language - Write clearly and concisely

​

File Naming

✅ Good Examples:
- product-guide-v2.1-2024.pdf
- return-policy-updated-jan-2024.pdf
- troubleshooting-wifi-issues.pdf

❌ Poor Examples:
- document.pdf
- new_file_final_FINAL.pdf
- Copy of guide (1).pdf

​

Search Optimization

1. Include key terms - Use terminology your customers use
2. Add context - Provide background information in documents
3. Answer questions directly - Structure content as Q&A when possible
4. Cross-reference - Link related topics
5. Update regularly - Keep information current

​

Agent Configuration

1. Explicit instructions - Tell agents when to search knowledge base
2. Cite sources - Require agents to reference documents
3. Handle not found - Define what to do when information isn’t found
4. Combine with tools - Use knowledge base alongside custom tools
5. Test thoroughly - Verify agents find correct information

​

Common Use Cases

​

Limitations & Considerations

​

File Limits

• Maximum file size: 50 MB per file
• Maximum files per organization: Varies by plan
• Supported formats: PDF, TXT, MD, DOCX, HTML

​

Search Performance

• Search time: Typically 1-3 seconds
• Relevance: Depends on query specificity and document quality
• Context window: Limited amount of text can be returned

​

Processing Constraints

• Large files take longer to process
• Complex formatting may affect extraction quality
• Scanned PDFs require OCR (slower processing)

​

Troubleshooting

​

File Won’t Upload

• File size under limit
• Supported file format
• Valid file content
• Presigned URL not expired

​

File Stuck in PROCESSING

• Delete and re-upload the file
• Check file format and content
• Contact support with file ID

​

Agent Not Finding Information

• File status is COMPLETED
• useKnowledgeBase is true
• knowledge-search tool is enabled
• Agent prompt includes search instructions

• Add more specific keywords to documents
• Restructure content for clarity
• Upload additional relevant files
• Refine agent search instructions

​

Irrelevant Search Results

• Improve document quality and structure
• Add more context to documents
• Use more specific file prompts
• Refine agent search queries in prompts

​

Next Steps