> ## Documentation Index > Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt > Use this file to discover all available pages before exploring further. # Knowledge Bases > Upload documents and give your agents instant access to your knowledge ## Overview Knowledge Bases are organized collections of documents that your agents can search and reference during conversations. Upload your company policies, research papers, technical documentation, and any reference materials to make them instantly searchable by your AI agents. Knowledge Base architecture: documents flow through upload, parse, chunk, extract, and embed into the knowledge base, which agents reach via search, read, list, write, and the Python sandbox. ## Key Features ### Multi-Format Document Support Upload documents in various formats and your agents will automatically understand the content: | File Type | Formats | Notes | | ---------------- | ------------------------------------ | ------------------------------------------------------- | | PDF Documents | .pdf | Text extraction with OCR fallback for scanned documents | | Word Documents | .docx | Full formatting preservation | | PowerPoint | .pptx | Slide content extraction | | Spreadsheets | .xlsx, .xls, .xlsm | Table structure conversion | | CSV Files | .csv | Structured data with automatic dialect detection | | Images | .png, .jpg, .jpeg, .gif, .bmp, .webp | AI vision for text and content extraction | | Text Files | .txt, .md, .json, .xml | Plain text processing | | HTML Files | .htm, .html | Web content analysis | | YAML Files | .yaml, .yml | Configuration and data files | | Outlook Messages | .msg | Email content extraction | **File size limit**: 250MB per file ### Intelligent Processing Pipeline Every file moves through a five-stage pipeline. Stage 3 forks into **two durable outputs**: the embedded chunks that power semantic search, and — when an extraction schema is set — the structured data your agents later read as `extracted_data.json`. Files are uploaded directly to secure cloud storage (Cloudflare R2). A record is created and background processing begins immediately. Text is extracted from each format and normalized to markdown with page markers (`[[Page N]]`). Scanned PDFs fall back to OCR; large files process asynchronously. Documents are split into page-aware chunks that preserve structure. If the knowledge base has an [extraction schema](/features/extraction-schemas), an AI model also writes structured JSON for each file. Each chunk is embedded in batches using your organization's configured embedding model, producing searchable vectors. Vectors are stored with page numbers and chunk metadata, then indexed for fast similarity search. The file is now searchable. ### Structured Data Extraction Configure your knowledge bases to extract structured information from documents, creating an index of numeric and categorical fields for cross-document analysis: * **Custom JSON Schemas**: Define exactly what data to extract from each file * **AI Model Selection**: Choose which AI model processes your documents * **Automatic Processing**: Extraction happens during file upload * **Cross-Document Queries**: Filter and aggregate across all files without scanning each one For detailed guidance on writing extraction schemas, see [Extraction Schemas](/features/extraction-schemas). ### How Agents Retrieve Knowledge Once a knowledge base is processed, agents reach it through four retrieval tools plus the Python sandbox. Access is always organization-scoped, and you choose how broad it is per agent: either a **selected list** of knowledge bases, or — with the **Allow all knowledge bases** option — every knowledge base in the organization (pair this with `manage_knowledge_bases` so the agent can discover them). **Hybrid retrieval.** Embeds the query, runs vector similarity *and* full-text search, then fuses the rankings. Returns the top-k chunks with file name, page numbers, and similarity scores. Reads a single file front-to-back — pass `kb:` to read a knowledge-base file. Text is line-paginated; PDF pages can be returned as inline images for multimodal models. Inventories a knowledge base — file names, sizes, status, and chunk counts — with regex filters. How an agent discovers what's available before reading. Saves attachments or generated content back into a knowledge base, re-triggering the full pipeline. Gated by a separate writable allowlist. Each search result includes the matching content, source file and page numbers, a similarity score, and the method that found it (semantic vs. text). Agents can also restrict a search to specific files or exclude outdated ones. ## Getting Started ### Creating a Knowledge Base 1. Navigate to **Control Hub** → **Knowledge Bases** 2. Click **"Create Knowledge Base"** 3. Configure your settings: * **Name & Description**: Help your team understand the content * **Embedding Model**: Choose from your organization's configured models * **Extraction Schema**: Optional JSON schema for structured data extraction ### Uploading Documents * **Drag & Drop**: Simply drag files into the knowledge base interface * **Bulk Upload**: Select multiple files at once * **Real-time Processing**: Watch files process with live status updates * **Processing Status**: See extraction progress and any errors ### Email Documents to Your Knowledge Base Every knowledge base has a unique email address that you can use to add documents without opening the app. **How to use:** 1. Find your KB's email address in the upload area (e.g., `kb-123@updates.asteragents.com`) 2. Send an email to that address 3. **With attachments**: Documents are automatically added and processed 4. **Without attachments**: The email body is saved as a `.md` file with subject, sender, and timestamp metadata **Security:** * Only organization members can add documents via email * Sender email is verified against your team's Clerk user accounts * Unauthorized senders are silently ignored **Use cases:** * Forward emails with attachments directly to your KB * **Email notes and updates** to keep a knowledge base current (e.g., interaction logs, meeting notes) * Add documents from your phone without logging in * Set up automated workflows that email documents to knowledge bases * Quickly share files from any device with email access ### Trigger Agents on File Upload Knowledge bases can automatically start an AI agent conversation whenever a file finishes processing. This enables powerful document automation workflows. **How to configure:** 1. Go to your knowledge base settings (click edit) 2. Enable "Trigger Agent on File Upload" 3. Select which agent should process the documents 4. Write instructions telling the agent what to do with the document **What the agent receives:** * The full extracted text content of the document * Structured extraction data (if you've configured an extraction schema) * The filename and knowledge base context **Example instructions:** ``` Analyze this document and: 1. Summarize the key points in 3-5 bullet points 2. Extract any action items or deadlines mentioned 3. Identify the document type (invoice, contract, report, etc.) ``` **Viewing triggered conversations:** * Files that triggered a conversation show a "View Conversation" option in their menu * The conversation is linked to the file for easy reference **Use cases:** * **Invoice Processing**: Automatically extract line items and totals from uploaded invoices * **Contract Analysis**: Summarize key terms and flag important clauses * **Report Summarization**: Generate executive summaries of lengthy documents * **Content Routing**: Have an agent read documents and route them to appropriate teams **Notes:** * Triggers fire for all upload methods: drag-and-drop, bulk upload, and email-to-KB * Only files uploaded by organization members trigger conversations (the uploader becomes the conversation owner) * If a file fails processing, no trigger fires until the file is successfully processed **Need time-based automation instead of file-based?** Use [Scheduled Tasks](/features/scheduled-tasks) to run agents on a recurring schedule (daily, weekly, etc.). For example, schedule a nightly task that searches a knowledge base for new documents and emails a digest to your team. ### Configuring Agents Once your knowledge base is ready: 1. Go to your agent configuration 2. Enable the **"Search Knowledge Base"** tool 3. Your agent can now access and search your documents during conversations ## Agent Integration ### Natural Language Queries Your agents can search using natural language: * *"Find information about our refund policy"* * *"What does the Q3 financial report say about revenue growth?"* * *"Show me technical specifications for our new product"* ### Advanced Search Options Agents can also use advanced filtering: * Search only within specific files * Exclude outdated documents * Control the number of results returned * Get detailed metadata about search results ### Search Results Include * **Relevant Content**: The actual text chunks that match the query * **Source Information**: File names, page numbers, and document metadata * **Similarity Scores**: How relevant each result is to the query * **Search Method**: Whether found via semantic or text search ## Working with KB Data in Python When an agent has `execute_python` enabled, it can pull KB files into the Python sandbox for bulk processing. Files are mounted **on request**, not automatically. ### How files get into the sandbox Request files via the `kb_files` parameter on the `execute_python` call (format `kb/{kb_id}/{filename}`). They then appear at `/home/user/kb/{kb_id}/`: * **Original files** — the uploaded documents (PDFs, Excel, `.docx`, etc.) * **`.md` files** — pre-extracted markdown text, auto-included alongside each requested file * **`extracted_data.json`** — structured extraction results for all files in each accessible KB; available even when no individual files are requested (if an extraction schema is configured) Files are **not** pre-loaded — `/home/user/kb/{kb_id}/` doesn't exist until you request a file into it. Use `list_kb_files` to discover exact filenames, then pass them in `kb_files`. You can request files from any knowledge base in your organization. ### Bulk processing pattern For agents that process many documents at once (financial spreading, portfolio analysis, document comparison), request the files you need in one call and read their local `.md` files in Python — significantly faster than reading each file individually: ```python theme={null} import json # Load structured index to filter files (extracted_data.json needs no explicit request) with open('/home/user/kb/{kb_id}/extracted_data.json') as f: files = json.load(f) # Filter to what you need target_files = [f for f in files if f.get('status') == 'APPROVED'] # Request those files via kb_files on this call, e.g. # kb_files=[f"kb/{kb_id}/{e['fileName']}" for e in target_files] # then read their .md companions directly — no per-file round-trips for entry in target_files: with open(f"/home/user/kb/{kb_id}/{entry['fileName']}.md") as f: content = f.read() # Parse and process... ``` **When to use each approach:** * **Local `.md` files** — bulk reads of 10+ documents * **`extracted_data.json`** — filtering, indexing, and summary metrics across all files * **`search_knowledge_base`** — finding specific content when you don't know which file has the answer * **`read_file`** (`kb:`) — focused reads of 1-3 files, or when you need page images For more details, see [Run Code — Knowledge base file access](/tools/execute_python#knowledge-base-file-access). ## Use Cases ### Customer Support * Upload FAQs, product manuals, and policy documents * Agents can instantly find answers to customer questions * Ensure consistent, accurate responses across your team ### Research & Analysis * Store research papers, market reports, and analysis documents * Agents can synthesize information across multiple sources * Extract insights and trends from large document collections ### Technical Documentation * Upload API docs, system specifications, and troubleshooting guides * Agents can help with code reviews and technical questions * Keep documentation searchable and accessible ### Compliance & Legal * Store contracts, regulations, and compliance documents * Agents can quickly reference relevant policies and procedures * Ensure adherence to legal requirements and standards ## Integration-Managed Knowledge Bases Some knowledge bases are automatically populated by external integrations (e.g., Salesforce, SharePoint, or custom sync services). These are called **integration-managed** knowledge bases. ### How to Identify * A badge appears next to the knowledge base name showing the integration source * An info banner displays at the top of the knowledge base detail page * Example: "Managed by Salesforce" ### What's Different | Feature | User-Managed KB | Integration-Managed KB | | ----------------------- | --------------- | ------------------------------- | | Upload files | ✅ Yes | ❌ No (synced automatically) | | Delete files | ✅ Yes | ❌ No (synced automatically) | | Retry failed processing | ✅ Yes | ✅ Yes | | Search & query | ✅ Yes | ✅ Yes | | View extracted data | ✅ Yes | ✅ Yes | | Delete knowledge base | ✅ Yes | ❌ No (via integration settings) | ### Why This Matters Integration-managed KBs are kept in sync with external systems. If you were to manually upload or delete files, those changes would be lost on the next sync. The UI protections ensure your data stays consistent with the source system. ## Organization & Management ### Organization-Scoped * Each knowledge base belongs to your organization * Admin controls for secure document management * Team members see only knowledge bases they have access to ### File Management * View all uploaded files with processing status * Remove outdated or incorrect documents * Monitor storage usage and document counts ### Performance Monitoring * Track search usage and performance * Monitor embedding generation status * View extracted structured data ## Best Practices ### Document Organization 1. **Create Topic-Specific Bases**: Separate knowledge bases for different subject areas 2. **Use Descriptive Names**: Clear names help agents and users understand content 3. **Regular Updates**: Remove outdated documents to maintain search quality 4. **Consistent Formatting**: Well-formatted documents produce better search results ### Search Optimization 1. **Structured Content**: Use headings, bullet points, and clear sections 2. **Complete Information**: Include context and background in documents 3. **Avoid Duplicates**: Multiple versions of the same content can confuse search 4. **Test Searches**: Verify your agents can find key information ### Security Considerations 1. **Sensitive Data**: Only upload documents appropriate for AI processing 2. **Access Controls**: Use organization-level access management 3. **Regular Audits**: Review uploaded content periodically 4. **Compliance**: Ensure uploaded documents comply with your data policies ## API Integration Knowledge bases integrate seamlessly with the Aster Agents API. Use the search functionality programmatically or build custom workflows that leverage your document collections. For detailed API documentation, see the [API Reference](/api-reference) section. *** Transform your documents into searchable knowledge that your agents can access instantly. Knowledge bases make your information work harder for your team, providing AI-powered insights from your existing documentation and files.