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.A knowledge base can also be a Data Store — a
structured SQL database your agents manage and your apps read and write live —
instead of a document collection. Use a document KB to cite source material;
use a data store to track state that changes (pipelines, trackers, logs).
This page covers document knowledge bases; see Data Stores
for the structured type.
From uploaded documents to agent-ready knowledge — ingestion, storage, and the retrieval tools agents use on top.
Key Features
Multi-Format Document Support
Upload documents in various formats and your agents will automatically understand the content:
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 asextracted_data.json.
Upload
Files are uploaded directly to secure cloud storage (Cloudflare R2). A record is created and background processing begins immediately.
Parse → Markdown
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.Chunk & Extract
Documents are split into page-aware chunks that preserve structure. If the knowledge base has an extraction schema, an AI model also writes structured JSON for each file.
Embed
Each chunk is embedded in batches using your organization’s configured embedding model, producing searchable vectors.
Store & Index
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
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 withmanage_knowledge_bases so the agent can discover them).
search_knowledge_base
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.
read_file
Reads a single file front-to-back — pass
kb:<file_id> to read a knowledge-base file. Text is line-paginated; PDF pages can be returned as inline images for multimodal models.list_kb_files
Inventories a knowledge base — file names, sizes, status, and chunk counts — with regex filters. How an agent discovers what’s available before reading.
write_to_knowledge_base
Saves attachments or generated content back into a knowledge base, re-triggering the full pipeline. Gated by a separate writable allowlist.
Getting Started
Creating a Knowledge Base
- Navigate to Control Hub → Knowledge Bases
- Click “Create Knowledge Base”
- 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:- Find your KB’s email address in the upload area (e.g.,
kb-123@updates.asteragents.com) - Send an email to that address
- With attachments: Documents are automatically added and processed
- Without attachments: The email body is saved as a
.mdfile with subject, sender, and timestamp metadata
- Only organization members can add documents via email
- Sender email is verified against your team’s Clerk user accounts
- Unauthorized senders are silently ignored
- 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:- Go to your knowledge base settings (click edit)
- Enable “Trigger Agent on File Upload”
- Select which agent should process the documents
- Write instructions telling the agent what to do with the document
- The full extracted text content of the document
- Structured extraction data (if you’ve configured an extraction schema)
- The filename and knowledge base context
- Files that triggered a conversation show a “View Conversation” option in their menu
- The conversation is linked to the file for easy reference
- 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
- 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
Configuring Agents
Once your knowledge base is ready:- Go to your agent configuration
- Enable the “Search Knowledge Base” tool
- 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 hasexecute_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 thekb_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.) .mdfiles — pre-extracted markdown text, auto-included alongside each requested fileextracted_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)
/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:
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
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
Scope Each Base to a Topic
Search returns the top matching chunks from across the entire knowledge base, so a base holding every document your company owns makes each individual answer worse. Separate bases by subject — one per product line, policy area, or client — and name them so both people and agents can tell them apart from the name alone. An agent can be given several.Keep One Current Copy of Each Document
Retrieval is hybrid: it runs semantic and full-text search and fuses the rankings. It has no notion of which version of a document is the current one. If v1 and v2 of the same manual both sit in a base, both compete for the same top-k slots and an agent can cite the retired procedure. So keep exactly one copy of each document and let your document system hold the history. When a document changes, remove the old file and upload the replacement — reprocessing re-runs the pipeline over the file already stored, so it will not pick up a newer version of the same document. On an integration-managed base the sync handles this for you, which is the main reason to prefer one.Feed From the Source System Where You Can
Documents that live somewhere else — SharePoint, a DMS, a portal — are best synced into the knowledge base rather than uploaded by hand, so the base can’t fall behind the source. A synced base is marked integration-managed, which turns off manual upload and deletion so nobody can put it out of step. For lighter cases, emailing documents to the base keeps it current without anyone opening the app.Use an Extraction Schema for Anything You Want to Compare
Search is the right tool for “what does our policy say about X.” It is the wrong tool for “which of these 400 contracts renew this quarter.” Set an extraction schema on the base and the same fields are pulled from every file at upload, so agents can filter and aggregate across the whole base without reading each document. If what you’re storing is state that changes rather than source material to cite, use a Data Store instead.Test Retrieval, Not Just Upload
A file showing completed means it parsed, chunked and embedded. It does not mean an agent can find what you need. After loading a base, ask the agent the questions its users will actually ask and check the citations it returns. Badly scanned PDFs, spreadsheets whose meaning lives in the layout, and documents that assume context they never state are the usual causes when the answer is there but retrieval misses it.Treat the Organization as the Access Boundary
Knowledge bases are scoped to your organization. Restricting an agent to a list of bases narrows what that agent reaches, but it is a configuration choice rather than a security control — anyone in the organization who can use a knowledge-base-enabled agent can reach the content. Put material that only some of your people should see in a separate organization, not a separate knowledge base.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 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.