> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xuna.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Add a knowledge base to ground your agent's responses
> Upload files, URLs, or text snippets to give your agent accurate, retrievable information using retrieval-augmented generation (RAG).
A knowledge base lets your agent answer questions grounded in your own content. When a user asks something, the platform retrieves the most relevant passages from your documents and injects them into the context before the LLM responds. This is retrieval-augmented generation (RAG), and it significantly reduces hallucination for domain-specific questions.
## Document types
You can add content to a knowledge base in three ways:
| Type | Supported formats | Max size |
| -------- | -------------------------------- | -------------- |
| **File** | PDF, TXT, DOCX, HTML, EPUB | 21 MB per file |
| **URL** | Any publicly accessible web page | — |
| **Text** | Plain text pasted directly | — |
On non-enterprise plans, the total knowledge base size per agent is limited to **20 MB or 300,000 characters**, whichever is reached first.
## Add documents via dashboard
Go to the [XUNA AI dashboard](https://xuna.ai/app/conversational-ai) and select your agent.
Click the **Knowledge base** tab in the agent settings.
Click **Add document** and choose **File**, **URL**, or **Text**. Fill in the required fields and click **Save**.
The document status changes from **Indexing** to **Ready** when retrieval is available. Large files may take a minute or two.
## Add documents via API
Create documents and attach them to an agent programmatically using the Python SDK.
```python create-from-text.py theme={null}
from xuna_ai import XunaAI
client = XunaAI()
# Create a document from text
doc_text = client.conversational_ai.knowledge_base.documents.create_from_text(
text="The airspeed velocity of an unladen swallow is 24 mph.",
name="Unladen Swallow facts",
)
```
```python create-from-url.py theme={null}
from xuna_ai import XunaAI
client = XunaAI()
# Create a document from a URL
doc_url = client.conversational_ai.knowledge_base.documents.create_from_url(
url="https://en.wikipedia.org/wiki/Unladen_swallow",
name="Unladen Swallow Wikipedia page",
)
```
```python create-from-file.py theme={null}
from xuna_ai import XunaAI
client = XunaAI()
# Create a document from a file
doc_file = client.conversational_ai.knowledge_base.documents.create_from_file(
file=open("/path/to/facts.txt", "rb"),
name="Facts",
)
```
After creating documents, attach them to your agent:
```python attach-to-agent.py theme={null}
from xuna_ai import XunaAI
client = XunaAI()
agent = client.conversational_ai.agents.update(
agent_id="your-agent-id",
conversation_config={
"agent": {
"prompt": {
"knowledge_base": [
{"type": "text", "name": doc_text.name, "id": doc_text.id},
{"type": "url", "name": doc_url.name, "id": doc_url.id},
{"type": "file", "name": doc_file.name, "id": doc_file.id},
]
}
}
}
)
```
Create documents and attach them to an agent using the TypeScript SDK.
```typescript create-from-text.ts theme={null}
import { XunaAIClient } from "@xuna-ai/xuna-ai-js";
const client = new XunaAIClient();
// Create a document from text
const docText = await client.conversationalAi.knowledgeBase.documents.createFromText({
name: "Unladen Swallow facts",
text: "The airspeed velocity of an unladen swallow is 24 mph.",
});
```
```typescript create-from-url.ts theme={null}
import { XunaAIClient } from "@xuna-ai/xuna-ai-js";
const client = new XunaAIClient();
// Create a document from a URL
const docUrl = await client.conversationalAi.knowledgeBase.documents.createFromUrl({
name: "Unladen Swallow Wikipedia page",
url: "https://en.wikipedia.org/wiki/Unladen_swallow",
});
```
```typescript create-from-file.ts theme={null}
import fs from "node:fs";
import { XunaAIClient } from "@xuna-ai/xuna-ai-js";
const client = new XunaAIClient();
// Create a document from a file
const file = new File(
[fs.readFileSync("/path/to/facts.txt")],
"facts.txt",
{ type: "text/plain" }
);
const docFile = await client.conversationalAi.knowledgeBase.documents.createFromFile({
name: "Facts file",
file,
});
```
After creating documents, attach them to your agent:
```typescript attach-to-agent.ts theme={null}
import { XunaAIClient } from "@xuna-ai/xuna-ai-js";
const client = new XunaAIClient();
await client.conversationalAi.agents.update("your-agent-id", {
conversationConfig: {
agent: {
prompt: {
knowledgeBase: [
{ type: "text", name: docText.name, id: docText.id },
{ type: "url", name: docUrl.name, id: docUrl.id },
{ type: "file", name: docFile.name, id: docFile.id },
],
},
},
},
});
```
## Best practices
Rather than uploading one large document, split content into smaller, focused files. Retrieval works by matching user queries to document chunks — smaller, topic-focused documents improve match quality.
Name documents clearly (e.g., "Return policy — US", "Product specs — Model X"). The retriever uses document names as signals during ranking.
URL-based documents are fetched and indexed at creation time, not on every conversation. Re-add the document if the source page changes significantly.
Use the knowledge base for reference content (FAQs, product specs, policies). Keep behavioral instructions in the [system prompt](/configure/system-prompt) — they are always in context, not retrieved.
After adding documents, start a test conversation and ask questions that should be answered from the knowledge base. Check the [conversation transcript](/monitor/conversation-analysis) to see which passages were retrieved.