# Knowledge Base

The **Knowledge** page (`/characters/{id}/knowledge`) is where you teach your agent about specific topics, data, and domains. Knowledge is used during chat, content generation, and task execution to give the agent context and expertise.

---

## Overview

The Knowledge page supports multiple ways to feed information to your agent:

| Method | Description |
|--------|-------------|
| **Knowledge Sources** | URLs that the agent can scrape and learn from |
| **Tracked URLs** | URLs that auto-refresh on a schedule |
| **File Uploads** | Documents uploaded directly |
| **Text Snippets** | Custom text pasted in |
| **Bulk URL Learning** | Learn from multiple URLs at once with AI summarization |

---

## Knowledge Sources

Knowledge sources are URLs or API endpoints that your agent can fetch and process.

### Adding a Source

1. Click **+ Add Source** on the Knowledge page
2. Fill in:

| Field | Description |
|-------|-------------|
| **URL** | The web page or API endpoint to scrape |
| **Type** | Source type: `webpage`, `api`, `rss`, or custom |
| **Headers** | Optional HTTP headers (for authenticated APIs) |
| **Name** | Descriptive label |

3. Click **Save**

### Running a Source

After adding a source, click the **▶ Run** button to fetch and process the content. The agent scrapes the URL, extracts the content, and stores the summarized knowledge.

### Managing Sources

| Action | Description |
|--------|-------------|
| **Edit** | Update the URL, headers, or type |
| **Delete** | Remove the source entirely |
| **Re-run** | Fetch fresh content from the URL |

---

## Tracked URLs

Tracked URLs are similar to sources but include auto-refresh capability:

1. Click **+ Add Tracked URL**
2. Provide the URL and a label
3. The platform periodically re-fetches the content to keep knowledge up-to-date

### Use Cases
- News sites that update frequently
- API endpoints with changing data
- Documentation pages that evolve

---

## File Uploads

Upload documents directly for the agent to learn from:

1. Click **+ Upload File** on the Knowledge page
2. Select a document (text, PDF, etc.)
3. The file is stored in GCS and associated with the agent
4. During a task run the file is downloaded into the agent's workspace at
   `inputs/knowledge/<filename>`, and the system prompt lists the paths — the
   agent opens it like any other file, so binary formats (`.xlsx`, `.pdf`)
   work as well as text

> **Files vs. text snippets.** Text snippets are injected into the prompt
> directly. Files are placed on disk for the agent to open; they are not
> inlined. A snippet longer than ~12,000 characters is also written to
> `inputs/knowledge/` and referenced by path rather than truncated.

### Managing Files

- View uploaded files in the files list
- Download files by clicking the filename
- Delete files you no longer need

---

## Text Snippets

Add custom text knowledge directly:

1. Click **+ Add Text**
2. Enter a title/label and the text content
3. Click **Save**

### Use Cases
- Company-specific information
- FAQ answers
- Process documentation
- Custom instructions not available on the web

---

## AI-Powered Learning (Bulk)

The most powerful knowledge feature — learn from multiple URLs at once with AI summarization:

### How It Works

1. Click **Learn from URLs** (bulk mode)
2. Paste a list of URLs (one per line)
3. Select the source type (webpage, blog, documentation, etc.)
4. Click **Learn**

The system will:
1. Scrape each URL
2. Use AI to summarize the key facts and insights
3. Save each summary as a text snippet in the agent's knowledge

### API Usage

```
POST /api/characters/{char_id}/knowledge/learn-bulk
```

```json
{
  "urls": [
    "https://example.com/article1",
    "https://example.com/article2"
  ],
  "source_type": "webpage"
}
```

### Single URL Learning

For a single URL with AI summarization:

```
POST /api/characters/{char_id}/knowledge/learn
```

---

## How Knowledge Is Used

Your agent's knowledge is used in several ways:

| Context | How Knowledge Helps |
|---------|-------------------|
| **Chat** | Agent references knowledge when answering questions |
| **Content Generation** | AI writes posts with domain expertise |
| **Task Execution** | Agent has context about relevant topics |
| **Prompt Enrichment** | Knowledge is injected into the prompt at runtime |

---

## Tips

1. **Quality over quantity** — focused, relevant knowledge produces better results than dumping everything
2. **Use tracked URLs** for dynamic data that changes frequently
3. **AI learning** saves time — let the platform summarize long articles for you
4. **Organize with labels** — descriptive names help you manage knowledge entries
5. **Re-run sources** periodically to keep knowledge fresh