Set Up a Knowledge Base
Give an agent a set of documents to search and answer from.
What you need
- An agent already created (or you can add a KB while creating a new agent).
- Your content: files (PDF, DOCX, MD, TXT, HTML) or web URLs.
- Available KB quota — each admin account has a maximum number of Knowledge Bases.
Each agent supports one Knowledge Base only. This limit is shown in the agent editor's Knowledge Base Integration section subtitle.
Steps
1. Open the agent editor
Open an existing agent for editing, or start creating a new one. Scroll down to the Knowledge Base Integration section (visible in the editor at all times).
2. Fill in the Knowledge Base details
The inline form is always present in the editor — there is no separate button to add a KB. Fill in:
- Knowledge Base Name — required. E.g., "Product Documentation".
- Description — a short note about the content.
3. Add content
Click Add Documents. You can:
- Upload files — select documents (PDF, DOCX, TXT, MD, HTML) from your computer.
- Add web URLs — paste URLs (one per line, e.g.,
https://example.com/docs). The platform crawls and indexes the page.
You can mix files and URLs in the same KB.
4. Save the agent
Click Update Agent (or Create Agent for new agents).
Behind the scenes the platform creates the Knowledge Base, ingests every file and URL, and embeds the chunks. This takes a few minutes.
5. Watch the status
The KB row in the editor shows a status chip:
| Status | Meaning |
|---|---|
| Setting Up | Initial creation, chunking, embedding. |
| Updating | New content is being processed. |
| Configured | Ready. The agent can search and answer from this KB. |
| Failed | Click the row to see the error. |
You can also monitor progress on the Tool Configuration page — the KB appears there alongside remote tools with the same status chips.
6. Test
Once the status reaches Configured, click Share on the agent's card → Start chatting. Ask a question specific to your content. The agent retrieves relevant chunks automatically.
Recommended models
When a KB is attached, the dashboard suggests Anthropic Claude models:
"For better performance with larger Knowledge Bases, we recommend using Anthropic Claude Models."
Claude handles long retrieved contexts well. Other models work too — Claude is the safe default.
Updating content
- Add new files / URLs → click Update Agent — they are ingested and added.
- Remove a file / URL → save — that content is no longer searchable.
- Re-upload a file → replaces the old version.
Customizing chunking and retrieval (advanced)
Most admins should leave this alone — the defaults work well. If you need to override chunking strategy, retrieval count, or reranking, switch to Advanced mode in the agent editor and edit the KnowledgeBaseIntegrationAndRetrieval block. See Advanced Mode.
Quotas
When you hit your KB quota:
- The Add Documents area may be disabled.
- You'll see: "Cannot add more than N knowledge bases per user. You currently have M."
Contact your platform admin to raise the cap.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| Status stays at "Setting Up" for a long time | Large file count or big web crawl. Check the Tool Configuration page for per-step progress. |
| Status: Failed | Click the row for the error. Common causes: source URL not reachable, unsupported file format, region permissions issue. |
| Agent ignores the KB | KB is still ingesting (only Configured KBs are searched), or the question doesn't surface relevant chunks. Try more specific questions and check your source material. |
| Wrong answers | Usually source quality or the system prompt, not retrieval. Check what the agent is citing — if the citation is right but the answer is wrong, fix the prompt; if the citation is wrong, fix the content. |
Tips
- Smaller, focused KBs work better. A 50-page focused manual outperforms a 5,000-page archive of mixed content.
- Use clean source material. Avoid PDFs that are scanned images — use native text formats where possible.
- One KB per agent. Each agent has one KB. If different audiences need different content, create separate agents.
- Don't put per-user data in a KB. KBs are shared across all users of the agent. Use a tool that scopes to the individual user instead.